bite docs

bite gives AI agents native access to six Apple apps — Calendar, Reminders, Mail, Notes, Contacts and Messages — over MCP, with a matching CLI verb for every tool. A Rust control plane over a native Swift helper (EventKit, Contacts.framework, ScriptingBridge), plus a detached crawl worker that indexes Mail into a local LanceDB database for instant search. Everything runs on your Mac; nothing leaves it.

These docs describe bite 0.5.0, released on 22 October 2026.

Choose a path

• Try it in five minutesInstall bite, run bite setup, approve the one-time prompts, and make the first call.
• Connect your agentClaude Code, ZCode, Codex, OpenCode, Cursor, VS Code or Gemini CLI — what gets written, where.
• Search your mailThe local index: milliseconds instead of minutes, bulk operations included.
• Extend biteAdd an app or a verb: one Swift handler, one registry entry, one CLI verb.

bite is a Ktesio project, developed in the open at ktesio.dev and released under the MIT license.

bite is an independent open-source project. It is not affiliated with, sponsored, or endorsed by Apple Inc. macOS, iMessage, iCloud, Calendar, Mail, Notes, Messages, Contacts and other Apple marks are trademarks of Apple Inc.

All docs

Start

Install bite, connect your agent CLI, and grant the permissions macOS asks for once.

• Getting StartedFrom cargo install to a working agent: install bite, run bite setup, approve the one-time macOS prompts, and make the first call.
• Agent ClientsHow bite registers itself in each agent CLI — Claude Code, ZCode, Codex, OpenCode, Cursor, VS Code and Gemini CLI — and the guarantees every config write carries.
• Permissions (TCC)Every macOS permission bite touches: the four TCC families, the Full Disk Access requirement for Messages history, the crawler's separate identity, and how to recover from anything.
• TroubleshootingFirst moves for the symptoms bite can run into: PATH, helper installs, permissions, indexing, clients and tools.

Reference

Exact facts to look up: every tool, the resources and prompts, the config keys, and the entity index.

• ToolsAll 46 MCP tools, by app — Calendar, Reminders, Mail, Notes, Contacts, Messages and the entity index — with the confirm-first rules and the CLI verb each tool mirrors.
• Resources & PromptsThe five MCP resources bite publishes and the three workflow prompts it ships — plan-my-week, triage-inbox and daily-brief.
• Configurationbite's config.toml — default_calendar, default_mail_account, timeout_secs, release_repo, auto_refresh_hours — plus the BITE_TIMEOUT_SECS override and where everything lives.
• The Entity IndexHow bite indexes Mail into a local LanceDB database — crawl windows, staged batches, instant full-text search, bulk operations, and the scoped durable purge.

Internals

The design underneath: the three processes, the bridge protocol, and how to extend bite.

• ArchitectureThe Rust control plane, the native Swift helper and the detached crawl worker — why the helper lives at a stable path, how OSA mediates Apple Events on macOS 27, and where the registry fits.
• Bridge & handoff protocols (Rust ↔ Swift)The Rust↔Swift helper protocol — NDJSON over stdio, the handshake, request and response shapes, error codes — and the staged batch handoff with the crawl worker.
• Adding an AppThe contributor guide: a Swift handler, a registry entry and a CLI verb — three layers in sync, with tests that catch drift.
• Security & Privacybite is local-only: what it can touch, where the data goes (nowhere), how to report vulnerabilities, and the intended-use line.

Project

Where bite stands, what changed in each release, and what is planned.

• ChangelogNotable changes per bite release, from v0.1.0 to v0.5.0 — condensed; the repository's CHANGELOG.md is the full log and gates the tags.
• RoadmapPhase 1 (shipped): six apps, 46 tools, the entity index. Phase 2: Music, Finder, Shortcuts, Safari, the generic command bridge, subscriptions and prebuilt helpers.