agent-toggle

A TypeScript CLI to enable or disable the MCP servers (grouped by function), plugins, skills, hooks, commands and subagents of every AI agent CLI installed on the machine, at the user level, the project level, or both.

Installation

Requires Node.js 22 or later.

npx agent-toggle                  # run it once, without installing
npm install -g agent-toggle       # or install the agent-toggle command
agent-toggle                      # interactive menu, run it in the project folder you want
agent-toggle --version            # installed version

To update: npm install -g agent-toggle@latest. With pnpm: pnpm dlx agent-toggle to run it once, pnpm add -g agent-toggle to install it.

Usage

39 agent CLIs are supported. The menu and agents only show the ones detected on the machine (a binary on the PATH or a characteristic config folder); agents --all lists them all. The menu lists every detected agent, plus a cross view: the MCP servers of all agents in a single list, grouped by function.

The interface is a full-screen terminal UI (Ink): a trail at the top shows where you are (Home › agent › category › scope), items are grouped in collapsible groups with a details panel, and every change goes through a review screen.

| Key | Action | |---|---| | ↑ ↓ / PgUp PgDn | move | | → / ← | expand / collapse a group | | space | toggle an item, or a whole group | | / | search the items (menus filter as you type) | | a | expand / collapse all groups | | enter | choose, continue, apply | | esc | back to the previous screen (quits from Home) | | Ctrl+C | quit |

The mouse works too: the wheel moves through a list, a click chooses a menu entry, ticks an item, opens a group (or ticks the whole group on its checkbox), and the key hints at the bottom are buttons. A click on an earlier screen of the trail at the top goes back to it. The interface then runs on the terminal's alternate screen; hold Shift to select text, or start with --no-mouse to keep the normal screen.

Commands

agent-toggle agents                                 # detected agents and what is managed
agent-toggle agents --all                           # every supported agent, installed or not
agent-toggle list all mcp                           # MCP servers of every agent
agent-toggle list codex skills
agent-toggle disable codex mcp node_repl
agent-toggle disable grok skills archify -s user
agent-toggle enable cursor mcp supabase -s project
agent-toggle claudeai off                           # claude.ai connectors (Claude Code)
agent-toggle groups                                 # customizable MCP groups
agent-toggle lang                                   # current language and the available ones
agent-toggle lang de                                # save the interface language

Options: -p <dir> (project), -s user|project|local|both|all, -n (dry run), --no-mouse (keyboard only, normal screen), -l <en|fr|es|de> (interface language for this run).

Language

The interface is in English by default. Available: English (en), French (fr), Spanish (es), German (de). The language is resolved in this order:

1. the --lang / -l option;
2. the AGENT_TOGGLE_LANG environment variable;
3. the language saved by agent-toggle lang <code> or by the Language entry of the interactive menu (~/.agent-toggle/config.json);
4. English.

Translations live in src/core/i18n.ts. English is the reference catalog, and the compiler rejects any other catalog that misses a key.

Mechanisms per agent

The agent's native mechanism is used whenever one exists. Otherwise the item is set aside: a JSON entry goes to ~/.agent-toggle/stash.json, a file or directory is moved to <dir>.disabled/. In both cases it is restored exactly as it was.

| Agent | MCP | Plugins | Skills | Hooks | Commands | Agents | |---|---|---|---|---|---|---| | Claude Code | disabledMcpServers (per project, ~/.claude.json); stash for user servers | enabledPlugins | skillOverrides: off | stash + disableAllHooks | move | move | | Codex | [mcp_servers.x] enabled = false | [plugins."p@m"] enabled | [[skills.config]] enabled = false | stash (hooks.json) | prompts: move | .toml: move | | Grok Build | disabled_mcp_servers (every source); project: enabled = false | grok plugin enable/disable | [skills] disabled | hooks/*.json files: move | move | move | | Cursor Agent | disabled: true | — (IDE) | link moved | stash (hooks.json) | move | move | | Copilot CLI | disabledMcpServers | enabledPlugins | disabledSkills | stash + disableAllHooks; files: move | — | subagents.disabledSubagents | | Devin CLI | disabled: true | — | move | stash | — | move | | Antigravity (agy) | disabled: true | plugins.<p>.enabled | move | <hook>.enabled = false | — | — | | Gemini CLI | mcp.excluded | — | skills.disabled | stash + hooksConfig.enabled | move | agents.overrides.<n>.enabled | | Qwen Code | mcp.excluded | — | skills.disabled | stash + disableAllHooks | slashCommands.disabled | move | | Factory Droid | disabled: true | enabledPlugins | disabledSkills | stash + hooksDisabled | move | droids: move | | OpenCode | mcp.<n>.enabled = false | files: move | permission.skill.<n> = deny | — (plugins) | move | agent.<n>.disable | | Amp | stash (no native flag) | files: move | move | — (plugins) | — | — | | Crush | disabled: true | — | options.disabled_skills | stash | — | — | | Kiro CLI | disabled: true | — | move | — | prompts: move | .json: move | | Kilo Code CLI | mcp.<n>.enabled = false | files: move | move | — (plugins) | move | agent.<n>.disable | | Amazon Q CLI (legacy Kiro) | disabled: true | — | — | — | prompts: move | cli-agents/*.json: move | | Goose | extensions.<n>.enabled: false (YAML) | disabledPlugins | — (plugins) | — (plugins) | — | — | | Cline CLI | disabled: true | — | SKILL.md frontmatter disabled: true | hook files: move | workflows: move | move | | Continue CLI | stash (YAML array, no flag) | — | move | stash + disableAllHooks | — | — | | Augment Auggie | stash | enabledPlugins | move | stash | move | move | | JetBrains Junie | stash | — | move | stash | move | move | | OpenHands CLI | enabled: false | — | move | — | — | move | | Kimi CLI | stash | plugin folders: move | move | — | — | — | | Mistral Vibe | [[mcp_servers]] disabled = true | — | disabled_skills | — | — | disabled_agents | | Rovo Dev CLI | mcp.disabledMcpServers (YAML) | — | move | — | — | subagents: move | | Qoder CLI | stash | — | move | — | move | move | | CodeBuddy Code | stash | enabledPlugins | move | stash | move | move | | Letta Code | — (per agent, use /mcp) | mods: move | move | stash + hooks.disabled | move | move | | Pi coding agent | — (no MCP) | extensions: move | move | — | prompt templates: move | — | | Codebuff | stash (strict schema) | — | — | — | — | — | | Hermes Agent | mcp_servers.<n>.enabled: false (YAML) | — | move | — | — | — | | Command Code | stash | — | — | stash | — | — | | Windsurf | stash | — | — | — | — | — | | Trae Agent | allow_mcp_servers allow-list (YAML) | — | — | — | — | — | | iFlow CLI (discontinued) | excludeMCPServers | — | — | stash | move | move | | Qodo Command (deprecated) | stash (project mcp.json) | — | — | — | — | — | | Aider, Plandex | detected, nothing to toggle | | | | | | | Warp / Oz | state kept inside the app: nothing is managed | | | | | |

Good to know

• Shared skills. Cursor, Kiro, Amp and Antigravity have no per-skill switch, so a skill is disabled by moving its folder (or link). If your skill folders are links to a shared store such as ~/.agents/skills, only the link moves, and a script that syncs those links would recreate it. Codex, Grok, Copilot, Qwen, Droid, OpenCode and Crush have a native setting that leaves the files in place.
• Project config and trust. Codex and Grok only read a project's config when the folder is "trusted".
• Formats are preserved. JSON/JSONC is edited path by path, comments included (jsonc-parser); YAML through the yaml document API, comments included. TOML is edited line by line and never rewritten as a whole. A disable/enable round trip gives back an identical file.
• Backups. Each modified file is copied to ~/.agent-toggle/backups/, which keeps the last 20 copies.

MCP server groups

Default groups use stable ids: web, docs, browser, data, apps, design, media, productivity, comms, pm, other. Their labels follow the interface language. Run agent-toggle groups, then edit ~/.agent-toggle/groups.json. A custom group name is displayed as-is, and overrides can target a default id or a custom name:

{
  "groups": { "My tools": ["jina", "/^deep/"] },
  "overrides": { "claude.ai Splice": "media" }
}

• Undocumented switches. When an agent has no documented native switch, the safe fallback is used (stash, or <dir>.disabled/) rather than a guessed key: some agents (Codebuff, Trae) reject unknown keys.

Development

The repository uses pnpm (pnpm-lock.yaml); end users only need npm.

pnpm install
pnpm dev              # run from the sources (tsx), e.g. pnpm dev -n for a dry run
pnpm run typecheck
pnpm run build        # compiles to dist/
npm link              # makes the local build the global agent-toggle command

npm publish rebuilds dist/ first (prepack).

Adding an agent

Write an adapter in src/agents/, an Agent object that describes how the agent is detected and its sections, then add it to AGENTS in src/agents/index.ts. The generic sections cover most cases: mcpSection, listSection, boolMapSection, hooksSection and dirSection (in src/core/generic.ts), plus tomlFlagSection and tomlListSection. User-facing text goes through t() with a key added to all four catalogs.