Skip to main content
Plugins extend 0x0 by hooking into the session lifecycle, adding custom tools, modifying LLM parameters, and more.

​
Plugin function

A plugin is a function that receives context and returns a hooks object: 
import type { Plugin } from '@0x0-ai/plugin'

const myPlugin: Plugin = async (input) => {
  // input.client    -- SDK client for the 0x0 API
  // input.project   -- current project info
  // input.directory  -- project directory path
  // input.worktree   -- git worktree root
  // input.serverUrl  -- local server URL
  // input.$          -- Bun shell for running commands

  return {
    // hooks go here
  }
}

export default myPlugin

​
Where plugins are loaded from

Plugins are loaded from multiple sources (low to high priority):
  1. Internal plugins — always loaded (Codex auth, Copilot auth, GitLab auth, Antigravity OAuth)
  2. Built-in npm plugins — installed automatically (e.g., zeroxzero-anthropic-auth)
  3. Config plugin array — npm packages or file URLs specified in config
  4. Local files — .zeroxzero/plugin/*.{ts,js} or .zeroxzero/plugins/*.{ts,js}
Higher-priority plugins with the same canonical name override lower ones.

​
Config example

plugin:
  - my-custom-plugin@1.0.0
  - another-plugin@latest

​
Disabling defaults

Set disable_default_plugins: true in config to skip built-in npm plugins.

​
Hooks reference

​
Core hooks

HookDescription
eventCalled for every internal bus event
configCalled with the resolved config at startup
toolRegister custom tools (return a { [id]: ToolDefinition } map)
authRegister auth methods for a provider

​
Chat hooks

HookDescription
chat.messageModify user messages and parts before processing
chat.paramsModify LLM parameters (temperature, topP, topK, options)
chat.headersAdd or modify HTTP headers for LLM requests

​
Execution hooks

HookDescription
permission.askIntercept permission requests; can auto-allow or auto-deny
command.execute.beforeModify slash command execution before it runs
tool.execute.beforeModify tool arguments before execution
tool.execute.afterModify tool results (title, output, metadata) after execution
shell.envInject environment variables into shell commands

​
Experimental hooks

HookDescription
experimental.chat.messages.transformTransform the full message history before sending to LLM
experimental.chat.system.transformTransform the system prompt array
experimental.session.compactingCustomize compaction prompt and context
experimental.text.completeModify completed text output

​
Custom tools

Register tools via the tool hook using Zod schemas for argument validation: 
import { z } from 'zod'
import type { Plugin } from '@0x0-ai/plugin'

const myPlugin: Plugin = async () => ({
  tool: () => ({
    'my-tool': {
      description: 'A custom tool that does something useful',
      args: {
        query: z.string().describe('The search query'),
        limit: z.number().optional().describe('Max results'),
      },
      async execute(args, context) {
        // context.sessionID    -- current session ID
        // context.messageID    -- current message ID
        // context.agent        -- current agent name
        // context.directory    -- project directory
        // context.worktree     -- git worktree root
        // context.abort        -- AbortSignal for cancellation
        // context.metadata()   -- set result metadata
        // context.ask()        -- request user permission
        return `Result for: ${args.query}`
      },
    },
  }),
})

export default myPlugin

​
Local file plugins

Place .ts or .js files in your project or global plugin directory:
  • Project: .zeroxzero/plugin/my-plugin.ts or .zeroxzero/plugins/my-plugin.ts
  • Global: ~/.zeroxzero/plugin/my-plugin.ts or ~/.zeroxzero/plugins/my-plugin.ts
A plugin module can export multiple plugin functions. Each is initialized independently. If the same function appears as both a named and default export, it is only initialized once.

​
Plugin lifecycle

  • Plugins are initialized at startup after config is resolved.
  • Failed plugin npm installations are retried after a 15-minute backoff.
  • Plugin hooks are called in registration order; results from multiple plugins providing the same hook are merged.

​
See also