Aegis Bridge API - v0.3.2-alpha

⚠️ Aegis is in Alpha. APIs may change. See ROADMAP.md for the path to stable.

📦 Package renamed: aegis-bridge → @onestepat4time/aegis. See Migration Guide if you're upgrading.

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

Quick Start

# Install and start
npx @onestepat4time/aegis

# 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."}'
Copy

Prerequisites: tmux and Claude Code CLI.

Windows Setup

On Windows, use psmux as the tmux-compatible backend before starting Aegis.

choco install psmux -y
npx @onestepat4time/aegis
Copy

For full setup, verification, and troubleshooting, see Windows Setup.

For a full walkthrough from install to first session, see Getting Started. For advanced features (pipelines, consensus, model router), see Advanced Features. For the full MCP tools reference, see MCP Tools.

How It Works

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
(tmux)"]
    API --> SSE["SSE Events"]
Copy

MCP Server

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

# Start standalone
@onestepat4time/aegis mcp

# Add to Claude Code
claude mcp add --scope user aegis -- npx @onestepat4time/aegis mcp
Copy

Or via .mcp.json:

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["@onestepat4time/aegis", "mcp"]
    }
  }
}
Copy

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

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

3 prompts — implement_issue, review_pr, debug_session

Ecosystem Integrations

Aegis works beyond Claude Code anywhere an MCP host can launch a local stdio server.

• Cursor integration
• Windsurf integration
• MCP Registry preparation

REST API

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
Copy

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

{
  "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
}
Copy

# 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"
Copy

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

Telegram

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"
Copy

Webhooks

Push events to any endpoint with exponential backoff retry.

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

Multi-Agent Orchestration

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.

Web Dashboard

Aegis ships with a built-in dashboard at http://localhost:9100/dashboard/ — real-time session monitoring, activity streams, and health overview.

npx @onestepat4time/aegis          # visit http://localhost:9100/dashboard/
Copy

Security

Aegis includes built-in security defaults:

• Permission mode — default requires approval for dangerous operations (shell commands, file writes). Change with permissionMode when creating a session.
• Hook secrets — webhook and hook secrets are passed via headers (not query params) to prevent log leakage.
• Auth tokens — protect the API with AEGIS_AUTH_TOKEN (Bearer auth on all endpoints except /v1/health).
• WebSocket auth — session existence is not revealed before authentication.

Configuration

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

Contributing

See CONTRIBUTING.md for the full guide — issue workflow, labels, commit conventions, and PR requirements.

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
Copy

src/
├── cli.ts                # CLI entry (npx @onestepat4time/aegis)
├── 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
Copy

Documentation

• Getting Started — Zero to first session in 5 minutes
• API Reference — Complete REST API documentation
• MCP Tools — 24 MCP tools and 3 prompts
• Advanced Features — Pipelines, consensus, model router, templates
• Enterprise Deployment — Auth, rate limiting, security, production
• Migration Guide — Upgrading from aegis-bridge
• Architecture — Module overview and design
• TypeDoc API — Auto-generated TypeScript reference

Support the Project

License

MIT — Emanuele Santonastaso