⚠️ 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."}'

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

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

Loading

---

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

Or via .mcp.json:

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

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

Method	Endpoint	Description
GET	/v1/health	Server health & uptime
POST	/v1/sessions	Create (or reuse) a session
GET	/v1/sessions	List sessions
GET	/v1/sessions/:id	Session details
GET	/v1/sessions/:id/read	Parsed transcript
GET	/v1/sessions/:id/events	SSE event stream
POST	/v1/sessions/:id/send	Send a message
POST	/v1/sessions/:id/approve	Approve permission
POST	/v1/sessions/:id/reject	Reject permission
POST	/v1/sessions/:id/interrupt	Ctrl+C
DELETE	/v1/sessions/:id	Kill session
POST	/v1/sessions/batch	Batch create
POST	/v1/handshake	Capability negotiation
POST	/v1/pipelines	Create pipeline
POST	/v1/memory	Set memory entry
GET	/v1/memory	List memory entries
GET	/v1/memory/:key	Get memory entry
DELETE	/v1/memory/:key	Delete memory entry
POST	/v1/templates	Create session template
GET	/v1/templates	List templates
GET	/v1/templates/:id	Get template
PUT	/v1/templates/:id	Update template
DELETE	/v1/templates/:id	Delete template
POST	/v1/dev/route-task	Route task to model tier
GET	/v1/dev/model-tiers	List model tiers
GET	/v1/diagnostics	Server diagnostics

Full API Reference

Method	Endpoint	Description
GET	/v1/sessions/:id/pane	Raw terminal capture
GET	/v1/sessions/:id/health	Health check with actionable hints
GET	/v1/sessions/:id/summary	Condensed transcript summary
GET	/v1/sessions/:id/transcript/cursor	Cursor-based transcript replay
POST	/v1/sessions/:id/screenshot	Screenshot a URL (Playwright)
POST	/v1/sessions/:id/escape	Send Escape
GET	/v1/pipelines	List all pipelines
GET	/v1/pipelines/:id	Get pipeline status

Session States

State	Meaning	Action
working	Actively generating	Wait or poll /read
idle	Waiting for input	Send via /send
permission_prompt	Awaiting approval	/approve or /reject
asking	Claude asked a question	Read /read, respond /send
stalled	No output for >5 min	Nudge /send or DELETE

Session Reuse

When you POST /v1/sessions (or POST /sessions) with a workDir that already has an idle session, Aegis reuses that session instead of creating a duplicate. The existing session's prompt is delivered and you get the same session object back.

Response differences:

	New Session	Reused Session
Status	201 Created	200 OK
reused	false	true
promptDelivery	{ delivered, attempts }	{ delivered, attempts }

# 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

Only idle sessions are reused. Working, stalled, or permission-prompt sessions are ignored — a new one is created.

Capability Handshake

Before using advanced integration paths, clients can negotiate capabilities with Aegis via POST /v1/handshake. This prevents version-drift breakage.

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

Response (200 OK when compatible):

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

Field	Description
protocolVersion	Server's protocol version ("1" currently)
serverCapabilities	Full list of server-supported capabilities
negotiatedCapabilities	Intersection of client + server capabilities
warnings	Non-fatal issues (unknown caps, version skew)
compatible	true (200) or false (409 Conflict)

Returns 409 if the client's protocolVersion is below the server minimum.

Cursor-Based Transcript Replay

Stable pagination for long transcripts that doesn't skip or duplicate messages under concurrent appends. Use instead of offset-based /read when you need reliable back-paging.

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

Query params:

Param	Default	Description
before_id	(none)	Cursor ID to page before. Omit for newest entries.
limit	50	Entries per page (1–200).
role	(none)	Filter: user, assistant, or system.

Response:

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

Cursor IDs are stable — they won't shift when new messages are appended. Use oldest_id from one response as before_id in the next to page backwards without gaps or overlaps.

---

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"

Webhooks

Push events to any endpoint with exponential backoff retry.

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

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/

---

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

Variable	Default	Description
AEGIS_PORT	9100	Server port
AEGIS_HOST	127.0.0.1	Server host
AEGIS_AUTH_TOKEN	—	Bearer token for API auth
AEGIS_PERMISSION_MODE	default	default, bypassPermissions, plan, acceptEdits, dontAsk, auto
AEGIS_TMUX_SESSION	aegis	tmux session name
AEGIS_TG_TOKEN	—	Telegram bot token
AEGIS_TG_GROUP	—	Telegram group chat ID
AEGIS_WEBHOOKS	—	Webhook URLs (comma-separated)

---

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

Project Structure

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

---

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