Aegis — CC Session Orchestration

Aegis manages interactive Claude Code sessions via HTTP API (port 9100) or MCP tools. Each session runs CC in tmux with JSONL transcript parsing and bidirectional communication.

Prerequisites

1. Aegis server running: curl -s http://127.0.0.1:9100/v1/health
2. MCP configured (optional, for native tool access): see scripts/setup-mcp.sh
3. Verify health: bash scripts/health-check.sh

Core Workflow

create → send prompt → poll status → handle permissions → read result → quality gate → cleanup

Step 1: Create Session

MCP: create_session(workDir, name?, prompt?) HTTP:

SID=$(curl -s -X POST http://127.0.0.1:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"workDir":"/path/to/project","name":"task-name"}' \
  | jq -r '.id')

⚠️ workDir must exist on disk or creation fails silently (returns null id).

Wait 8-10s for CC to boot. Check promptDelivery.delivered in the response — if false, resend via send_message after CC boots.

Step 2: Send Prompt

MCP: send_message(sessionId, text) HTTP:

curl -s -X POST http://127.0.0.1:9100/v1/sessions/$SID/send \
  -H "Content-Type: application/json" \
  -d '{"text":"Your task here"}'

Step 3: Poll Until Idle

MCP: get_status(sessionId) — check status field HTTP:

STATUS=$(curl -s http://127.0.0.1:9100/v1/sessions/$SID/read | jq -r '.status')

Step 4: Handle Permission Prompts

While polling, react to non-idle states:

Step 5: Read Transcript

MCP: get_transcript(sessionId) HTTP: curl -s http://127.0.0.1:9100/v1/sessions/$SID/read

Returns { messages[], status, statusText }. Each message: { role, contentType, text, timestamp }.

Step 6: Quality Gate

Before accepting output, verify:

1. Check transcript for tool errors or failed assertions
2. Run tsc --noEmit and build via send_message if needed
3. Confirm tests pass (request CC to run them)
4. Check for common issues: missing imports, hardcoded values, incomplete implementations

Step 7: Cleanup

MCP: kill_session(sessionId) HTTP: curl -s -X DELETE http://127.0.0.1:9100/v1/sessions/$SID

Always cleanup — idle sessions consume tmux windows and memory.

Common Patterns

Implement Issue

create_session(workDir=repo, name="impl-#123", prompt="Implement issue #123. Read the issue description first, then write code. Don't explain, just implement. Run tests when done.")
→ poll → approve permissions → read transcript → verify tests pass → cleanup

Review PR

create_session(workDir=repo, name="review-PR-456", prompt="Review PR #456. Focus on: security issues, test coverage, API design. Be concise.")
→ poll → read transcript → extract review comments

Fix CI

create_session(workDir=repo, name="fix-ci", prompt="CI is failing on main. Run the failing test suite, identify the root cause, and fix it. Don't add skip/only annotations.")
→ poll → approve bash commands → verify CI green → cleanup

Batch Tasks

Spawn multiple sessions in parallel, then poll all:

for task in "task-a" "task-b" "task-c"; do
  curl -s -X POST http://127.0.0.1:9100/v1/sessions \
    -H "Content-Type: application/json" \
    -d "{\"workDir\":\"$REPO\",\"name\":\"$task\",\"prompt\":\"$task description\"}" \
    | jq -r '.id' >> /tmp/session-ids.txt
done
# Poll all until done
while read SID; do ... done < /tmp/session-ids.txt

Stall Detection and Recovery

A session is stalled when working for >5 minutes with no transcript change.

Detection

HASH1=$(curl -s http://127.0.0.1:9100/v1/sessions/$SID/read | jq -r '.messages | length')
sleep 30
HASH2=$(curl -s http://127.0.0.1:9100/v1/sessions/$SID/read | jq -r '.messages | length')
# If HASH1 == HASH2 and status is still "working", likely stalled

Recovery Options (in order)

1. Nudge — send send_message("Continue. What's blocking you?")
2. Interrupt — POST .../interrupt then resend the task
3. Refine — send a simplified or decomposed version of the task
4. Pivot — kill session, create new one with a different approach
5. Escalate — abandon automated approach, notify human

Troubleshooting

MCP Tool Reference

When MCP is configured, 21 tools are available natively:

Session Lifecycle

Communication

Permission Handling

Monitoring

Advanced

For full API reference, see references/api-quick-ref.md. For agent templates, see references/agent-template.md. For heartbeat/dev-loop templates, see references/heartbeat-template.md.