Aegis — CC Session Orchestration#

Aegis manages interactive Claude Code sessions via HTTP API (port 9100) or MCP tools. Each session runs CC via the ACP runtime 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#

text

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

Step 1: Create Session#

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

bash

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:

bash

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:

bash

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:

StatusActionidleDone — read resultworkingWait (poll every 5s)permission_prompt``POST .../approve (trust folder, tool use)bash_approval``POST .../approve or POST .../reject``plan_mode``POST .../approve (option 1) or POST .../escape``ask_question``POST .../send with answerunknown``GET .../pane for raw terminal output

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 memory.

Common Patterns#

Implement Issue#

text

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#

text

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#

text

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:

bash

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#

bash

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#

ProblemFixConnection refused on 9100Aegis not running. Check scripts/health-check.shSession stuck at unknown``GET .../pane for raw output. May need POST .../escapePermission loop (approve keeps coming)Likely bash approval. Check transcript for the command. Reject if unsafepromptDelivery: "failed"CC didn't boot yet. Wait 10s and resend via send_messageSession not appearing in list_sessionsCheck workDir filter. Session may have been killedHigh memory usageKill idle sessions. Use list_sessions to find orphans

MCP Tool Reference#

When MCP is configured, 24 tools are available natively:

Session Lifecycle#

ToolDescriptioncreate_sessionSpawn new CC session (workDir, name, prompt)list_sessionsList sessions, filter by status/workDirget_statusDetailed session status + healthkill_sessionKill session + cleanup resourcesbatch_create_sessionsSpawn multiple sessions at once

Communication#

ToolDescriptionsend_messageSend text to a sessionsend_bashExecute bash via ! prefixsend_commandSend /slash commandget_transcriptRead conversation transcriptcapture_paneRaw terminal outputget_session_summarySummary with message counts + duration

Permission Handling#

ToolDescriptionapprove_permissionApprove pending promptreject_permissionReject pending promptescape_sessionSend Escape key (dismiss dialogs)interrupt_sessionSend Ctrl+C

Monitoring#

ToolDescriptionserver_healthServer version, uptime, session countsget_session_metricsPer-session performance metricsget_session_latencyLatency measurements

State (Memory Bridge)#

ToolDescriptionstate_setSet a shared state key/value entrystate_getGet a shared state key/value entrystate_deleteDelete a shared state key/value entry

Advanced#

ToolDescriptionlist_pipelinesList multi-step pipelinescreate_pipelineCreate orchestrated pipelineget_swarmSwarm status for parallel sessions

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.