Aegis

Orchestrate Claude Code sessions via Aegis HTTP/MCP bridge. Use when spawning CC sessions for coding tasks, implementing issues, reviewing PRs, fixing CI, ba...

Security Scan

The skill appears to do what it says (orchestrate local Aegis/Claude Code sessions), but its runtime instructions and included scripts perform actions that are not declared in the metadata (modify Claude config, auto-approve permission prompts, rely on npx to fetch code) and those behaviors are risky and worth review before installing.

Purpose & Capability

The skill claims no required config paths or credentials, yet the provided scripts modify ~/.claude/settings.json or project .mcp.json (setup-mcp.sh). The skill also assumes availability of external tools (jq, curl, claude, npx) even though no required binaries are declared. Writing to other tool configuration and relying on npx to run 'aegis-bridge' are not aligned with the declared 'no config paths / no binaries' metadata.

Instruction Scope

SKILL.md and included scripts instruct automated behaviors that go beyond simple orchestration: the heartbeat script auto-approves permission_prompt and bash_approval states (POST /approve) without human confirmation, and setup-mcp.sh will write/alter user Claude settings. Those instructions can cause arbitrary command execution in sessions and change user configuration files; they should be explicit and gated but are presented as default flow.

Install Mechanism

There is no install spec (instruction-only), which reduces install-time risk. However the scripts reference 'npx aegis-bridge mcp' as the MCP command: that will fetch and run code from npm at runtime if used. The skill doesn't declare or vendor that package, so using the MCP 'npx' path introduces a deferred code-download risk.

Credentials

Metadata lists no required environment variables, but scripts and instructions use/accept AEGIS_HOST/AEGIS_PORT and read/write $HOME config files. The skill will interact with local filesystem paths (workDir must exist) and edit ~/.claude/settings.json — access that is not reflected in the declared requirements and may be disproportionate to what a simple orchestration helper should require.

Persistence & Privilege

The skill's setup script modifies another tool's per-user configuration (~/.claude/settings.json) to add an MCP entry, which is persistent and affects the user's Claude Code client. Combined with the heartbeat's auto-approve behavior, this is an elevated privilege: it can both enable automated integration and make approval of potentially dangerous operations automatic.

What to consider before installing

Before installing or using this skill: (1) Review the two scripts (setup-mcp.sh and health-check.sh) line-by-line — they will modify ~/.claude/settings.json (or .mcp.json) and may add an npx command that downloads code at runtime. (2) Understand and decide whether automatic approval of permission prompts is acceptable — the heartbeat script auto-approves permission_prompt and bash_approval by default. That can allow remote code execution within sessions. (3) Ensure jq, curl, and optionally the claude CLI are available; the skill does not declare these dependencies. (4) If you want to try it, run it in a disposable/test environment first and back up ~/.claude/settings.json; prefer manual approval handling rather than the provided auto-approve paths. (5) If you cannot inspect or control the package 'aegis-bridge' pulled via npx, avoid enabling the npx path — prefer a vetted local Aegis binary or review the package source before use.

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:

Status	Action
idle	Done — read result
working	Wait (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 answer
unknown	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 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

Problem	Fix
Connection refused on 9100	Aegis not running. Check scripts/health-check.sh
Session stuck at unknown	GET .../pane for raw output. May need POST .../escape
Permission loop (approve keeps coming)	Likely bash approval. Check transcript for the command. Reject if unsafe
promptDelivery: "failed"	CC didn't boot yet. Wait 10s and resend via send_message
Session not appearing in list_sessions	Check workDir filter. Session may have been killed
High memory usage	Kill idle sessions. Use list_sessions to find orphans

MCP Tool Reference

When MCP is configured, 21 tools are available natively:

Session Lifecycle

Tool	Description
create_session	Spawn new CC session (workDir, name, prompt)
list_sessions	List sessions, filter by status/workDir
get_status	Detailed session status + health
kill_session	Kill session + cleanup resources
batch_create_sessions	Spawn multiple sessions at once

Communication

Tool	Description
send_message	Send text to a session
send_bash	Execute bash via ! prefix
send_command	Send /slash command
get_transcript	Read conversation transcript
capture_pane	Raw terminal output
get_session_summary	Summary with message counts + duration

Permission Handling

Tool	Description
approve_permission	Approve pending prompt
reject_permission	Reject pending prompt
escape_session	Send Escape key (dismiss dialogs)
interrupt_session	Send Ctrl+C

Monitoring

Tool	Description
server_health	Server version, uptime, session counts
get_session_metrics	Per-session performance metrics
get_session_latency	Latency measurements

Advanced

Tool	Description
list_pipelines	List multi-step pipelines
create_pipeline	Create orchestrated pipeline
get_swarm	Swarm 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.