Contents

Agents

gitta works with any tool that makes Git worktrees. Claude Code gets warnings automatically through hooks. Cursor and Codex get them through MCP tools, which work only when the agent calls them.

Tool	How warnings arrive	Automatic
Claude Code	Hooks after every tool call, and before the agent finishes	Yes
Cursor, Codex	MCP tools the agent calls	Only when the agent calls them. Tell it to, in `AGENTS.md`
Any other tool	`gitta status`, `gitta watch`, the git merge output and the check on pull requests	No

Claude Code

gitta init adds two hooks to ~/.claude/settings.json:

Hook	What it does
`PostToolUse`	After each tool call, gitta tells the agent about changes by other agents that affect its work.
`Stop`	When the agent's last merge failed its tests, gitta sends it back once with the repair note. Nothing else happens when it finishes. Other agents' unfinished work is never tested here, because the merge itself runs the tests.

What the agent reads

A hook note names the other agent and the function it changed, and shows that agent's new definition line. It is information, and the agent hears it once:

In the ci99 agent's session

Gitta: agent ci-level changed `wilson`, which your new code in bench/aidev-replay/analyze.py calls. Check that your code still fits. Their version: bench/aidev-replay/analyze.py:23: def wilson(k, n, *, z=1.96):

Handle it yourself and tell the user in one sentence.

When a merge fails its tests, the agent gets one short repair note. It names the failing tests with their first error lines and, when a function the code relies on changed, its new definition line. The merge output shows it first, and the agent's hook does not repeat it. If the agent stops while its merge still fails, the Stop hook sends the note once more:

In the ci99 agent's session

Gitta: your merge into main failed its tests (test_ci99.T.test_wider). Fix it and merge again.
  TypeError: wilson() takes 2 positional arguments but 3 were given
Now on main: bench/aidev-replay/analyze.py:23: def wilson(k, n, *, z=1.96):

The agent fixes its code and tells you in its chat, in one sentence, what gitta caught and what it changed.

The hooks do nothing outside repositories where you ran gitta init. They print nothing there. Inside one, a hook scans only its own agent's worktree and reuses the last scan of the others. See Hooks are slow.

Start Claude Code in a worktree as usual, for example with claude --worktree. gitta finds the worktree the next time it runs. See Run multiple Claude Code agents in parallel.

To skip the hooks, run gitta init --no-claude. To add them later, run gitta install claude.

Cursor and Codex

When Cursor or Codex is installed, gitta init registers gitta as an MCP server in ~/.cursor/mcp.json or ~/.codex/config.toml. The agent then has these tools:

Tool	What the agent can do
`gitta_status`	See the other agents, what each changed, and the warnings that affect it.
`gitta_sync`	Merge work that reached main into its own copy.
`gitta_check`	Run your tests on its work combined with each other agent's work.
`gitta_claim`, `gitta_release`	Announce a symbol or path that it is about to change, so others are warned before they build on it.

Registering the tools does not make an agent use them. An MCP tool runs only when the agent decides to call it, so put an instruction in your AGENTS.md, for example:

Merge with git as usual. gitta runs the tests on the combined code during the merge.
If a merge fails, fix it and merge again.

To register later, run gitta install cursor or gitta install codex.

Git worktrees with Claude Code, Cursor and Codex

Each tool makes its worktrees in its own place. gitta reads git worktree list, so it finds them all without setup. It names each agent after the worktree's branch, or after its folder when the worktree has no branch.

Tool	How it makes worktrees	Where they go	How gitta picks them up
Claude Code	`claude --worktree <name>`, the `EnterWorktree` tool, subagents with `isolation: worktree`, and desktop sessions. A `WorktreeCreate` hook can replace the Git steps.	`.claude/worktrees/<name>/` in the repository, on branch `worktree-<name>`	Found on the next gitta command or hook. The hooks in `~/.claude/settings.json` warn each session.
Cursor	Agents Window agents in a worktree, `/worktree` and `/best-of-n` in the editor. Setup commands come from `.cursor/worktrees.json`.	A worktree root that Cursor manages. Run `git worktree list` to see it.	Found the same way. Warnings come through the MCP tools.
Codex app	A new chat in a worktree, started from the `HEAD` of the branch you pick. The worktree has a detached `HEAD` until you choose Create branch here.	`$CODEX_HOME/worktrees`, or the worktree root in Settings	Found the same way, named after its folder while detached. Warnings come through the MCP tools.

Clean up worktrees with the tool that made them. Cursor and Codex delete old managed worktrees by themselves. gitta drops an agent when its worktree is gone from git worktree list. Merge or push the work first.

On Linux, gitta init can make new Claude Code and Cursor worktrees share one checkout copy-on-write. It does this through a WorktreeCreate hook for Claude Code and a first setup step in .cursor/worktrees.json for Cursor. See Linux workspaces.

Sources: Anthropic, Run parallel sessions with worktrees. Cursor, Worktrees. OpenAI, Codex worktrees. For a full Claude Code walkthrough, see Run multiple Claude Code agents in parallel.

Other tools

gitta watches every worktree of the repository. Conductor, Claude Squad and worktrees made by hand all work. Use gitta status or gitta watch to see their warnings. The GitHub check covers cloud agents that only open pull requests.

AGENTS.md and CLAUDE.md

Agents read an instruction file at the start of each session. Codex, Cursor and many other tools read AGENTS.md. Claude Code reads CLAUDE.md, which can import AGENTS.md with a line @AGENTS.md. A few lines about gitta in that file tell every agent what to do with a warning.

## Working with gitta
This repository uses gitta. Other agents work in parallel in their own worktrees.
- Merge with git as usual. If gitta stops a merge, fix it and merge again.
- Handle gitta's findings yourself, and tell the user in one sentence what gitta caught.
- Do not delete or skip tests to make a check pass. gitta reports it at merge time.
- Do not edit AGENTS.md or CLAUDE.md unless a person asks you to.

Claude Code gets warnings through its hooks even without these lines. The lines help it act on them the same way each time. For Cursor and Codex, the merge output is where the agent learns what failed.

A person should add and commit this text. When an agent changes one of these files, gitta warns about it, because the change reaches every agent. Sources: AGENTS.md, Anthropic, Manage Claude's memory.

Run a batch of agents

gitta run starts one agent per task, each in its own worktree. Merge the results with git as usual.

Terminal

$ gitta run --agent claude --task "Add type hints to bench/aidev-replay/analyze.py" --task "Add tests for wilson"

Use --agent codex for Codex, or --cmd with a command template that contains {task} for any other tool.

Settings files that init changes

File	Change
`.gitta/` in the repository	gitta's settings and state. Listed in `.git/info/exclude`, so Git ignores it.
Git hooks of the repository	`pre-merge-commit`, `post-merge`, `reference-transaction` and `pre-push`, in the folder that `core.hooksPath` names. A hook you already had is kept and still runs first.
`~/.claude/settings.json`	Two hooks. A backup is kept next to the file.
`~/.cursor/mcp.json`, `~/.codex/config.toml`	The gitta MCP server, when the tool is installed.
`.claude/settings.local.json` (Linux)	Worktree hooks for shared workspaces. Skip with `--no-cow`. `gitta install claude` also adds the two hooks here, because Claude Code reads this file at the main checkout in worktree sessions.

gitta merges into existing files. It never replaces your other settings. Uninstall removes exactly what it added.