Orca Integration

Orca  is a development environment for running multiple AI coding agents in isolated Git worktrees. Orca manages agent execution and workspaces, while AgentTeams acts as the governance layer for team conventions, plans, verification, and completion reporting.

MCP registration does not target Orca. Orca itself is not an MCP client, so it is not one of the agentteams mcp install --client values. Register the AgentTeams MCP server with the individual agents Orca launches (Claude Code, Codex, Cursor CLI, and so on) — running agentteams mcp install inside the worktree detects them. See MCP Integration.

Install the AgentTeams skill

Install the AgentTeams skill in Orca:

npx skills add https://github.com/AgentTeamsRun/conventions --skill agentteams

Bootstrap a worktree

If the AgentTeams CLI is not installed, install it globally first:

npm install -g @agentteams/cli

When the worktree bootstrap hook is installed on the main checkout, every new worktree Orca creates connects its conventions automatically. Nothing else is required.

Check for the hook — and install it if it is missing — from the main checkout root:

agentteams doctor

Worktree bootstrap hook: ready means you are set. Projects whose agentteams init predates this feature may not have the hook, so an existing project is worth checking once.

Where the hook cannot be used — a custom post-checkout hook already exists, or core.hooksPath points somewhere other than the default hooks directory — run this once per worktree from the worktree root instead. It does not run from a nested directory. In that case agentteams doctor reports Worktree bootstrap hook: not installed as guidance and still exits 0:

agentteams init

In a linked Git worktree, this connects the existing AgentTeams configuration from the main checkout. You do not need to configure the project or authenticate again. The worktree’s .agentteams is a link rather than a copy, so convention updates made in the main checkout are visible in the worktree immediately.

Worktrees created with Orca are picked up by the Runner’s automatic worktree discovery like any other linked worktree. Discovery remains available when Orca events are not delivered. See Discovered RunnerBoxes.

Optional immediate lifecycle notifications

Add the following orca.yaml at the repository root to notify the AgentTeams registry immediately after an Orca lifecycle operation:

scripts:
  setup: |
    agentteams worktree notify-created --quiet || true
  archive: |
    agentteams worktree notify-deleted --after-removal --quiet || true

Run agentrunner init --token <token> once on the host and keep the CLI on PATH. Creation must explicitly enable hooks with orca worktree create --setup run (or --run-hooks), and removal must use orca worktree rm --run-hooks. Orca skips archive hooks by default, and --setup skip or another policy that skips hooks does not provide an immediate notification.

Orca runs the archive hook before the Git worktree is removed. --after-removal preserves the pre-removal identity and uses a detached delivery process that sends MISSING only after the path disappears. If removal fails and the path remains, no deleted event is sent.

Hooks are best-effort: a CLI or network failure never reverses a successful local worktree operation. If an event is lost, the next Runner Git reconciliation remains the correctness path and restores AVAILABLE or MISSING.

Work under AgentTeams governance

After bootstrap, .agentteams/convention.md is available in the worktree. Before starting work, have the agent read the file and follow it as the single source of truth for working rules. See Plans for the flow from plan approval through execution and completion reporting.