Aegis Bridge API - v0.6.7

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

📦 Package: @onestepat4time/aegis on npm. See ACP Migration Guide if upgrading from aegis-bridge.

Run Claude Code agents from your terminal. Approve from your phone. See everything on one dashboard.

Quick Start

One command. Zero config. Claude Code responds in your terminal.

npx --package=@onestepat4time/aegis ag run "Summarize this folder and suggest improvements" --cwd ./my-project
Copy

That's it. Aegis:

1. Bootstraps its config (first run only)
2. Starts the server
3. Creates a Claude Code session
4. Streams Claude's response to your terminal

When Claude needs permission to run a command or edit a file, you'll see a prompt in your terminal. Approve or deny right there.

$ npx --package=@onestepat4time/aegis ag run "Build a login page" --cwd ./my-project

  Aegis v0.7.0
  ✓ Claude Code found
  ✓ Server started → http://127.0.0.1:9100/dashboard
  ✓ Session created: cc-build-a-login-page

  [Claude] I'll build a login page with email and password fields...
  [Claude] ├── Creating src/components/LoginForm.tsx
  [Claude] └── Creating src/pages/Login.tsx

  🔔 Permission required: Write to src/components/LoginForm.tsx
  Allow? [Y/n] >
Copy

npm install -g @onestepat4time/aegis
ag run "Your prompt here" --cwd ./my-project
Copy

Next Steps

After your first session, you might want to:

• Dashboard — open http://127.0.0.1:9100/dashboard to see sessions, cost analytics, and audit trails
• Telegram — approve agent actions from your phone: ag setup telegram (one guided setup)
• MCP — let Claude Code control Aegis: claude mcp add --scope user aegis -- ag mcp
• Multiple sessions — ag run "fix the tests" & ag run "update the README" (parallel agents)

ag init              # Interactive setup (token, model, Telegram, etc.)
ag init --defaults    # Non-interactive — use all defaults
ag init --force       # Overwrite existing config
Copy

ag init --list-templates
ag init --from-template code-reviewer
Copy

Prerequisites: Node.js ≥ 20 and Claude Code CLI (authenticated). That's it.

CLI naming: the primary command is ag. The legacy name aegis is preserved as an alias.

Windows

npm install -g @onestepat4time/aegis
ag run "Your prompt here" --cwd C:\my-project
Copy

For troubleshooting, see Windows Setup.

Learn more: Getting Started · MCP Tools · BYO LLM · Advanced Features · Deployment Guide

How It Works

Aegis bridges Claude Code sessions through the Agent Client Protocol (ACP) and exposes everything through a unified API. No SDK dependency, no browser automation — just JSON-RPC over stdio.

1. Spawns claude-agent-acp as a child process → communicates via JSON-RPC on stdio
2. Sends prompts via structured JSON-RPC requests with timeout and cancellation support
3. Receives structured ACP events — text deltas, tool calls, approvals, usage updates
4. Maps ACP events into normalized Aegis domain events for replay and fanout
5. Fans out events to Telegram, Slack, Email, webhooks, and SSE streams
6. Stores session state, events, and actions locally (file-backed by default)

graph LR
    OC["OpenClaw"] --> API["Aegis :9100"]
    CI["CI/CD"]     --> API
    TG["Telegram"]  --> API
    WH["Webhooks"]  --> API
    MCP["MCP"]      --> API
    API --> CC["Claude Code
(ACP)"]
    API --> SSE["SSE Events"]
    API --> WS["WebSocket"]
    API --> PG["SessionStore
(Postgres)"]
Copy

MCP Server

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

# Start standalone
ag mcp

# Add to Claude Code
claude mcp add --scope user aegis -- ag mcp
Copy

Or via .mcp.json:

{
  "mcpServers": {
    "aegis": {
      "command": "ag",
      "args": ["mcp"]
    }
  }
}
Copy

Without a global install, use "command": "npx" with ["--package=@onestepat4time/aegis", "ag", "mcp"] instead.

34 tools — create_session, send_message, get_transcript, approve_permission, acp_send_prompt, acp_respond_approval, batch_create_sessions, create_pipeline, state_set, and more.

3 resources — aegis://sessions, aegis://sessions/{id}/transcript, 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.

• CLI Reference — ag command-line tool (alias: aegis)
• Notification Channels — Telegram, Slack, Email, Webhooks
• 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.

Dashboard features:

• Dark/light theme with system preference detection
• Full accessibility pass — ARIA landmarks, labels, skip-to-content, 24 a11y tests
• Internationalization scaffolding with language switcher (Italian catalog shipped)
• Keyboard shortcuts for fast navigation (?, Ctrl+K, G+O/S/P/A/U)
• Session search, filter by date range, CSV export
• Metric cards with sparkline mini-charts
• Consistent empty states across all pages
• Routines page with calendar-style view for scheduled tasks (Phase 1 — UI scaffold)
• Toast notifications for user feedback

ag                                 # visit http://localhost:9100/dashboard/
Copy

Use Cases & Deployment Tiers

Aegis serves three deployment scenarios:

Tier 1 — Local Orchestration

Single developer. Run Claude Code tasks in the background, monitor via dashboard, approve via Telegram.

ag
# Dashboard: http://localhost:9100/dashboard/
# Telegram approvals while AFK
Copy

Tier 2 — CI/CD & Team Automation

Development teams. Policy-based permission control, batch operations, Slack notifications.

# Blueprint: PR Reviewer
curl -X POST http://localhost:9100/v1/pipelines \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"pr-reviewer","stages":[...],"permissionMode":"plan"}'
Copy

Tier 3 — Zero-Trust Enterprise

Banks, SaaS, regulated industries. Docker-isolated containers, no network egress, audit-first.

• Each task runs in an ephemeral Docker container
• No cross-container networking
• Immutable audit log for compliance
• See Enterprise Deployment for production hardening guide

Golden rule: Intelligence stays outside Aegis. Aegis is a stupid-but-powerful middleware — flows, security, audit. OpenClaw (or any external orchestrator) provides the brains.

Security

Aegis is built with production security as a first-class concern — not an afterthought.

Authentication & Authorization

• Bearer token auth — AEGIS_AUTH_TOKEN protects all endpoints except /v1/health
• SSE token separation — dedicated sse_-prefixed tokens for event streams (regular API keys are rejected on SSE routes)
• API key management — CRUD with role-based access (admin, operator, viewer, custom)
• Hook secret authentication — X-Hook-Secret header with header-only enforcement mode

Audit & Compliance

• Immutable audit trail — hash-chained event log for every session action
• Permission policies — configurable approval/rejection per tool, per session
• Per-IP rate limiting — auth failure limits, connection limits, request throttling

Observability

• OpenTelemetry tracing — distributed spans for HTTP, session lifecycle, tool invocations, and channel delivery
• Prometheus metrics — standard exposition format for session counts, tool usage, latency histograms
• SSE real-time events — live session state, permission requests, tool calls

Network Security

• Default localhost binding — 127.0.0.1 unless explicitly configured
• Docker auto-detection — binds 0.0.0.0 in containers, 127.0.0.1 everywhere else
• No telemetry home — Aegis never phones home or sends data to external services
• Self-hosted only — your data stays on your infrastructure

Safety Mechanisms

• Circuit breaker — detects rapid hook failure loops and trips breaker to prevent session death
• Payload validation — strict Zod schema validation on all inbound hooks
• Payload truncation protection — warns when hook payloads approach Claude Code's 2KB truncation limit
• WebSocket auth — session existence is not revealed before authentication

For the full security questionnaire (pre-filled for vendor assessments), see Security Questionnaire. For deployment hardening, see Enterprise Deployment.

Configuration

Priority: CLI --config > ./.aegis/config.yaml > ./aegis.config.json > ~/.aegis/config.yaml > ~/.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 (`ag`; alias: `aegis`)
├── services/acp/          # ACP runtime (child process, JSON-RPC, events)
├── server.ts             # Fastify HTTP server + routes
├── session.ts            # Session lifecycle
├── monitor.ts            # State monitoring + events
├── 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
│   ├── slack.ts          # Slack incoming webhook channel
│   ├── email.ts          # SMTP email alert channel
│   └── webhook.ts        # Webhook channel
└── __tests__/            # Vitest tests
Copy

Client SDKs

TypeScript

Official @onestepat4time/aegis-client package — generated from the OpenAPI 3.1 specification.

npm install @onestepat4time/aegis-client
Copy

import { AegisClient } from '@onestepat4time/aegis-client';

const client = new AegisClient('http://localhost:9100', process.env.AEGIS_AUTH_TOKEN);

// List sessions
const sessions = await client.listSessions();

// Create a session
const { id } = await client.createSession({ workDir: '/path/to/project' });

// Send a message
await client.sendMessage(id, 'Hello, Claude!');

// Approve a permission
await client.approvePermission(id);
Copy

What's included:

• Generated from OpenAPI spec — all 53 REST endpoints with full TypeScript types
• Backward-compatible class API + function-based API for new code
• Sessions, health, metrics, pipelines, templates, memory, audit log
• Works in Node.js and browser (fetch-based, zero external HTTP deps)

See packages/client/ for the full SDK source.

Python Client SDK

Official ag-client package generated from the OpenAPI contract — 53 methods, Pydantic v2 models, stdlib HTTP.

pip install ag-client
Copy

from aegis_python_client import AegisClient

client = AegisClient(base_url="http://localhost:9100", auth_token="your-token")

# List sessions
sessions = client.list_sessions()

# Create a session
session = client.create_session(work_dir="/path/to/project", prompt="Hello!")

# Send a message
client.send_message(session.id, "Fix the tests")

# Approve a permission
client.approve_permission(session.id)
Copy

What's included:

• 53 methods covering all REST endpoints
• Pydantic v2 models for request/response types
• Uses Python stdlib http.client — zero runtime dependencies
• Type-safe with full IDE autocompletion

See packages/python-client/ for the full SDK source.

Documentation

• Getting Started — Zero to first session in 5 minutes
• Why Aegis? — How Aegis differs from dev tools and multi-agent frameworks
• Roadmap — Phase 3 (Team & Early-Enterprise) is now active
• External Deployment Guide — Step-by-step for external teams
• API Reference — Complete REST API documentation
• ACP Major Cutover Release Plan — Phase 3.5 breaking-release governance
• MCP Tools — 34 MCP tools and 3 prompts
• Advanced Features — Pipelines, Memory Bridge, templates
• Enterprise Deployment — Auth, rate limiting, security, production
• Enterprise Technical Review — Deep architecture, security, observability, and roadmap analysis
• Architecture — Module overview and design
• ACP Migration Guide — Upgrading from aegis-bridge
• Notifications — Telegram, Slack, Email, webhooks
• Deployment Guide — Secure access away from localhost
• Remote Access — External access configuration
• BYO LLM — OpenAI-compatible provider setup (GLM, OpenRouter, LM Studio, Ollama)
• Troubleshooting — Common issues and fixes
• Known Issues — Active bugs with workarounds
• Release Process — Maintainer runbook for production releases
• Disaster Recovery — Data loss and infrastructure failure recovery
• Incident and Rollback Runbook — Deployment rollbacks and version pinning
• TypeDoc API — Auto-generated TypeScript reference

Support the Project

License

MIT — Emanuele Santonastaso