Skip to Content
GuidesUsing Agent Harbor from an AI Agent

Using Agent Harbor from an AI Agent

Agent Harbor is designed not only for human developers at a terminal, but also for supervising AI agents (such as the Manager Agent, an orchestrator session, or any agent running inside a shell) to spawn, steer, branch, and review child worker sessions.

For AI Agents Reading This Page: When IN_AGENT_SHELL=1 or AH_SESSION_ID is set in your environment, you are already executing inside an Agent Harbor session. Every child ah <agent> or ah session command you run automatically records your session ID as its parent_session_id in ah session tree.

1. Launching Child Agents Without Blocking Your Turn (--detach)

An AI agent executing shell tool calls must never launch an interactive TUI child session in the foreground, as doing so will block your shell tool call waiting for TTY input.

Always pass --detach (or --non-interactive --detach) so ah prints the new session ID and exits immediately:

# Spawn a child Claude Code worker inside an isolated Copy-on-Write branch
CHILD_ID=$(ah claude \
  --detach \
  --branch work/parser-optimisation \
  --role rust-engineer \
  "Optimise the zero-copy lexer in crates/parser and ensure cargo test passes")
 
echo "Spawned child session: $CHILD_ID"

2. Empty Starts & Programmatic Multi-Turn Steering (--non-interactive)

When you want to initialise a child agent’s sandbox and CoW workspace first and send it a sequence of prompts across multiple steps, start an empty headless session with --non-interactive --detach (omitting the initial prompt):

# 1. Start an idle headless Codex session in its own CoW branch
WORKER_ID=$(ah codex --non-interactive --detach --branch work/db-migration)
 
# 2. Send the first task prompt and wait for the turn to complete
ah session prompt "$WORKER_ID" --wait "Generate the SQL migration for adding tenant_id to invoices"
 
# 3. Inspect the resulting diff inside the child's CoW branch
ah branch diff work/db-migration
 
# 4. Send a follow-up instruction to the same warm session
ah session prompt "$WORKER_ID" --wait "Now update the SQLx queries in crates/billing and run cargo check"

3. Monitoring Progress & Inspecting Child Output

Supervising agents should use structured non-interactive subcommands rather than interactive ah session attach:

# Check the current status (running, idle, waiting_approval, completed, failed)
ah session status "$CHILD_ID" --json
 
# Read the structured turn-by-turn transcript
ah session view "$CHILD_ID" --json
 
# Read recent stdout/stderr logs without blocking
ah session logs "$CHILD_ID" --tail 100

4. ah session branch vs ah session children vs ah branch create

Supervising agents frequently coordinate parallel explorations. Be careful to choose the right command for the layer you are manipulating:

GoalCommand to RunEffect
Create a fresh CoW workspace clone before launching a workerah branch create <branch-name>Clones the current filesystem state (including build caches) using APFS/Btrfs/ZFS/ReFS CoW. Does not start an agent session.
Fork an existing agent session from a specific turn (--at-turn N)ah session branch <session-id> --at-turn N --name <branch-name> --prompt "..."Clones both the agent’s conversation history up to turn N and its CoW filesystem snapshot at turn N, launching a new child session.
List sessions forked from a sessionah session branches <session-id>Lists conversation/filesystem forks created via ah session branch.
List sub-agents spawned by a parent sessionah session children <session-id>Lists child sessions launched while AH_SESSION_ID=<session-id> was active.
Inspect the full hierarchyah session tree <session-id>Displays the combined tree of spawned child sessions, turn forks, and CoW branches.

5. Automated Spec & Code Verification (ah review)

Before merging a child worker’s CoW branch back into the main workspace or opening a pull request, run ah review to have an independent reviewer agent verify the diff against the specification and test suite:

# Run an automated review of the child branch against the task specification
ah review \
  --branch work/parser-optimisation \
  --against-spec specs/Parser-Zero-Copy.md \
  --json
ConfigurationOverview