Orchestrate Claude Code sessions via REST API, MCP, CLI, webhooks, or Telegram.

# Install and start
npx aegis-bridge

# Create a session
curl -X POST http://localhost:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "feature-auth", "workDir": "/home/user/my-project", "prompt": "Build a login page with email/password fields."}'

# Send a follow-up
curl -X POST http://localhost:9100/v1/sessions/abc123/send \
  -H "Content-Type: application/json" \
  -d '{"text": "Add form validation: email must contain @, password min 8 chars."}'

Prerequisites: tmux and Claude Code CLI.

Need a full walkthrough from install to first session? See Getting Started.

Aegis wraps Claude Code in tmux sessions and exposes everything through a unified API. No SDK dependency, no browser automation — just tmux + JSONL transcript parsing.

1. Creates a tmux window → launches Claude Code inside it
2. Sends messages via tmux send-keys with delivery verification (up to 3 retries)
3. Parses output from both terminal capture and JSONL transcripts
4. Detects state changes: working, idle, permission prompts, stalls
5. Fans out events to Telegram, webhooks, and SSE streams

graph LR
    OC["OpenClaw"] --> API["Aegis :9100"]
    CI["CI/CD"]     --> API
    TG["Telegram"]  --> API
    WH["Webhooks"]  --> API
    MCP["MCP"]      --> API
    API --> CC["Claude Code<br/>(tmux)"]
    API --> SSE["SSE Events"]

Connect any MCP-compatible agent to Claude Code — the fastest way to build multi-agent workflows.

# Start standalone
aegis-bridge mcp

# Add to Claude Code
claude mcp add --scope user aegis -- npx aegis-bridge mcp

Or via .mcp.json:

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["aegis-bridge", "mcp"]
    }
  }
}

21 tools — create_session, send_message, get_transcript, approve_permission, batch_create_sessions, create_pipeline, and more.

4 resources — aegis://sessions, aegis://sessions/{id}/transcript, aegis://sessions/{id}/pane, aegis://health

3 prompts — implement_issue, review_pr, debug_session

All endpoints under /v1/.

# First call → creates session (201)
curl -s -o /dev/null -w "%{http_code}" -X POST http://localhost:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"workDir": "/home/user/project", "prompt": "Fix the tests"}'
# → 201

# Same workDir while idle → reuses session (200)
curl -s -o /dev/null -w "%{http_code}" -X POST http://localhost:9100/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"workDir": "/home/user/project", "prompt": "Now add error handling"}'
# → 200, body includes "reused": true

curl -X POST http://localhost:9100/v1/handshake \
  -H "Content-Type: application/json" \
  -d '{"protocolVersion": "1", "clientCapabilities": ["session.create", "session.transcript.cursor"]}'

{
  "protocolVersion": "1",
  "serverCapabilities": ["session.create", "session.resume", "session.approve", "session.transcript", "session.transcript.cursor", "session.events.sse", "session.screenshot", "hooks.pre_tool_use", "hooks.post_tool_use", "hooks.notification", "hooks.stop", "swarm", "metrics"],
  "negotiatedCapabilities": ["session.create", "session.transcript.cursor"],
  "warnings": [],
  "compatible": true
}

# Get the newest 50 messages
curl http://localhost:9100/v1/sessions/abc123/transcript/cursor

# Get the next page (pass oldest_id from previous response)
curl "http://localhost:9100/v1/sessions/abc123/transcript/cursor?before_id=16&limit=50"

# Filter by role
curl "http://localhost:9100/v1/sessions/abc123/transcript/cursor?role=user"

{
  "messages": [...],
  "has_more": true,
  "oldest_id": 16,
  "newest_id": 25
}

Bidirectional chat with topic-per-session threading. Send prompts from your phone, get completions pushed back.

export AEGIS_TG_TOKEN="your-bot-token"
export AEGIS_TG_GROUP="-100xxxxxxxxx"

Push events to any endpoint with exponential backoff retry.

export AEGIS_WEBHOOKS="https://your-app.com/api/aegis-events"

AI orchestrators delegate coding tasks through Aegis — monitor progress, send refinements, handle errors, all without a human in the loop.

Works with OpenClaw, custom orchestrators, or any agent that can make HTTP calls.

Priority: CLI --config > ./aegis.config.json > ~/.aegis/config.json > defaults

git clone https://github.com/OneStepAt4time/aegis.git
cd aegis
npm install
npm run dev          # build + start
npm test             # vitest suite
npx tsc --noEmit     # type-check

src/
├── cli.ts                # CLI entry (npx aegis-bridge)
├── server.ts             # Fastify HTTP server + routes
├── session.ts            # Session lifecycle
├── tmux.ts               # tmux operations
├── monitor.ts            # State monitoring + events
├── terminal-parser.ts    # Terminal state detection
├── transcript.ts         # JSONL parsing
├── mcp-server.ts         # MCP server (stdio)
├── events.ts             # SSE streaming
├── pipeline.ts           # Batch + pipeline orchestration
├── channels/
│   ├── manager.ts        # Event fan-out
│   ├── telegram.ts       # Telegram channel
│   └── webhook.ts        # Webhook channel
└── __tests__/            # Vitest tests

MIT — Emanuele Santonastaso