docs · start
Agent Clients#
bite setup writes one MCP server entry into every agent CLI it detects. This page is the exact reference: which file per client, what shape the entry takes, and the guarantees every write carries. The first-time walkthrough around it is on the getting started page.
What exactly gets written#
A single MCP server entry named bite, per client's own documented format — nothing else in the file is touched:
| Client | File | Shape |
|---|---|---|
| Claude Code | ~/.claude.json (or $CLAUDE_CONFIG_DIR/.claude.json) | "mcpServers": { "bite": … } |
| ZCode | ~/.zcode/settings.json, else ~/.zcode/config.json | "mcpServers" |
| Codex CLI | ~/.codex/config.toml (or $CODEX_HOME/config.toml) | [mcp_servers.bite] table |
| OpenCode | ~/.config/opencode/opencode.json[c] | "mcp": { "bite": … } |
| Cursor | ~/.cursor/mcp.json | "mcpServers" |
| VS Code | ~/Library/Application Support/Code/User/mcp.json | "servers" with "type": "stdio" |
| Gemini CLI | ~/.gemini/settings.json | "mcpServers" |
All entries are the same server: bite mcp over stdio. The registered command is the resolved absolute bite path (installed copies), so GUI-launched clients can start it without ~/.cargo/bin on their PATH; builds straight from a dev checkout register the bare bite instead — build-tree binaries vanish on the next cargo clean.
The writing is defensive by design#
- Atomic. The new config is written to a temp file in the same directory, fsynced, then renamed over the target — an interrupted setup can never leave a truncated or zero-byte config behind.
- Never clobbers what it can't parse. A config that fails to parse (strict JSON with comments in it, trailing commas, hand edits) is left untouched and reported — bite would rather do nothing than destroy your file.
- Backups. Before first modifying a non-empty config, bite saves
<name>.bite-bakfrom the original bytes. The first backup is never overwritten. - Symlinks are refused. Dotfile-manager-managed configs (stow, chezmoi) are skipped with a note to merge the entry manually — rename would silently sever the link.
- Permissions never widen. Replacements keep the file's existing mode; new files are 0600.
- Comments survive. OpenCode's JSONC is edited with a comment-preserving parser; formatting and comments outside the inserted key come out unchanged.
- Idempotent. Running setup twice yields identical bytes.
Claude Code and ZCode: the marketplace plugin#
Claude Code and ZCode can install bite as a plugin instead of a raw MCP entry:
/plugin marketplace add ktesio/bite-mcp
/plugin install bite@bite-mcpThe plugin ships an agent skill alongside the server (tool map, recipes, and the rules of thumb — ISO 8601 dates with offset, preview-before-confirm, relay fix verbatim). It still needs bite on PATH first, so cargo install bite-mcp happens either way; with both, prefer the plugin and skip the raw mcpServers entry.
When setup reports leftovers#
If a client config could not be written safely, setup prints a summary on stderr and exits 2 — every other client was still handled. Fix the reported file (usually: resolve the syntax error bite names) and re-run bite setup. Two other notes you might see:
- legacy scar note — files left behind by pre-0.3.1 writers are reported with a hint but never deleted by bite.
- "no agent CLIs detected" — nothing to configure yet; the CLI verbs (
bite reminders lists, …) work without any client config.
Removing an entry#
Delete the bite key from the file in the table above. If you manage configs through a dotfiles repo, bite never wrote through the symlink — merge the removal the same way you manage the rest of the file. Restart the CLI afterwards; the tools disappear with the entry.