bite
Menu

docs · start

Getting Started#

From cargo install to a working agent in five minutes: install, bite setup, permission prompts, connecting your agent CLI, and the first real call. The permissions page is the full TCC reference — every prompt and how to recover; this page walks the happy path.

What you need#

  • macOS 13+ (Ventura or newer)
  • Xcode Command Line Tools — xcode-select --install. bite ships as source: the install compiles two small Swift binaries (the native helper and the Mail crawl worker) next to the Rust control plane.
  • An agent CLI (optional for the CLI verbs, required for MCP): Claude Code, ZCode, Codex, OpenCode, Cursor, VS Code or Gemini CLI.

Step 1 — install#

cargo install bite-mcp

If cargo is not installed yet, install Rust first (rustup.rs), then re-run. bite lands on $CARGO_HOME/bin — make sure that directory is on your PATH (bite --version should print).

Claude Code and ZCode users can alternatively start from the plugin marketplace (/plugin marketplace add ktesio/bite-mcp) — but that path still needs bite on PATH first, so the install above happens either way.

Step 2 — bite setup#

bite setup

One command, four stages, in order:

  1. Data dir hardening (silent) — ~/Library/Application Support/bite and its contents are enforced to 0700/0600, including on upgrades of older installs. The same enforcement also runs at every CLI/MCP startup, so a data dir first materialized by a crawl (before bite setup ever ran) is tightened automatically. Nothing is sent anywhere; bite is local-only.

  2. Native helper install — compiles (first run) or refreshes bite-helper at a stable path under the data dir. The stable path is deliberate: macOS ties permission grants to the binary's path, so a helper that moves would re-prompt for everything. If this stage fails, the rendered error names its real fix (most often installing the Xcode Command Line Tools via xcode-select --install, then re-running).

  3. bite doctor — a prompt-free environment check: macOS version, helper presence and capabilities, per-app permission status. This is read-only; it never triggers prompts (that's what --probe is for — it live-tests Apple Events and can raise prompts, so it warns first). Add --json for the same report as one compact machine-readable object (exit codes unchanged: 0 clean, 2 problems). A denied crawler Mail probe counts as a problem (exit 2); the missing Swift toolchain shows as a warning (○) and never does.

  4. Agent clients — for every agent CLI it detects (by config file or binary on PATH), bite asks once:

    register MCP server in Claude Code? [Y/n]

    Answer Enter/Y to write the config, n to skip that client. Detection means "this CLI exists on the machine" — bite never guesses about clients you don't have. No agent CLIs at all? It says so and moves on; re-run bite setup after installing one.

Flags: --all-clients (or --yes) registers every detected client without asking — for headless use. The only prompt in the whole run is the per-client registration question; pressing Enter accepts. Closed stdin (EOF) counts as n for every prompt — a scripted run that wants registrations passes --yes (piped answers like printf 'y\n' still work).

The run ends with the marketplace commands for Claude Code / ZCode and the next-steps list. Exit code 0 = all good; 2 = some client configs were left untouched (see When setup reports leftovers).

Exactly what gets written, where, and with what safety guarantees is on the clients page.

Step 3 — permission prompts (once)#

The first real call per app family raises macOS's own prompt once:

  • Calendar / Reminders / Contacts — "bite-helper would like access…", attributed to the helper's stable path (granted once, stays granted).
  • Mail / Notes / Messages — "'Terminal' wants to control Mail" (or your agent CLI's name), attributed to the parent app of the process chain.
  • Mail indexing — the crawl worker is a separate binary with its own TCC identity, so it raises one more "wants to control Mail" prompt the first time indexing starts.

Approve them from a real terminal when they appear (prompts raised from deep inside an agent session can be awkward to attribute — running the first call yourself avoids the confusion). The full prompt matrix, including Messages history's Full Disk Access requirement, is on the permissions page.

Denied something later or never saw a prompt? bite doctor --fix opens the matching System Settings pane for anything denied.

Step 4 — restart the agent CLI#

Agent CLIs read their MCP config at startup. After setup writes an entry, restart the CLI (or reload the window in VS Code) before expecting bite tools to appear. bite doctor shows a per-client line (✓ configured, ○ detected but not configured, blank = not found) to confirm what each CLI will pick up.

Step 5 — first call#

Verify the whole chain from your terminal first — this raises the permission prompts in your own context, not the agent's:

bite reminders lists
bite calendar availability --from "today 9am" --to "today 6pm"
bite mail search --mailbox INBOX --unread --limit 10

Then ask your agent. In Claude Code / ZCode the tools are namespaced under the bite MCP server; elsewhere the 46 tools (calendar_events_search, mail_send, notes_create, messages_send, contacts_search, …) appear in the client's normal tool list. Mail searches stay fast because the index builds in the background after first use — see the entity index.

Uninstall / clean slate#

  • Remove bite from an agent CLI: delete the bite entry from the file listed in the clients table (or your dotfiles repo if you manage configs that way — bite refuses to write through symlinks, so it never edited the link itself).
  • Remove the binary: cargo uninstall bite-mcp.
  • Remove all local data (index, helper, config): delete ~/Library/Application Support/bite. Nothing else on the system references it; macOS permission grants for the helper's old path become inert when the binary is gone.