agent-toggle

PyPI: https://pypi.org/project/agent-toggle/

Temporarily disable and restore AI-agent resources — skills, agents, commands, rules, plugins (mods included), MCP servers — across Claude Code, Codex, Grok CLI, OpenCode, OpenClaw, Copilot, Vibe, Devin and Antigravity — and show what each one costs at session start.

It ships in two forms: a CLI (agent-toggle, all harnesses) and a Claude Code mod (the /agent-toggle pane, claude harness only; see Claude Code pane mod). Both drive the same toggle engine and state.

Nothing is ever deleted. Everything is parked and recorded, and enable puts it back where it came from.

At a glance

agent-toggle ui: one list per harness, with what each resource costs in tokens. Toggle rows, see the token change before you apply it, and apply it as one batch that undo reverses (Interactive picker).

agent-toggle config: every setting in one menu. Turn harnesses on or off and set the language, update check and Telegram notifications. It also runs tools such as doctor and undo (Settings & config menu).

/agent-toggle inside Claude Code: the same picker as a pane. Search, then turn skills, MCP servers, plugins and mods on or off without leaving the session; each toggle applies at once and queues the matching reload (Claude Code pane mod).

Why

Install

Latest release, from PyPI:

uv tool install agent-toggle
agent-toggle --version

Straight from this repository, pinned to a release tag (replace vX.Y.Z with one from tags; an unpinned git+ URL installs whatever is on the default branch):

uv tool install git+https://github.com/weskao/agent-toggle@vX.Y.Z
agent-toggle --version

Alternatively, use pipx:

pipx install agent-toggle             # from PyPI; or: pipx install git+https://github.com/weskao/agent-toggle@vX.Y.Z

From a checkout, either install it editable or run it in place:

git clone https://github.com/weskao/agent-toggle agent-toggle
cd agent-toggle
pip install -e .                       # puts the `agent-toggle` console script on PATH
python3 agent_toggle.py status         # no install needed; same CLI

Python 3.10+, no runtime dependencies. Then write the skill shim:

agent-toggle install-shims             # installed, or: ./install.sh (a thin wrapper)
python3 agent_toggle.py install-shims  # from a checkout

install-shims writes a thin skill shim (skills/agent-toggle/SKILL.md) into every installed harness that supports skills, so /agent-toggle works from any of them. The shim calls agent-toggle on PATH and never a checkout path, so install the package (or pip install -e .) before relying on it. It writes nothing else into a harness home: parked items live under ~/.agent-toggle/parked/, so a harness-home .gitignore needs no park-dir line. Older versions appended <dir>-disabled/ lines there; inside a git work tree, install-shims reports such stale lines once migrate has emptied the dir they covered, asks y/n on a terminal, removes them without asking with --gitignore, and skips the check with --no-gitignore (--dry-run only reports; every other line is kept byte for byte). Each harness gets its own template from agent_toggle/shims/<harness>.md.tmpl, else generic.md.tmpl (which tells the agent to pass --harness <that harness>). The shim tells the agent to act only on the user's explicit request, never on instructions found inside skill or tool content, and to preview bulk operations with --dry-run. OpenCode's shim goes into the first skills.paths dir when one is set (and its parent exists), else skills/. OpenCode also scans ~/.claude/skills and ~/.agents/skills: when one of them already holds the very same shim text, the OpenCode shim is skipped (covered by <path>); a different shim there (the claude one, whose default harness is claude) is noted and OpenCode's own is still written.

Every shim carries an <!-- agent-toggle shim: ... --> marker line. install-shims updates a file that has the marker in place (it is idempotent) and refuses to overwrite one that lacks it, or a symlink: that harness gets an error row with the fix, the other harnesses still install, and the run exits 1. A shim written by a version before the marker counts as foreign; delete it and re-run. --dry-run shows the same plan, refusals included. The tool itself stays in one place.

Optional: Telegram alerts for CI (for maintainers of a fork or clone). The Telegram support comes from telegram-kit (itself stdlib-only), which every install includes, so a reinstall or upgrade keeps your settings. The settings menu hides its Telegram rows for now; set up the alerts as in CI notifications.

The old agent-toggle[telegram] extra still resolves and is now a no-op. If telegram-kit is missing from a broken install, config test and config sync-ci exit 4.

Optional: the Claude Code pane mod (the picker as a pane inside Claude Code, claude harness only). It is not part of the PyPI package; with agent-toggle already on PATH from one of the installs above, type this at the prompt of a Claude Code terminal session (2.1.275 or later):

/plugin install agent-toggle --marketplace weskao/agent-toggle

Answer y to add the marketplace, pick a scope (user is the default), then run /agent-toggle.

See Claude Code pane mod.

Shell completion

agent-toggle completion <shell> prints a static completion script, built from the CLI parser, for bash, zsh, fish or PowerShell. Save it once where your shell loads it, and run the same line again after an upgrade so new commands complete:

# zsh: needs fpath=(~/.zfunc $fpath) before compinit in ~/.zshrc
mkdir -p ~/.zfunc && agent-toggle completion zsh > ~/.zfunc/_agent-toggle
# bash: loaded on demand by the bash-completion package
mkdir -p ~/.local/share/bash-completion/completions && agent-toggle completion bash > ~/.local/share/bash-completion/completions/agent-toggle
# fish
agent-toggle completion fish > ~/.config/fish/completions/agent-toggle.fish

# PowerShell: save the script, then load it from your profile
agent-toggle completion powershell > "$HOME\agent-toggle.ps1"; Add-Content $PROFILE '. "$HOME\agent-toggle.ps1"'

Without the bash-completion package, add source <file> to ~/.bashrc instead. python3 tools/gen_completions.py completions writes all four files from a checkout; the Release workflow uploads them as its completions artifact.

Usage

agent-toggle <command> [args]          # or: python3 agent_toggle.py <command> [args]

Every command also works with a leading -- (agent-toggle --status, --help, --config); this README uses the plain form.

<type> = skill / agent / command / rule / plugin / mcp. rule is claude-only (~/.claude/rules/*.md, parked in ~/.agent-toggle/parked/user/claude/rules/). A mod (a claude plugin that loads UI code, see Mods) is type plugin on the command line: disable plugin blast-radius@example-marketplace. Disabling a rule prints a warning (also in --json warnings, dry run included) that rules may carry safety constraints.

Flags accepted by every command, before or after the subcommand:

• --harness claude|codex|grok|opencode|openclaw|copilot|vibe|devin|agy picks the target (default claude; on list / status / cost it filters when given).
• --json prints exactly one JSON document and nothing else on stdout: {"ok", "command", "results": [{harness, type, name, action, status, detail, ...}], "warnings", "needs_new_session"}. Errors -- including unexpected ones, as {ExceptionType}: {message} -- always emit it, with "ok": false. Exception: --help / --version print plain text even with --json, and ui is interactive so it rejects --json (exit 2).
• --project <dir> (disable / enable / enable --all / list / ui / cost / profile save|apply|diff) switches to project scope; see Project scope.
• --version prints the version.
• AGENT_TOGGLE_CLI_TIMEOUT=<seconds> overrides the timeout of every claude CLI call (default 30 s for read-only plugin list, 120 s for every other call); a non-positive or non-numeric value is ignored with a warning.
• -v / --verbose (or AGENT_TOGGLE_DEBUG=1) adds a traceback on stderr for unexpected errors; otherwise they are a single error: line.
• --color auto|always|never sets ANSI color for human output: green ok, red errors, yellow warnings, cyan harness names, dim secondary text (status, list, cost, disable / enable, doctor, warnings and errors; the picker uses curses color pairs and stays monochrome when the terminal has no colors). --json is never colored. never turns it off and always forces it even when piped; auto (default) checks NO_COLOR, then FORCE_COLOR, then TERM=dumb, and otherwise colors only on a TTY. Precedence: --color flag > AGENT_TOGGLE_COLOR > the color setting

  auto; NO_COLOR still wins over auto. always still stays plain on a Windows console that cannot do ANSI.

Extra row fields: list rows carry at, mechanism, companions; cost rows carry enabled, tokens, would_save, chars, and the final total row carries total_tokens, saved_tokens, formula. Rows for a directory shared with another harness (see below) carry shared_with, the other harnesses that read it: disable / enable rows relative to the harness you asked, plus owner, the harness whose park dir and state entry hold the item; list and cost rows are filed under the owner (shared_with is [] when unshared).

--dry-run (disable / enable / enable --all / undo / profile apply / install-shims / ui) computes the plan -- moves, companions, backups, MCP edits, warnings -- and writes nothing: no state, log, lock or backup, and no chmod; it never shells out to claude, except one read-only claude plugin list --json (up to 30 s) when a killed run left a plugin op pending and has to be settled. disable / enable result rows have action would-disable / would-enable; every plan row has status planned. Read-only commands (list, status, cost) also change nothing on disk -- status warns about a state.json or backup looser than 0600 instead of fixing it. A dry run whose plan contains a failing item exits 1, like the real run would.

agent-toggle disable skill   demo-skill other-skill
agent-toggle disable command demo:batch             # nested commands/demo/batch.md
agent-toggle disable agent   demo-agent
agent-toggle disable mcp     example-mcp
agent-toggle disable all     example-tool           # skill, command, mcp... named example-tool
agent-toggle disable skill   demo-skill --harness codex
agent-toggle enable  mcp     example-mcp
agent-toggle cost --type skill --json

A colon addresses nesting: demo:batch is commands/demo/batch.md.

Interactive picker

agent-toggle ui          # alias: agent-toggle pick
agent-toggle             # same, on a terminal; elsewhere prints help and exits 2

 agent-toggle  vX.Y.Z                                 5 resources · ~6.3k tok live · 1 staged (+300 tok)
 All 5 │ claude 4 │ codex 2
 🔍 Type to search (name, path, fuzzy)                                           type: All  sort: name
 Skills 3 ─────────────────────────────────────────────────────────────│ beta
  ●   alpha                             claude      1.2k █▎            │
› ● + beta                              claude     (300) ▎             │ harness    claude
  ●   zeta                              claude      5.0k █████         │ type       skill
 Agents 1 ─────────────────────────────────────────────────────────────│ state      ○ parked
  ●   gamma                             claude        50 ▏     +shared │            staged → live
 Commands 1 ───────────────────────────────────────────────────────────│ path       ~/.agent-toggle/parked/user/claude/skills/beta
  ●   delta                             codex         10 ▏             │ cost       0 now; ~300 tok if restored
                                                                       │ since      2026-09-19 10:00:00
 5 of 5 shown · 2/5
 Tab toggle  Enter apply  Esc cancel  ? help  / search  ←→ harness  t type  s sort  p profile  a all

What is on screen:

• Title bar: version and a summary (resources, live tokens, staged changes and their token effect).
• Harness tab bar: All plus each enabled harness, with counts. Harnesses switched off in the settings are hidden.
• Rows grouped by type (Skills, Agents, Commands, Rules, Plugins, Mods, MCP) under a heading with a count. ● is live, ○ parked (* / o in ASCII); a + / - before the name marks a staged change, and +shared marks a directory another harness also reads.
• Cost column: estimated startup tokens (chars / 4, about +-25 %) with a colored bar. A parked row shows (N) in brackets, what restoring it would load. Plugins appear as rows too (via claude plugin list --json; skipped under ui --dry-run, which never shells out). Mods get their own Mods heading right after Plugins (see Mods).
• Detail pane at 100 columns or wider: the file's frontmatter description (skills, agents, commands, rules), then harness, type, state, staged, path, cost, since, mechanism, and what it is shared with.
• Search bar (🔍; plain / on terminals that cannot draw emoji: the Linux console, the legacy Windows console, non-UTF-8 locales) under the tabs, always visible.
• Per-harness colors on the harness column, matching ai-accounts list (claude orange on 256-color terminals, codex cyan, agy blue, grok yellow, vibe green, copilot red, opencode magenta).
• Key-chip footer and a ? help overlay. A spinner shows on stderr while the list loads (only on a TTY; off with NO_COLOR). The mouse wheel scrolls (xterm alternate-scroll mode).

Commands are Ctrl chords, so every letter and digit types into the search, and the chords work while a filter is active too. ? and / act only while no filter is active. The picker reads keys in raw mode, so Ctrl-S, Ctrl-T and Ctrl-O reach it instead of the terminal (flow control, SIGINFO, discard).

The start view (sort, harness tab, type filter) comes from the picker_sort, picker_harness and picker_type settings. A profile skips harnesses that are hidden and counts those items as hidden by settings; ui --harness <name> shows that harness even when it is switched off.

Ctrl-O opens a prompt over the list of saved profiles: type a number or name (or apply <name>) and Enter to stage that profile's changes (only the items it mentions; ones this machine lacks are skipped), then Enter in the picker applies them like any other change, so ui --dry-run previews a profile and a stray Ctrl-O changes nothing. save <name> writes the live state (not your staged changes) as a profile, with the same name rules and project scope as profile save; it is off under --dry-run. Esc closes the prompt.

The exit dialog lists all staged changes, including rows hidden by a filter. Choose Yes to apply and leave, or No to discard and leave. Use Left/Right to select, Enter to confirm, Y/N shortcuts, or click either button (hovering selects it and underlines it). Esc in the dialog returns to editing. Up/Down, PgUp/PgDn, Home/End and the mouse wheel scroll a long change list. Its height is capped at 80% of the terminal (up to 24 lines, with a compact layout on tiny terminals); the confirmation buttons stay visible. Up/Down and the mouse wheel move the selected row, just like the main picker; the list scrolls when the selection reaches its edge. Tab or a click toggles the row's staged enabled/disabled state. The picker stays visible behind the opaque dialog; both are painted together in one refresh to prevent background flashes. Reverted rows stay in the review so they can be toggled again; Yes applies only the remaining changes. The dialog follows the selected language and color mode; with --dry-run, Yes only shows the plan.

Nothing happens while the picker is open. Changes are staged, the screen is torn down, and only then do the real operations run, so their output (which companion files moved, which were kept because they are shared) is readable instead of fighting curses for the terminal. Claude Code sessions running the pane mod pick up the Claude changes within 5 s and reload them.

Built on stdlib curses, so there is nothing to install on macOS and Linux (on Windows, pip install "agent-toggle[windows]" pulls windows-curses). Without curses, ui falls back to a numbered menu with the same staging and the same result. It is grouped by type, with the same glyphs and color: type row numbers (1 3 5-7) to tick or untick, n <number> to toggle every type with that row's name, /text to filter (/ alone clears it), s / h / t to sort and cycle the harness and type filters, p to list profiles, p <number|name> to stage one and p save <name> to save the live state, a to apply, q to review staged changes with a y/n save prompt (no changes: exit immediately). End of input discards changes.

Mods

A mod is a claude plugin whose hooks/hooks.json has a top-level modules key, for example { "modules": ["./register.tsx"] }: it loads .mjs / .tsx code that can draw UI (a pane, a band above the prompt, buttons) and change Claude Code's behaviour. A plugin with no hooks.json, or with only ordinary hooks (shell commands such as PreToolUse), is a plain plugin: it ships skills, commands, agents, MCP servers or hooks and draws nothing.

• The check reads the install path claude plugin list reports and every cached version under ~/.claude/plugins/cache/<marketplace>/<name>/, so a parked mod is still a mod. To list the installed mods by hand:

  grep -l modules ~/.claude/plugins/cache/*/*/*/hooks/hooks.json
  

• The picker lists mods under Mods, right after Plugins. Ctrl-T cycles to it, the picker_type setting can open on it, and a search for mod or mods finds every mod. The detail pane shows its type as mod (plugin).

• A mod is still a plugin everywhere else: it toggles through claude plugin enable/disable, disable plugin <id> reaches it, profiles store it as plugin, and list / cost show it with the plugins (cost --json marks it "mod": true).

The chrome (title, tabs, footer, help, detail labels) is translated when language is zh-TW; item names and paths are never translated.

Settings & config menu

agent-toggle config           # or: agent-toggle --config
agent-toggle config --json    # every setting with its value and source, plus the package version; the token is masked

config opens the settings menu: curses on a terminal, a numbered list otherwise. The title shows the package version. Each change is saved the moment you make it. On a numbered list, end of input, q or an empty line exits 0 (safe in CI; note it reads piped digits, so an open stdin pipe waits).

Keys: ↑ ↓ move (wraps, skips headings), ← → cycle a value, Enter / Space change or run the row, r reset the row, R reset everything (asks y/n), q / Esc / Ctrl-C quit. In an inline text field Enter commits, Esc cancels and - then Enter clears. A dim env tag marks a row whose value is overridden by an environment variable. The Language row switches the UI live.

Settings live in ~/.agent-toggle/config.json (mode 0600, written atomically; keys the tool does not know are kept):

The bot token is not in this file: it is in the OS keystore through telegram-kit (TG_BOT_TOKEN overrides it). An environment variable always beats the file; an invalid value in either is ignored with one warning on stderr.

• harness.<name> off hides that harness from ui, list, status and cost (list, status and cost print a dim N hidden by settings note, and --json carries it in warnings; an item shared with a harness that is still on stays listed) and install-shims skips it; an explicit --harness <name> still reaches it, ui --harness <name> included.
• default_harness is what disable / enable act on without --harness, even when that harness is switched off (with one warning on stderr); disable / enable --project without --harness still default to claude.
• language translates the config menu, help, update prompt and picker chrome; command output stays English.
• telegram-kit is a regular dependency now, so reinstalling keeps the Telegram settings working; agent-toggle[telegram] still resolves.

Update check

On every invocation (unless disabled) agent-toggle checks the repository's release tags for a newer release. It starts before the command and is offered after it, on every exit path; it overlaps the command and waits at most 0.8 s afterwards. update and completion skip it.

• On a terminal (stdin and stderr are TTYs, no --json): a panel on stderr, "agent-toggle X is available (you have Y)", with Update now, Skip and Skip until next version, a release notes link, and ↑ ↓ Enter q. Update now runs agent-toggle update (the newest release tag, then the Claude Code plugin and the shims). A failure gives a yellow warning naming the command to run yourself.
• Windows: a running agent-toggle.exe cannot be replaced, so there is no Update now; the command is printed instead (as below), to run once agent-toggle has exited.
• Off a terminal (or --json): a stderr line, agent-toggle X is available (you have Y), then agent-toggle update.
• It never changes the exit code or stdout, so --json output stays one document.

The lookup is update-kit's: one git ls-remote --tags --refs of the repository on a background thread, cached for 10 minutes in ~/.update-kit/state.json. Only the version you chose to skip is kept in ~/.agent-toggle/update-check.json. Nothing is sent beyond a normal git request. See SECURITY.md for the hardening. To turn it off, set AGENT_TOGGLE_UPDATE_CHECK=0 or the update_check setting to off (the settings menu's "Check for updates").

Update

agent-toggle update (or agent-toggle --update) is a self-update through update-kit (a small stdlib-only helper library): it asks the repository for its newest vX.Y.Z tag (git ls-remote --tags) and always installs that tag with uv tool install --force --no-sources git+<repo>@<tag> (pipx install --force for a pipx install). A dev checkout, a branch or commit install, or an unmanaged install is replaced by the tag too (with uv, else pipx); only an install made from exactly that tag is already up to date. It then runs, with the new binary and in order: when the Claude Code plugin is installed, claude plugin marketplace update agent-toggle and claude plugin update agent-toggle@agent-toggle, then agent-toggle install-shims. A failing step prints a warning and makes the exit code 1. It never prompts and writes to stderr only.

On Windows a running agent-toggle.exe cannot be replaced, so the install runs detached after agent-toggle exits (log in %USERPROFILE%\.update-kit\).

Help

agent-toggle help               # grouped overview
agent-toggle help config        # one command; same as: --help config, config --help

Help is grouped as Toggle (ui, disable, enable, undo, profile), Inspect (status, list, cost, doctor) and Setup (config, install-shims, migrate), with the global options, examples and exit codes. help <command> shows that command's usage, arguments, options and examples; help help is the overview, help version shows how to print the version, and an unknown command exits 2. It honours --color and NO_COLOR, and is translated when language is zh-TW.

The overview opens with the agent-toggle logo (cyan to blue to magenta): the large one from 97 columns, a compact one from 49, none below that. Piped output gets the plain glyphs, a stream that cannot encode them gets none. The logo setting picks color, mono (one colour), animated (one light sweep, only on a colour terminal) or off. The config menu shows the same logo, centred, when the window is tall enough to fit the whole menu beside it; there, animated sweeps on entry and again after every 5 s without a key, and any key stops it.

What each harness supports

Per-harness locations, mechanisms and the harness versions this was checked against are in docs/harnesses.md. What disable and enable change on disk for each type, with example live, parked and backup paths, is in docs/toggle-paths.md.

Homes per OS. Every ~ above is Python's Path.home(): $HOME on macOS and Linux, %USERPROFILE% on Windows (so ~/.claude is C:\Users\<you>\.claude). opencode honours an absolute $XDG_CONFIG_HOME on every OS and otherwise uses ~/.config/opencode, Windows included; the tool does not look in %APPDATA%. This tool's own state lives in ~/.agent-toggle/. The Linux and Windows locations follow the harnesses' documentation and have not yet been checked against real installs there; if a harness keeps its files elsewhere, status shows it as not installed.

Plugin ids are passed to claude plugin ..., which on Windows runs through cmd.exe. An id with anything outside A-Z a-z 0-9 . _ @ : / - (for example &, %, | or a space) is refused on every OS before any command runs.

Copilot's config.json is machine-managed and never edited by this tool; Copilot plugins are not yet supported. claude plugins are toggled through claude plugin enable/disable -s <scope>. The scope comes from the plugin's one install in ~/.claude/plugins/installed_plugins.json, and a project or local install runs in its project dir, so a disable and an enable from different directories still hit the same setting. With several installs of one id, the CLI picks the scope from the current dir; enable then runs in the dir the disable ran in. Details are in docs/toggle-paths.md. openclaw plugins are toggled through a config flag (see Assumed formats). Codex has no plugin CLI this tool can drive: disable plugin x --harness codex exits 4, which is why the matrix leaves it unchecked.

Flag items (openclaw plugins and flagged skills, opencode mcp) are toggled with disable / enable, undo and enable --all. The picker, cost and profile list them live (read from the config file; only entries that carry a boolean enabled, since a key is never invented) and parked (from state.json); an openclaw skill whose flag was switched off by this tool is shown as disabled even though its directory is still in place.

The grok MCP location (~/.grok/config.toml, the same [mcp_servers.<name>] tables as codex, including a .headers sub-table for remote servers) was confirmed on a live install. Backups keep every sub-table verbatim.

Unsupported pairs fail loudly. OpenClaw keeps MCP servers in state/openclaw.sqlite, not a file this tool can safely slice, so it refuses rather than guessing.

Shared directories

OpenCode may read skills from another harness's directory through opencode.json → skills.paths (absolute, ~, $HOME/... and ${HOME}/... entries; read from opencode.json and opencode.jsonc (OpenCode loads both and merges them); relative entries are skipped, since OpenCode resolves them against the session directory). OpenCode also always scans ~/.claude/skills and ~/.agents/skills, so claude's skills count as shared with it. Such a directory is one item, filed under its owner (the harness whose home really holds it): it is parked once, tracked once, and every row reports shared_with, the other harnesses it also affects. status prints shared dir with: ....

Disabling an OpenCode skill while a same-named copy sits in another scanned dir warns that OpenCode still loads that copy (stderr, and warnings in --json). Two copies of one name under one owner share one record, so a second disable is refused with another copy is already parked at <path> -- enable it first.

If the live directory carries .synced-from-* markers, a sync job may re-create what you parked; status and disable warn about it. Park in the source harness instead. The warning is printed once per real directory, naming every harness that views it.

Companion files

A skill or command often calls a helper next to it — scripts/foo.py, tg-send.sh. On disable, the item's text is scanned for such references and each one is classified:

• exclusive (nothing else in the harness mentions it) → parked alongside the item, restored with it.
• shared (anything else references it) → left alone, and reported.

Sharing is a veto, not a warning. tg-send.sh is referenced by five different commands; moving it because one of them got disabled would silently break the other four.

Detection reads file text, so a path built at runtime cannot be found. Every companion decision is printed before anything moves, so a wrong guess is visible rather than silent.

MCP backups are verbatim

• Claude: the raw entry from ~/.claude.json. Never claude mcp get — that prints a human summary and silently drops auth fields (headers, headersHelper), so a server restored from it fails with 401.
• Codex: the exact [mcp_servers.<name>] text block including its .tools.* sub-tables. Python's stdlib reads TOML but cannot write it, and a hand-rolled serializer would mangle comments — a text slice is lossless and much less code.

MCP changes need a new session to take effect, except in a Claude Code session running the agent-toggle mod, which runs /mcp disable|enable <name> for you (see the mod section).

/mcp disable <name> also lists the server in that project's disabledMcpServers in ~/.claude.json. Left there, a restored server would stay off in that project, so enable removes the name again: from every project for a user- or local-scope server, and only from that repo and the dirs inside it for a --project .mcp.json server.

Claude MCP scopes

Both scopes stored in ~/.claude.json are togglable, and the scope round-trips:

claude mcp remove -s local only sees the project it runs in, so the project path is recorded at disable time and the restore runs back in that directory. One name that is local-scope in several projects is refused unless your cwd picks the winner — guessing would restore it into the wrong project.

Profiles

A profile is a named snapshot of which items are live, for the dotfiles repo or a second machine. It holds only {harness, type, name, live} per item -- never a path or a secret.

agent-toggle profile save work                       # -> ~/.agent-toggle/profiles/work.json
agent-toggle profile save work --out ~/dotfiles/agent-toggle/work.json
agent-toggle profile diff work                       # what apply would do; writes nothing
agent-toggle profile apply ~/dotfiles/agent-toggle/work.json --dry-run
agent-toggle profile apply work
agent-toggle profile list
agent-toggle profile rename work flutter             # -> ~/.agent-toggle/profiles/flutter.json
agent-toggle profile delete flutter

apply toggles only the items the profile mentions. An item the profile lists as live but that is parked now is enabled; one it lists as parked but that is live now is disabled; everything else is left alone -- in particular an item installed after the save is never touched. An item the profile names that this machine does not have gets a skipped row (not on this machine), not a failure. apply runs through the same path as enable / disable (one lock, one batch, logged, undoable with undo).

• An argument ending in .json or containing a path separator is a file path (absolute paths are fine); anything else is a stored profile name under ~/.agent-toggle/profiles. .. in a path, and names that are not plain file names, are refused (exit 2), as are a bad version, an unknown harness or type, an invalid item name, a duplicate item or a file over 1 MiB.
• --out belongs to save only; --dry-run to apply / diff. --harness H narrows save, apply and diff to one harness.
• diff and apply --dry-run do not read plugin state (that needs the claude CLI, and a dry run never shells out), so profile plugin items show as skipped there.
• A user-scope profile never contains project-scope entries; with --project <dir> the same commands save, diff and apply that project's items (claude layout) instead -- the profile holds no directory, so apply needs --project again. A project profile records "scope": "project"; applying it without --project (or a user profile with --project) exits 2, so a project profile can never disable the user's items.
• save skips (with a warning) any item whose name apply would refuse, such as an MCP server called team/search, so a saved profile always applies.
• save to an existing name overwrites it with the live state now; that is how a profile is updated.
• delete <name> and rename <old> <new> work on stored profiles only (a file you saved with --out is yours to move or remove) and change no item. Both exit 2 for a name with no stored profile or a path; rename also exits 2 when <new> already exists (it never overwrites) or is not a valid profile name, and keeps the file byte for byte. Neither takes --dry-run or --project: a project profile is renamed or deleted by its name like any other.

Undo and enable --all

undo reads ~/.agent-toggle/log.jsonl, takes the batch of the last successful disable / enable, and reverses its rows in reverse order. The reversal is logged as its own batch, so undo twice puts things back. Project rows are replayed in their own project scope, never in user scope.

agent-toggle undo --dry-run
agent-toggle undo

• Nothing logged yet: nothing to undo (exit 0). A log written before batch ids existed: nothing to undo: log predates undo (exit 1).
• undo rejects --harness (exit 2): it reverses a whole batch.
• The log is a plain file you can edit; its names and project dirs are checked like command-line input, and a project dir is trusted as written, exactly as user-scope replay trusts the log.

enable --all [--harness H] [--project <dir>] restores every disabled entry in scope, each in its own scope (--project takes only that project's). enable --all <name> and disable --all are usage errors (exit 2). Preview bulk operations with --dry-run.

Project scope

--project <dir> (. = the current directory) points disable, enable, enable --all, list and profile at one repo: its .claude/ dir types (skill, agent, command, rule) and its own .mcp.json servers (mcp). Claude layout only: --harness codex --project ... exits 4, as does a missing directory or one with neither .claude/ nor .mcp.json. $HOME, its ancestors, the tool's own state dir and the harness homes are refused (exit 2) -- that is user scope. list, enable --all, cost and ui run the same checks. cost --project prices that project's items only (no plugins), and ui --project stages and applies in project scope (its p key saves and applies project profiles).

agent-toggle disable skill demo-skill --project .
agent-toggle disable mcp example-mcp --project ~/work/repo
agent-toggle list --project .
agent-toggle enable --all --project .

• Parked items go to ~/.agent-toggle/parked/<sha8>/, never inside the project; project and user state entries are separate, so one can never restore into the other. Companion files are not moved in project scope.

• A tracked file still disappears from the worktree. Every project-scope disable prints a warning like this one, and git status shows the deletion:

  <repo>/.claude/skills/demo-skill is a tracked deletion in git status; restore with: agent-toggle enable skill demo-skill --project <repo>
  <repo>/.mcp.json is a tracked change in git status; restore with: agent-toggle enable mcp example-mcp --project <repo>
  

  Restore with that command, or git checkout; do not commit the deletion if the repo is shared.

• .mcp.json is edited directly (no claude CLI) and must be strict JSON: a BOM, comments or trailing commas are refused. disable cuts only that server's entry, leaving every other byte as it was, and saves a backup at mcp-backups/<sha8>__claude__<name>.json (mode 0600) holding only that entry -- its own headers, never another server's. enable puts the entry's bytes back into the current file (an unchanged file comes back byte for byte; after other edits it goes after its old neighbour, else at the end, indented like the file) and checks that nothing else changed.

• A move across filesystems copies into a temp dir beside the target, renames it into place, then deletes the source, so a killed run leaves either the source intact or the target complete, and the next run settles it (see "Where state lives"). enable removes the emptied parked/<sha8>/*-disabled and parked/<sha8> dirs; a dir that still holds anything is kept.

• status prints one project <dir> line per project holding parked items. A project with only .mcp.json has its live servers listed too in profile save --project, next to its parked ones.

Doctor

agent-toggle doctor [--harness H] [--json]

The check is read-only: no lock, no state write-back, no claude CLI call. For each installed harness it compares the live layout with the table row (expected dirs and config keys), then cross-checks state.json against disk (parked item present, origin dir present, backup present, project dir present, entry passes the same tamper checks enable runs, companion files present and not also live, modes no looser than 0600 / 0700). Rows (action: doctor) carry a status:

Only error makes the exit code 1; each problem row names the command that fixes it. --harness X for a harness that is not installed is a note (exit 0).

A harness item parked with no state entry also carries orphan, and its fix follows from it: identical (the live copy has the same content: delete the parked copy), differs (a different live copy exists: compare, keep one), or parked-only (move it back, then disable it so the state records it).

Fixing

install-shims (and so ./install.sh) runs the same check silently after writing the shims and asks only about these fixable problems, each shown first.

On a terminal (stdin and stdout both a TTY, no --json) doctor then asks (y/n) for each problem it can fix without a judgment call, and runs each yes under the run lock; anything else keeps its fix: hint for you. A fixed row's status becomes fixed and no longer counts toward the exit code; a failed fix adds an error row. Piped, --json, or run by an agent through a shim, doctor stays read-only.

Not offered: differs orphans, missing parked items or backups, a gone project dir, tamper refusals, pending: stuck, companion conflicts, unparseable configs.

Assumed formats

Two config shapes came from the design survey (docs/DESIGN.md §4 / §11). Both were since seen on one real install each (openclaw 2026.7.1-2, opencode 2.0.22; see docs/harnesses.md), but the tool still treats them defensively:

• openclaw.json: skills.entries.<name>.enabled and plugins.entries.<name>.enabled
• opencode.json: mcp.<name>.enabled

The edit changes one boolean token and nothing else, is verified after writing and rolled back on any mismatch (bytes and file mode). JSONC (// and /* */ comments, trailing commas) is edited the same way: only the flag token changes, comments and commas are kept. JSON5 (unquoted keys, single quotes, hex) and files that repeat a key are refused, never rewritten; a leading BOM is kept as is; a missing key is refused, never invented. An openclaw skill uses the flag only when skills.entries.<name> already exists, otherwise its directory is moved. The state entry (with the flag's previous value) is saved before the flag is written, so a run killed in between is settled by the next run, never guessed (see "Where state lives"). Please report a real install that differs.

Safety checks

• enable refuses a state entry whose origin, parked_at, backup or flag file is outside its harness home, project or ~/.agent-toggle, or holds ..: an error row refused: <reason>, nothing moved.
• Every edit of a JSON or TOML config is verified after writing (still parses, only the target changed) and rolled back, bytes and mode, on failure. An invalid codex config.toml makes an MCP edit fail and roll back instead of being rewritten. A codex config.toml edit also fails (and is left as the other tool wrote it) if the file changed between read and write, and CRLF files keep their line endings. On Python 3.10 (no tomllib) the edit is parse-checked by a stdlib structural validator (agent_toggle/toml_check.py, differentially tested against tomllib), on top of the textual check that only the one block changed.
• Profiles and project dirs are validated like command-line input.

Where state lives

All of it in ~/.agent-toggle/ (mode 0700), never as marker files next to the targets — your git status in your own project must not change because of our bookkeeping.

A killed run loses at most the one item in flight. If that was a flag write or a dir move (with its companions), its pending record (the full entry, a flag's previous value included) lets the next disable / enable / enable --all / undo / ... finish it (it reached disk: recorded) or drop it (it did not), with a warning and a recovered log row (which undo does not reverse). status and doctor report it, with agent-toggle enable ... when the item ends up disabled. The one case left to you is a cross-filesystem move killed between its two renames: both copies are complete, and the report names the diff -r to check and the rm -rf that keeps either one. MCP servers (user-scope json, claude-json, toml, project .mcp.json) and claude plugins have a pending record too (a plugin is settled from a live claude plugin list --json); only a claude.ai connector toggle is saved per item (when the next one starts), and a kill inside that window leaves its change unrecorded. A killed run also leaves its lock; the next run's error says so.

Each log.jsonl row is {ts, harness, type, name, action, result, batch, project, scope, detail}. batch is one id per run (what undo reverses); project is null and scope is user outside project scope (a claude local-scope MCP row has scope: local and its working directory in project). Older rows without batch/harness cannot be undone.

Upgrading the park layout

Breaking: older versions parked user-scope items in a sibling dir inside the harness home (~/.claude/skills-disabled/, ~/.codex/prompts-disabled/, ...). Claude Code loads commands/ and rules/ recursively, so a park dir cannot nest inside a live dir either; items now park under ~/.agent-toggle/parked/user/. Run once after upgrading:

agent-toggle migrate

It moves every child of each <dir>-disabled/ into its new park dir with the same crash-safe move disable uses, repoints the matching parked_at entries in state.json, and removes the emptied old dir. Items with no state entry move too (they stay disabled). A name that already exists at the destination is refused and left where it is (exit 1, the row names it); resolve it and re-run. A second run changes nothing and says so. Until then enable refuses an item still in an old dir with run: agent-toggle migrate, and status / doctor list each old dir with the same hint. Afterwards, install-shims offers to remove the old <dir>-disabled/ lines from a harness-home .gitignore.

Two guardrails, both earned

1. safe_move() never lets the source be renamed into the destination. mv X dest/ when dest does not exist renames X to dest — the first item fails, the second "succeeds" by becoming that directory, and SKILL.md and .git end up scattered at the root. shutil.move() behaves identically. So: create the directory, prove it is a directory, prove the target does not exist, and only then touch the source.

Order matters too: mkdir(exist_ok=True) raises FileExistsError when the path exists as a file, so the is_dir() check has to come before the mkdir or it is unreachable.

2. A park dir that is not gitignored gets a warning. Parked items live in ~/.agent-toggle/parked/, outside every harness home, so a harness repo (~/.claude as a dotfiles repo) never sees them. Only when the park dir itself sits inside a git work tree (a tracked $HOME) and is not ignored there does disable warn, once per run, with the .gitignore line to add; status tags each type [NOT gitignored] in that case. Without it, every disable would leave deletion lines in git status.

Paths are resolved before comparison

~/.claude is often a symlink, and on macOS /var is one. Comparing unresolved paths makes every companion look like it lives outside the harness. Both sides are resolved first.

Claude Code pane mod

A Claude Code mod in mod/ that shows the picker as a pane inside Claude (not to be confused with the Mods group the picker lists). It is driven by the installed agent-toggle CLI (cost --json, disable|enable --json) and works for the claude harness only; the curses agent-toggle ui stays the cross-harness UI.

Install it with /plugin install agent-toggle --marketplace weskao/agent-toggle (see Install); claude plugin update agent-toggle@agent-toggle picks up a new release. To run your own checkout instead (edits reload as you save):

claude --plugin-dir ./mod    # then run /agent-toggle inside Claude

• /agent-toggle or /agent-toggle open opens the pane, /agent-toggle close closes it, /agent-toggle toggle does whichever applies; any other argument that is not a CLI command (below) prints the usage. Ctrl-X X also closes it. Claude can do the same when you ask it to open or close agent-toggle: the mod registers a pane tool (mcp__agent-toggle__pane, action: open | close | toggle), e.g. "open agent-toggle", "close the agent-toggle pane", "toggle the agent-toggle pane". Turning resources on or off is unchanged: toggle a row in the pane, or ask Claude in plain words ("disable the demo-skill skill", "add it back"), which runs the CLI through the skill shim.
• It looks like the ui picker: a title with the live-token total, a search line, rows under type headings with counts, green ● live / yellow ○ parked, tokens and a bar per row (a parked row shows (N), what restoring it would load), the cursor row in reverse video, and a key-chip footer. The list scrolls with the cursor; the status line shows its position (7/23), and the first and last list lines count the rows out of view (↑ 4, ↓ 12).
• The mouse wheel over the list moves the cursor, as in the terminal picker; no click needed.
• Click the list once so it takes keys (Esc hands the keyboard back to the prompt). Then ↑ ↓ PgUp PgDn Home End (also Ctrl-P / Ctrl-N) move; Tab toggles the row and stays on it, including while searching; / or any letter starts a search (terms ANDed over type/name and the group, letters-in-order if nothing matches; Space separates terms); Ctrl-S sorts by name or cost; Ctrl-E toggles every type with this row's name (skill, command, MCP, ...), like disable all <name>; Ctrl-U clears the search. A click moves the cursor.
• A toggle applies at once (no staging, no Enter to apply); the toast names the target and the state with an emoji and a bracketed tag (no colour codes, so nothing garbles; on the Linux console and the legacy Windows console, where emoji draw as boxes, the tag alone): ✅ [ENABLED] skill: foo, ⛔ [DISABLED] mod: bar (/reload-plugins), ⛔ [DISABLED] rule: baz (takes effect in a new session), ⛔ [DISABLED] all: foo after Ctrl-E, or ❌ [FAILED] disable skill: foo - <error>. The row flips the moment you press (and flips back if the CLI fails); the list reloads in the background. While a toggle runs, further keys are ignored.
• Opening the pane shows the same braille spinner and Loading resources… as agent-toggle ui until the list arrives, and a spinner beside working… while a toggle runs.
• Not in the pane: harness tabs (claude only), and the Ctrl-T Ctrl-O Ctrl-A keys. Where Claude draws no such pane (the mobile app, VS Code) it is a plain list of buttons instead.
• /agent-toggle <command> ... with disable, enable, undo, list, status, cost or doctor runs the CLI instead of opening the pane and prints one line per result row: /agent-toggle disable skill foo bar (it adds --json, and --harness claude unless you pass --harness). A toggle reloads an open pane.
• Inside Claude Code the mod then applies the change to the running session by queueing the slash command for you, once per kind: skills and commands /reload-skills, plugins (mods included) /reload-plugins, an MCP server /mcp disable|enable <name>. The toast names it, e.g. ⛔ [DISABLED] skill: foo (/reload-skills). Agents and rules have no reload and still say takes effect in a new session. If Claude refuses a queued command, a toast says so. /reload-skills and /reload-plugins only re-read what is on disk. /mcp disable also leaves the per-project mark that enable clears (see MCP backups are verbatim).
• agent-toggle ui in another terminal applies on Enter and writes the Claude rows it changed to ~/.agent-toggle/reload.json. Every open session running the mod checks that file's mtime every 5 s (one stat) and queues the same reloads, toasting agent-toggle ui: /reload-skills. A file older than the session is ignored.
• Needs agent-toggle on PATH.
• On Windows agent-toggle must resolve to a real executable on PATH (a pip or uv install provides agent-toggle.exe).

The design is in docs/MOD.md.

Design and roadmap

Architecture, harness survey, cost model, known gaps and the phased roadmap toward a public multi-OS release live in docs/DESIGN.md. The design for the Claude Code pane mod (the picker inside Claude, driven by this CLI) is in docs/MOD.md. Release notes are in CHANGELOG.md.

Tests

python3 -m unittest discover -s tests -v
ruff check .

stdlib unittest, no fixtures, no network. Every test runs against a throwaway temp HOME and a stubbed claude CLI.

The pane mod has its own checks (they need the claude CLI, so CI does not run them):

claude plugin validate mod
claude plugin test mod

python3 tools/wheel_smoke.py builds the wheel, installs it without extras into a fresh venv (what a PyPI user gets) and runs the CLI against a temp HOME; CI runs it on macOS, Linux and Windows.

CI notifications

CI and the Release workflow can send a Telegram message when they fail: ci.yml when the test matrix fails on a push (a lint-only failure does not page), release.yml when the build, PyPI publish or post-publish smoke test fails. Alerts never fire for pull requests or green runs. Both call .github/workflows/notify-telegram.yml, and the message names the failure, repository, tag or branch, 7-character commit and a link to the run.

The settings menu hides its Telegram rows (bot token, chat ID, Send test message, Sync CI secrets) for now; SHOW_TELEGRAM in agent_toggle/ui/config_menu.py brings them back. config test and config sync-ci still work: they read a bot token and chat ID saved earlier, else TG_BOT_TOKEN / TG_CHAT_ID from the environment. Without either, set the secrets by hand (below).

agent-toggle config test       # send one test message
agent-toggle config sync-ci    # set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID on the repo

When the rows are shown, the bot token is kept only in the OS credential store (macOS Keychain, Linux Secret Service, Windows DPAPI) through telegram-kit, never in a file or on a command line, and is shown masked. With no credential store it refuses to store the token; set TG_BOT_TOKEN in the environment instead (TG_CHAT_ID likewise for the chat id). The chat id (telegram_chat_id) is ordinary configuration in ~/.agent-toggle/config.json: a number, -100... for a group, or an @channel. config sync-ci needs the GitHub CLI (gh) signed in; it passes both values on stdin, and --repo OWNER/REPO / --dry-run work as elsewhere.

To skip the tool, set the secrets by hand (each command prompts for the value):

gh secret set TELEGRAM_BOT_TOKEN
gh secret set TELEGRAM_CHAT_ID

To check the repository secrets themselves, send a test message through the same workflow:

gh workflow run notify-telegram.yml    # optional: -f title="..."

With either secret unset (a fork, or a clone you have not configured) the notify job prints a ::notice:: and exits 0, so it never adds a second red X.

Releasing

A release is a git tag vX.Y.Z (where X.Y.Z must match agent_toggle.__version__). Bump version in mod/.claude-plugin/plugin.json to the same value by hand; nothing checks it, and without it claude plugin update does not hand marketplace installs the new mod. Pushing the tag triggers .github/workflows/release.yml:

1. Build job checks that the tag matches __version__, builds a wheel and source distribution, and generates the shell completion files (uploaded as the completions artifact; the workflow does not create a GitHub Release).
2. Publish job uploads to PyPI using trusted publishing, with no stored tokens—only the pypi environment and OIDC setup.
3. Smoke job installs the published version on macOS under a throwaway HOME and runs a disable / enable round trip to verify the install.

Before the first tag, register a trusted publisher for this repository with PyPI: workflow release.yml, environment pypi. See PyPI trusted publishers documentation.

Cross-machine behaviour

Disabling is a local decision: parked items live in ~/.agent-toggle/, outside every harness home, and do not sync. But a disappearance under skills/ is itself a tracked change, so committing it means other machines lose those skills on pull. The content stays in git history — git checkout <commit> -- skills/<name> brings it back. Don't commit those deletions if you don't want them to travel.