A coding agent for your terminal and desktop that works with any model provider.

Cavvy reads, edits and runs code in your project, asks before doing anything risky, and keeps your API keys out of everything it writes. Use it in the terminal, in its desktop app, or in your browser: a session started in one continues in the others.

Highlights

• Any model. Anthropic, OpenAI, Gemini and Vertex AI, OpenRouter, Groq, DeepSeek, xAI, Mistral, Together, Fireworks and Cerebras; local models through Ollama and LM Studio; and any OpenAI-compatible endpoint. One searchable list, with context sizes and prices.
• Your Claude or ChatGPT plan. Cavvy runs your own Claude Code or Codex, signed in by you, so a subscription works without an API key. Several accounts per CLI, switched between responses.
• Asks before it acts. Five permission modes, from asking before every edit to an auto mode where workspace edits go through, shell commands run in a sandbox (on macOS), and a reviewer model checks the rest.
• A desktop app. Several sessions at once, approvals with diff previews, a review pane where you commit, push and open pull requests, worktrees, a terminal panel, a browser the agent can drive, and on a Mac with Xcode, iOS simulators it can drive too.
• Other models as sub-agents. Hand a task to another provider's model: a second opinion, a review, a cheaper research run.
• Works with what you already use. MCP servers, Claude Code plugins and marketplaces, hooks in Claude Code's format, and CLAUDE.md and AGENTS.md memory files.
• Keys stay secret. They're kept in the OS keychain (or an owner-only file where there's none), sent only to the endpoint they're for, and redacted from tool output, transcripts and logs.

Install

Cavvy needs Bun (it's tested on 1.3) and Git, and a model to talk to: an API key, a local model, or Claude Code or Codex signed in to your plan. The terminal app and the browser GUI run on macOS and Linux; the desktop app needs macOS 13 or later.

git clone https://github.com/Aqu1bp/cavvy.git
cd cavvy
bun install
bun link                     # puts `cavvy` on your PATH (or add bin/ to it)

bun run build makes a standalone binary instead, in dist/cavvy.

The GUI has dependencies of its own. Build it once, and again after pulling GUI changes:

bun install --cwd gui && bun run gui:build

To try it without any keys, bun run gui:demo serves it with a mock model and a demo project.

The desktop app builds from the same checkout. It installs into /Applications (or ~/Applications if that isn't writable), and from then on updates itself from main, so keep the checkout:

bun run desktop:install

Quick start

cavvy                                    # start in the current project
cavvy -p "explain src/agent/agent.ts"    # one-shot, for scripts
cavvy gui                                # the GUI in your browser

In the terminal app, /login adds an API key (or /login claude-code, /login codex for your plan), /model picks a model, and shift+tab cycles the permission mode. In the desktop app, Settings → Providers adds keys and turns on Claude Code or Codex.

Documentation

Page	What's in it
Providers and models	API keys, Vertex AI, the model list, fast mode, and how keys are kept safe
Claude and ChatGPT subscriptions	Running your own Claude Code or Codex, several accounts, continuing a CLI session
Other coding agents (ACP)	Running your own OpenCode or Grok Build, and how their permissions work
Antigravity	Running your own Antigravity CLI with your plan, and how Cavvy's permission gate works
Permissions	Permission modes, auto mode's sandbox and reviewer, rules
The terminal app	Shortcuts, commands, rewinding and forking, the status line, notifications
Desktop app and GUI	Building, installing and updating, using it, the terminal panel, project scripts, security
Changes, worktrees and comparing models	The review pane, committing and pushing, pull requests, worktrees, one task on several models
Browser	The browser tools and the Browser pane
Simulator	iOS simulators the agent drives, and the Simulator pane
Sub-agents on other models	Delegating a task to another provider's model
Asking for secrets	Tokens the agent asks you for, kept out of its sight
Project files	CAVVY.md and other memory files, settings files, trust
MCP · Plugins · Hooks	Extending it
Diagnostics after edits	Language servers checking each edit
Headless runs and the SDK	cavvy -p in scripts and CI, and the TypeScript SDK
Development	Building, testing, and how the code is laid out

Contributing

Issues and pull requests are welcome. Development covers building and testing, and AGENTS.md has the working rules for branches, tests and CI. Please report security problems privately, as SECURITY.md explains.

License

MIT, see LICENSE. Third-party material and its licenses are listed in THIRD_PARTY_NOTICES.md.