Skip to content

plugin.md

Latest commit

 

History

History
278 lines (219 loc) · 10.2 KB

plugin.md

File metadata and controls

278 lines (219 loc) · 10.2 KB
summary Install, configure, and manage FoxFang plugins
read_when
Installing or configuring plugins
Understanding plugin discovery and load rules
Working with Codex/Claude-compatible plugin bundles
title Plugins
sidebarTitle Install and Configure

Plugins

Plugins extend FoxFang with new capabilities: channels, model providers, tools, skills, speech, image generation, and more. Some plugins are core (shipped with FoxFang), others are external (published on npm by the community).

Quick start

```bash foxfang plugins list ``` ```bash # From npm foxfang plugins install @foxfang/voice-call 
# From a local directory or archive
foxfang plugins install ./my-plugin
foxfang plugins install ./my-plugin.tgz
```
```bash foxfang gateway restart ``` 
Then configure under `plugins.entries.\<id\>.config` in your config file.

If you prefer chat-native control, enable commands.plugins: true and use:

/plugin install clawhub:@foxfang/voice-call
/plugin show voice-call
/plugin enable voice-call

The install path uses the same resolver as the CLI: local path/archive, explicit clawhub:<pkg>, or bare package spec (ClawHub first, then npm fallback).

Plugin types

FoxFang recognizes two plugin formats:

Format How it works Examples
Native foxfang.plugin.json + runtime module; executes in-process Official plugins, community npm packages
Bundle Codex/Claude/Cursor-compatible layout; mapped to FoxFang features .codex-plugin/, .claude-plugin/, .cursor-plugin/

Both show up under foxfang plugins list. See Plugin Bundles for bundle details.

If you are writing a native plugin, start with Building Plugins and the Plugin SDK Overview.

Official plugins

Installable (npm)

Plugin Package Docs
Matrix @foxfang/matrix Matrix
Microsoft Teams @foxfang/msteams Microsoft Teams
Nostr @foxfang/nostr Nostr
Voice Call @foxfang/voice-call Voice Call
Zalo @foxfang/zalo Zalo
Zalo Personal @foxfang/zalouser Zalo Personal

Core (shipped with FoxFang)

`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `modelstudio`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - `memory-core` — bundled memory search (default via `plugins.slots.memory`) - `memory-lancedb` — install-on-demand long-term memory with auto-recall/capture (set `plugins.slots.memory = "memory-lancedb"`) `elevenlabs`, `microsoft` - `browser` — bundled browser plugin for the browser tool, `foxfang browser` CLI, `browser.request` gateway method, browser runtime, and default browser control service (enabled by default; disable before replacing it) - `copilot-proxy` — VS Code Copilot Proxy bridge (disabled by default)

Looking for third-party plugins? See Community Plugins.

Configuration

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}
Field Description
enabled Master toggle (default: true)
allow Plugin allowlist (optional)
deny Plugin denylist (optional; deny wins)
load.paths Extra plugin files/directories
slots Exclusive slot selectors (e.g. memory, contextEngine)
entries.\<id\> Per-plugin toggles + config

Config changes require a gateway restart. If the Gateway is running with config watch + in-process restart enabled (the default foxfang gateway path), that restart is usually performed automatically a moment after the config write lands.

- **Disabled**: plugin exists but enablement rules turned it off. Config is preserved. - **Missing**: config references a plugin id that discovery did not find. - **Invalid**: plugin exists but its config does not match the declared schema.

Discovery and precedence

FoxFang scans for plugins in this order (first match wins):

`plugins.load.paths` — explicit file or directory paths. `\/.foxfang/extensions/*.ts` and `\/.foxfang/extensions/*/index.ts`. `~/.foxfang/extensions/*.ts` and `~/.foxfang/extensions/*/index.ts`. Shipped with FoxFang. Many are enabled by default (model providers, speech). Others require explicit enablement.

Enablement rules

  • plugins.enabled: false disables all plugins
  • plugins.deny always wins over allow
  • plugins.entries.\<id\>.enabled: false disables that plugin
  • Workspace-origin plugins are disabled by default (must be explicitly enabled)
  • Bundled plugins follow the built-in default-on set unless overridden
  • Exclusive slots can force-enable the selected plugin for that slot

Plugin slots (exclusive categories)

Some categories are exclusive (only one active at a time):

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable
      contextEngine: "legacy", // or a plugin id
    },
  },
}
Slot What it controls Default
memory Active memory plugin memory-core
contextEngine Active context engine legacy (built-in)

CLI reference

foxfang plugins list                    # compact inventory
foxfang plugins inspect <id>            # deep detail
foxfang plugins inspect <id> --json     # machine-readable
foxfang plugins status                  # operational summary
foxfang plugins doctor                  # diagnostics

foxfang plugins install <package>        # install (ClawHub first, then npm)
foxfang plugins install clawhub:<pkg>   # install from ClawHub only
foxfang plugins install <path>          # install from local path
foxfang plugins install -l <path>       # link (no copy) for dev
foxfang plugins update <id>             # update one plugin
foxfang plugins update --all            # update all

foxfang plugins enable <id>
foxfang plugins disable <id>

See foxfang plugins CLI reference for full details.

Plugin API overview

Plugins export either a function or an object with register(api):

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
    api.registerChannel({
      /* ... */
    });
  },
});

Common registration methods:

Method What it registers
registerProvider Model provider (LLM)
registerChannel Chat channel
registerTool Agent tool
registerHook / on(...) Lifecycle hooks
registerSpeechProvider Text-to-speech / STT
registerMediaUnderstandingProvider Image/audio analysis
registerImageGenerationProvider Image generation
registerWebSearchProvider Web search
registerHttpRoute HTTP endpoint
registerCommand / registerCli CLI commands
registerContextEngine Context engine
registerService Background service

Hook guard behavior for typed lifecycle hooks:

  • before_tool_call: { block: true } is terminal; lower-priority handlers are skipped.
  • before_tool_call: { block: false } is a no-op and does not clear an earlier block.
  • message_sending: { cancel: true } is terminal; lower-priority handlers are skipped.
  • message_sending: { cancel: false } is a no-op and does not clear an earlier cancel.

For full typed hook behavior, see SDK Overview.

Related