How Cate Works

Cate makes AI coding a team sport, orchestrating agents on your machine while capturing context in Jira, Linear, and GitHub.

The big picture

Two workflows, both familiar

Cate’s built to get tasks done, not manage a dozen chats. Its two core workflows are modeled on how teams already ship software:

1. Pair — Peer coding with a built-in note-taker. The agent pairs with you live, captures key decisions, prepares the pull request, and handles the tracker paperwork.
2. Plan Mode — A planning agent interviews you, decomposes the work into a spec with linked sub-issues, and hands it to worker agents. Independent reviewers verify before you add the finishing touches.

Your issue tracker, your process

Issue trackers have been central to how teams ship for decades. Cate is built to join your team, not run a parallel process. Its built-in tracker works great for solo projects. For teams, connect Jira, Linear, or GitHub Issues and every agent’s work surfaces in the tools you already use.

Shared context that compounds

Agents and humans both need context, and context is more than code. It’s the shared knowledge of your team — why things are the way they are, how standards evolved, what worked, and what didn’t. Cate captures all of it:

1. Every task records acceptance criteria, implementation plans, diagrams, key decisions, review feedback, and human/agent collaboration — all within your issue tracker.
2. Every project maintains an indexed, searchable, Markdown-based knowledge base within its Git repository.

All of it is available in plain language, in the open, for your team, your agents, and whatever comes next.

Under the hood

Cate and your AI agents

Cate drives Claude Code through its official SDK. Your existing authentication and configuration just work — if you have a ~/.claude/settings.json file, Cate honors it. If you have an Anthropic API key or a Max subscription, Cate uses it directly.

Cate never intercepts or accesses your authentication credentials. It isn’t a token broker or a proxy: your API keys and subscriptions stay between you and your provider, and we take every reasonable effort to use them efficiently. Your code stays between you and your AI provider — it’s never visible to Blue Ghost.

Worktrees and agents

Cate’s pool of worker and review “agents” is shorthand. Behind the scenes, each agent is a single-task session assigned a specific role, a specific issue, and its own Git worktree. That isolation means agents work in parallel without stepping on each other — or on your working copy.

Worktrees are created when an agent picks up an issue and pruned when they’re no longer needed. Cate projects ship with four code agents and two review agents by default; adjust the count up or down depending on how fast you want to move.

Git and .cate

Every Cate project is a Git repository with a .cate directory at its root. At a minimum, that directory contains workflows.json — the file that maps your issue tracker’s statuses and transitions to Cate’s task phases, like To Do, In Progress, AI Review, and Ready for Review.

As your project grows, run configurations, custom commands, guardrails, and shared research all live in .cate too — committed to the repo and available to every agent and teammate. That’s why you occasionally need to reload a project after adding a new custom workflow: Cate reads the configuration from the repository, not from an external service.

Local data

Cate stores all project-level data in conventional OS directories:

OS	Path
macOS	~/Library/Application Support/Cate/
Windows	%APPDATA%\Cate\

Inside that directory you’ll find:

1. credentials.bin — An encrypted file containing any OAuth credentials you’ve configured (GitHub, Jira, Linear). It’s encrypted using your OS’s native keychain (macOS Keychain or Windows DPAPI). Deleting it removes those connections. See Credentials for details.
2. leftenant.db — A SQLite database tracking Cate projects, agents, and tasks.
3. worktrees/ — The directory containing agent worktrees, kept here so they don’t clutter your project directories.

You can override the data directory with the --data-dir flag when launching Cate.