{"id":47630551,"url":"https://github.com/onestepat4time/aegis","last_synced_at":"2026-05-03T08:12:17.125Z","repository":{"id":346057414,"uuid":"1188370331","full_name":"OneStepAt4time/aegis","owner":"OneStepAt4time","description":"🛡️ Orchestrate Claude Code sessions via API. Create, brief, monitor, refine, ship. The bridge between your orchestrator and your coding agent.","archived":false,"fork":false,"pushed_at":"2026-04-28T00:58:49.000Z","size":6812,"stargazers_count":8,"open_issues_count":26,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T01:20:11.034Z","etag":null,"topics":["ai-agent","alpha","automation","claude-code","cli","coding-agent","developer-tools","early-access","multi-agent","orchestration","session-management","tmux","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OneStepAt4time.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"OneStepAt4time","ko_fi":"onestepat4time"}},"created_at":"2026-03-22T01:23:21.000Z","updated_at":"2026-04-27T20:28:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/OneStepAt4time/aegis","commit_stats":null,"previous_names":["onestepat4time/aegis"],"tags_count":107,"template":false,"template_full_name":null,"purl":"pkg:github/OneStepAt4time/aegis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneStepAt4time%2Faegis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneStepAt4time%2Faegis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneStepAt4time%2Faegis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneStepAt4time%2Faegis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OneStepAt4time","download_url":"https://codeload.github.com/OneStepAt4time/aegis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneStepAt4time%2Faegis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32562145,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","alpha","automation","claude-code","cli","coding-agent","developer-tools","early-access","multi-agent","orchestration","session-management","tmux","typescript"],"created_at":"2026-04-01T23:22:51.341Z","updated_at":"2026-05-03T08:12:17.117Z","avatar_url":"https://github.com/OneStepAt4time.png","language":"TypeScript","funding_links":["https://github.com/sponsors/OneStepAt4time","https://ko-fi.com/onestepat4time"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/aegis-banner.jpg\" alt=\"Aegis\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/v/@onestepat4time/aegis.svg\" alt=\"npm\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/OneStepAt4time/aegis/ci.yml?branch=main\" alt=\"CI\" /\u003e\n  \u003cimg src=\"https://img.shields.io/npm/l/@onestepat4time/aegis.svg\" alt=\"license\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-%3E%3D20.0.0-blue.svg\" alt=\"node\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MCP-ready-green.svg\" alt=\"MCP ready\" /\u003e\n  \u003ca href=\"https://github.com/OneStepAt4time/aegis/blob/main/ROADMAP.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/roadmap-preview-blue\" alt=\"Roadmap\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e ⚠️ **Aegis is in Preview.** APIs may change. See [ROADMAP.md](./ROADMAP.md) for the path to stable.\n\u003e Current release channel is `preview`.\n\u003e\n\u003e **Phase 3 (Team \u0026 Early-Enterprise) is now active.** Phase 2 is complete. See the [roadmap](./ROADMAP.md) for what's next.\n\u003e\n\u003e 📦 **Package renamed:** `aegis-bridge` → [`@onestepat4time/aegis`](https://www.npmjs.com/package/@onestepat4time/aegis). See [Migration Guide](docs/migration-guide.md) if you're upgrading.\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eOrchestrate Claude Code sessions via REST API, MCP, CLI, webhooks, or Telegram.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/aegis-architecture-hero.jpg\" alt=\"Message Claude. Ship Code. — Aegis x Claude Code\" width=\"800\"\u003e\n\u003c/p\u003e\n\n---\n\n## Quick Start\n\n```bash\n# Install, bootstrap, and start\nnpm install -g @onestepat4time/aegis\nag init\nag\n\n# Scaffold a repo-local starter\nag init --list-templates\nag init --from-template code-reviewer\nag doctor\n\n# Create a session\nag create \"Build a login page with email/password fields.\" --cwd /path/to/project\n```\n\n\u003e **CLI naming:** the primary command is `ag` (e.g. `ag`, `ag mcp`, `ag create \"brief\"`). The legacy name `aegis` is preserved as an alias, so any existing scripts using `aegis` keep working.\n\nBuilt-in starter templates include `code-reviewer`, `ci-runner`, `pr-reviewer`, and `docs-writer`.\n\n\u003e **Prerequisites:** [tmux](https://github.com/tmux/tmux) and [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code).\n\n### Windows Setup\n\nOn Windows, use psmux as the tmux-compatible backend before starting Aegis.\n\n```powershell\nchoco install psmux -y\nnpm install -g @onestepat4time/aegis\nag\n```\n\nFor full setup, verification, and troubleshooting, see [Windows Setup](docs/windows-setup.md).\n\nFor a full walkthrough from install to first session, see [Getting Started](docs/getting-started.md). For advanced features (pipelines, Memory Bridge, templates), see [Advanced Features](docs/advanced.md). For OpenAI-compatible provider setup (GLM, OpenRouter, LM Studio, Ollama, Azure OpenAI), see [BYO LLM](docs/byo-llm.md). For deployment and secure access away from localhost, see [Deployment Guide](docs/deployment.md) and [Remote Access](docs/remote-access.md). For the full MCP tools reference, see [MCP Tools](docs/mcp-tools.md).\n\n---\n\n## How It Works\n\nAegis wraps Claude Code in tmux sessions and exposes everything through a unified API. No SDK dependency, no browser automation — just tmux + JSONL transcript parsing.\n\n1. Creates a tmux window → launches Claude Code inside it\n2. Sends messages via `tmux send-keys` with delivery verification (up to 3 retries)\n3. Parses output from both terminal capture and JSONL transcripts\n4. Detects state changes via **VT100 screen buffer analysis** — clean, reliable idle detection\n5. Streams terminal output in real-time via **WebSocket PTY streaming** (`tmux pipe-pane`)\n6. Fans out events to Telegram, Slack, Email, webhooks, and SSE streams\n7. Stores session state in a pluggable **SessionStore** (in-memory default, PostgreSQL available)\n\n```mermaid\ngraph LR\n    OC[\"OpenClaw\"] --\u003e API[\"Aegis :9100\"]\n    CI[\"CI/CD\"]     --\u003e API\n    TG[\"Telegram\"]  --\u003e API\n    WH[\"Webhooks\"]  --\u003e API\n    MCP[\"MCP\"]      --\u003e API\n    API --\u003e CC[\"Claude Code\u003cbr/\u003e(tmux)\"]\n    API --\u003e SSE[\"SSE Events\"]\n    API --\u003e WS[\"WebSocket PTY\"]\n    API --\u003e PG[\"SessionStore\u003cbr/\u003e(Postgres)\"]\n```\n\n---\n\n## MCP Server\n\nConnect any MCP-compatible agent to Claude Code — the fastest way to build multi-agent workflows.\n\n```bash\n# Start standalone\nag mcp\n\n# Add to Claude Code\nclaude mcp add --scope user aegis -- ag mcp\n```\n\nOr via `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"aegis\": {\n      \"command\": \"ag\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nWithout a global install, use `\"command\": \"npx\"` with `[\"--package=@onestepat4time/aegis\", \"ag\", \"mcp\"]` instead.\n\n**24 tools** — `create_session`, `send_message`, `get_transcript`, `approve_permission`, `batch_create_sessions`, `create_pipeline`, `state_set`, and more.\n\n**4 resources** — `aegis://sessions`, `aegis://sessions/{id}/transcript`, `aegis://sessions/{id}/pane`, `aegis://health`\n\n**3 prompts** — `implement_issue`, `review_pr`, `debug_session`\n\n## Ecosystem Integrations\n\nAegis works beyond Claude Code anywhere an MCP host can launch a local stdio server.\n\n- [CLI Reference](docs/integrations/cli.md) — `ag` command-line tool (alias: `aegis`)\n- [Notification Channels](docs/integrations/notifications.md) — Telegram, Slack, Email, Webhooks\n- [Cursor integration](docs/integrations/cursor.md)\n- [Windsurf integration](docs/integrations/windsurf.md)\n- [MCP Registry preparation](docs/integrations/mcp-registry.md)\n\n---\n\n## REST API\n\nAll endpoints under `/v1/`.\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/v1/health` | Server health \u0026 uptime |\n| `POST` | `/v1/sessions` | Create (or reuse) a session |\n| `GET` | `/v1/sessions` | List sessions |\n| `GET` | `/v1/sessions/:id` | Session details |\n| `GET` | `/v1/sessions/:id/read` | Parsed transcript |\n| `GET` | `/v1/sessions/:id/events` | SSE event stream |\n| `POST` | `/v1/sessions/:id/send` | Send a message |\n| `POST` | `/v1/sessions/:id/approve` | Approve permission |\n| `POST` | `/v1/sessions/:id/reject` | Reject permission |\n| `POST` | `/v1/sessions/:id/interrupt` | Ctrl+C |\n| `POST` | `/v1/sessions/:id/discover-commands` | Discover available slash commands |\n| `DELETE` | `/v1/sessions/:id` | Kill session |\n| `POST` | `/v1/sessions/batch` | Batch create |\n| `POST` | `/v1/handshake` | Capability negotiation |\n| `POST` | `/v1/pipelines` | Create pipeline |\n| `POST` | `/v1/memory` | Set memory entry |\n| `GET` | `/v1/memory` | List memory entries |\n| `GET` | `/v1/memory/:key` | Get memory entry |\n| `DELETE` | `/v1/memory/:key` | Delete memory entry |\n| `POST` | `/v1/templates` | Create session template |\n| `GET` | `/v1/templates` | List templates |\n| `GET` | `/v1/templates/:id` | Get template |\n| `PUT` | `/v1/templates/:id` | Update template |\n| `DELETE` | `/v1/templates/:id` | Delete template |\n| `POST` | `/v1/dev/route-task` | Route task to model tier |\n| `GET` | `/v1/dev/model-tiers` | List model tiers |\n| `GET` | `/v1/diagnostics` | Server diagnostics |\n\n\u003cdetails\u003e\n\u003csummary\u003eFull API Reference\u003c/summary\u003e\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/v1/sessions/:id/pane` | Raw terminal capture |\n| `GET` | `/v1/sessions/:id/health` | Health check with actionable hints |\n| `GET` | `/v1/sessions/:id/summary` | Condensed transcript summary |\n| `GET` | `/v1/sessions/:id/transcript/cursor` | Cursor-based transcript replay |\n| `POST` | `/v1/sessions/:id/screenshot` | Screenshot a URL (Playwright) |\n| `POST` | `/v1/sessions/:id/escape` | Send Escape |\n| `GET` | `/v1/pipelines` | List all pipelines |\n| `GET` | `/v1/pipelines/:id` | Get pipeline status |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eSession States\u003c/summary\u003e\n\n| State | Meaning | Action |\n|-------|---------|--------|\n| `working` | Actively generating | Wait or poll `/read` |\n| `idle` | Waiting for input | Send via `/send` |\n| `permission_prompt` | Awaiting approval | `/approve` or `/reject` |\n| `asking` | Claude asked a question | Read `/read`, respond `/send` |\n| `stalled` | No output for \u003e5 min | Nudge `/send` or `DELETE` |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eSession Reuse\u003c/summary\u003e\n\nWhen 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.\n\n**Response differences:**\n\n| | New Session | Reused Session |\n|---|---|---|\n| Status | `201 Created` | `200 OK` |\n| `reused` | `false` | `true` |\n| `promptDelivery` | `{ delivered, attempts }` | `{ delivered, attempts }` |\n\n```bash\n# First call → creates session (201)\ncurl -s -o /dev/null -w \"%{http_code}\" -X POST http://localhost:9100/v1/sessions \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"workDir\": \"/home/user/project\", \"prompt\": \"Fix the tests\"}'\n# → 201\n\n# Same workDir while idle → reuses session (200)\ncurl -s -o /dev/null -w \"%{http_code}\" -X POST http://localhost:9100/v1/sessions \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"workDir\": \"/home/user/project\", \"prompt\": \"Now add error handling\"}'\n# → 200, body includes \"reused\": true\n```\n\nOnly **idle** sessions are reused. Working, stalled, or permission-prompt sessions are ignored — a new one is created.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCapability Handshake\u003c/summary\u003e\n\nBefore using advanced integration paths, clients can negotiate capabilities with Aegis via `POST /v1/handshake`. This prevents version-drift breakage.\n\n```bash\ncurl -X POST http://localhost:9100/v1/handshake \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"protocolVersion\": \"1\", \"clientCapabilities\": [\"session.create\", \"session.transcript.cursor\"]}'\n```\n\n**Response** (200 OK when compatible):\n\n```json\n{\n  \"protocolVersion\": \"1\",\n  \"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\"],\n  \"negotiatedCapabilities\": [\"session.create\", \"session.transcript.cursor\"],\n  \"warnings\": [],\n  \"compatible\": true\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `protocolVersion` | Server's protocol version (`\"1\"` currently) |\n| `serverCapabilities` | Full list of server-supported capabilities |\n| `negotiatedCapabilities` | Intersection of client + server capabilities |\n| `warnings` | Non-fatal issues (unknown caps, version skew) |\n| `compatible` | `true` (200) or `false` (409 Conflict) |\n\nReturns **409** if the client's `protocolVersion` is below the server minimum.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCursor-Based Transcript Replay\u003c/summary\u003e\n\nStable 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.\n\n```bash\n# Get the newest 50 messages\ncurl http://localhost:9100/v1/sessions/abc123/transcript/cursor\n\n# Get the next page (pass oldest_id from previous response)\ncurl \"http://localhost:9100/v1/sessions/abc123/transcript/cursor?before_id=16\u0026limit=50\"\n\n# Filter by role\ncurl \"http://localhost:9100/v1/sessions/abc123/transcript/cursor?role=user\"\n```\n\n**Query params:**\n\n| Param | Default | Description |\n|-------|---------|-------------|\n| `before_id` | (none) | Cursor ID to page before. Omit for newest entries. |\n| `limit` | `50` | Entries per page (1–200). |\n| `role` | (none) | Filter: `user`, `assistant`, or `system`. |\n\n**Response:**\n\n```json\n{\n  \"messages\": [...],\n  \"has_more\": true,\n  \"oldest_id\": 16,\n  \"newest_id\": 25\n}\n```\n\nCursor 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.\n\n\u003c/details\u003e\n\n---\n\n### Telegram\n\nBidirectional chat with topic-per-session threading. Send prompts from your phone, get completions pushed back.\n\n```bash\nexport AEGIS_TG_TOKEN=\"your-bot-token\"\nexport AEGIS_TG_GROUP=\"-100xxxxxxxxx\"\n```\n\n### Webhooks\n\nPush events to any endpoint with exponential backoff retry.\n\n```bash\nexport AEGIS_WEBHOOKS=\"https://your-app.com/api/aegis-events\"\n```\n\n### Multi-Agent Orchestration\n\nAI orchestrators delegate coding tasks through Aegis — monitor progress, send refinements, handle errors, all without a human in the loop.\n\nWorks with [OpenClaw](https://openclaw.ai), custom orchestrators, or any agent that can make HTTP calls.\n\n### Web Dashboard\n\nAegis ships with a built-in dashboard at `http://localhost:9100/dashboard/` — real-time session monitoring, activity streams, and health overview.\n\n**Dashboard features:**\n- Dark/light theme with system preference detection\n- Full accessibility pass — ARIA landmarks, labels, skip-to-content, 24 a11y tests\n- Internationalization scaffolding with language switcher (Italian catalog shipped)\n- Keyboard shortcuts for fast navigation (`?`, `Ctrl+K`, `G+O/S/P/A/U`)\n- Session search, filter by date range, CSV export\n- Metric cards with sparkline mini-charts\n- Consistent empty states across all pages\n- Toast notifications for user feedback\n\n```bash\nag                                 # visit http://localhost:9100/dashboard/\n```\n\n---\n\n## Use Cases \u0026 Deployment Tiers\n\nAegis serves three deployment scenarios:\n\n### Tier 1 — Local Orchestration\n**Single developer.** Run Claude Code tasks in the background, monitor via dashboard, approve via Telegram.\n\n```bash\nag\n# Dashboard: http://localhost:9100/dashboard/\n# Telegram approvals while AFK\n```\n\n### Tier 2 — CI/CD \u0026 Team Automation\n**Development teams.** Policy-based permission control, batch operations, Slack notifications.\n\n```bash\n# Blueprint: PR Reviewer\ncurl -X POST http://localhost:9100/v1/pipelines \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -d '{\"name\":\"pr-reviewer\",\"stages\":[...],\"permissionMode\":\"plan\"}'\n```\n\n### Tier 3 — Zero-Trust Enterprise\n**Banks, SaaS, regulated industries.** Docker-isolated containers, no network egress, audit-first.\n\n- Each task runs in an ephemeral Docker container\n- No cross-container networking\n- Immutable audit log for compliance\n- See [Enterprise Deployment](docs/enterprise.md) for production hardening guide\n\n**Golden rule:** Intelligence stays outside Aegis. Aegis is a stupid-but-powerful middleware — flows, security, audit. OpenClaw (or any external orchestrator) provides the brains.\n\n---\n\n## Security\n\nAegis includes built-in security defaults:\n\n- **Permission mode** — `default` requires approval for dangerous operations (shell commands, file writes). Change with `permissionMode` when creating a session.\n- **Hook secrets** — use `X-Hook-Secret` header (preferred). Query-param `secret` remains backward compatible by default but is deprecated.\n- **Auth tokens** — protect the API with `AEGIS_AUTH_TOKEN` (Bearer auth on all endpoints except `/v1/health`).\n- **WebSocket auth** — session existence is not revealed before authentication.\n\n---\n\n## Configuration\n\n**Priority:** CLI `--config` \u003e `./.aegis/config.yaml` \u003e `./aegis.config.json` \u003e `~/.aegis/config.yaml` \u003e `~/.aegis/config.json` \u003e defaults\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AEGIS_BASE_URL` | `http://127.0.0.1:9100` | Preferred API origin for hooks, CLI clients, and dashboard links |\n| `AEGIS_PORT` | 9100 | Server port |\n| `AEGIS_HOST` | 127.0.0.1 | Server host |\n| `AEGIS_AUTH_TOKEN` | — | Bearer token for API auth |\n| `AEGIS_DASHBOARD_ENABLED` | `true` | Serve the bundled dashboard |\n| `AEGIS_PERMISSION_MODE` | default | `default`, `bypassPermissions`, `plan`, `acceptEdits`, `dontAsk`, `auto` |\n| `AEGIS_TMUX_SESSION` | aegis | tmux session name |\n| `AEGIS_TG_TOKEN` | — | Telegram bot token |\n| `AEGIS_TG_GROUP` | — | Telegram group chat ID |\n| `AEGIS_WEBHOOKS` | — | Webhook URLs (comma-separated) |\n| `AEGIS_HOOK_SECRET_HEADER_ONLY` | false | Enforce `X-Hook-Secret` header and reject deprecated `?secret=` transport |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide — issue workflow, labels, commit conventions, and PR requirements.\n\n```bash\ngit clone https://github.com/OneStepAt4time/aegis.git\ncd aegis\nnpm install\nnpm run dev          # build + start\nnpm test             # vitest suite\nnpx tsc --noEmit     # type-check\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eProject Structure\u003c/summary\u003e\n\n```\nsrc/\n├── cli.ts                # CLI entry (`ag`; alias: `aegis`)\n├── server.ts             # Fastify HTTP server + routes\n├── session.ts            # Session lifecycle\n├── tmux.ts               # tmux operations\n├── monitor.ts            # State monitoring + events\n├── terminal-parser.ts    # Terminal state detection\n├── transcript.ts         # JSONL parsing\n├── mcp-server.ts         # MCP server (stdio)\n├── events.ts             # SSE streaming\n├── pipeline.ts           # Batch + pipeline orchestration\n├── channels/\n│   ├── manager.ts        # Event fan-out\n│   ├── telegram.ts       # Telegram channel\n│   ├── slack.ts          # Slack incoming webhook channel\n│   ├── email.ts          # SMTP email alert channel\n│   └── webhook.ts        # Webhook channel\n└── __tests__/            # Vitest tests\n```\n\n\u003c/details\u003e\n\n---\n\n## Client SDKs\n\n### TypeScript\n\nOfficial `@onestepat4time/aegis-client` package — generated from the OpenAPI 3.1 specification.\n\n```bash\nnpm install @onestepat4time/aegis-client\n```\n\n```typescript\nimport { AegisClient } from '@onestepat4time/aegis-client';\n\nconst client = new AegisClient('http://localhost:9100', process.env.AEGIS_AUTH_TOKEN);\n\n// List sessions\nconst sessions = await client.listSessions();\n\n// Create a session\nconst { id } = await client.createSession({ workDir: '/path/to/project' });\n\n// Send a message\nawait client.sendMessage(id, 'Hello, Claude!');\n\n// Approve a permission\nawait client.approvePermission(id);\n```\n\n**What's included:**\n- Generated from OpenAPI spec — all 53 REST endpoints with full TypeScript types\n- Backward-compatible class API + function-based API for new code\n- Sessions, health, metrics, pipelines, templates, memory, audit log\n- Works in Node.js and browser (fetch-based, zero external HTTP deps)\n\nSee [`packages/client/`](packages/client/) for the full SDK source.\n\n## Python Client SDK\n\nOfficial `ag-client` package generated from the OpenAPI contract — 53 methods, Pydantic v2 models, stdlib HTTP.\n\n```bash\npip install ag-client\n```\n\n```python\nfrom aegis_python_client import AegisClient\n\nclient = AegisClient(base_url=\"http://localhost:9100\", auth_token=\"your-token\")\n\n# List sessions\nsessions = client.list_sessions()\n\n# Create a session\nsession = client.create_session(work_dir=\"/path/to/project\", prompt=\"Hello!\")\n\n# Send a message\nclient.send_message(session.id, \"Fix the tests\")\n\n# Approve a permission\nclient.approve_permission(session.id)\n```\n\n**What's included:**\n- 53 methods covering all REST endpoints\n- Pydantic v2 models for request/response types\n- Uses Python stdlib `http.client` — zero runtime dependencies\n- Type-safe with full IDE autocompletion\n\nSee [`packages/python-client/`](packages/python-client/) for the full SDK source.\n\n\n## Documentation\n\n- **[Getting Started](docs/getting-started.md)** — Zero to first session in 5 minutes\n- **[Roadmap](ROADMAP.md)** — Phase 3 (Team \u0026 Early-Enterprise) is now active\n- **[External Deployment Guide](EXTERNAL_DEPLOYMENT_GUIDE.md)** — Step-by-step for external teams\n- **[API Reference](docs/api-reference.md)** — Complete REST API documentation\n- **[MCP Tools](docs/mcp-tools.md)** — 24 MCP tools and 3 prompts\n- **[Advanced Features](docs/advanced.md)** — Pipelines, Memory Bridge, templates\n- **[Enterprise Deployment](docs/enterprise.md)** — Auth, rate limiting, security, production\n- **[Enterprise Technical Review](docs/enterprise/index.md)** — Deep architecture, security, observability, and roadmap analysis\n- **[Architecture](docs/architecture.md)** — Module overview and design\n- **[Migration Guide](docs/migration-guide.md)** — Upgrading from `aegis-bridge`\n- **[Notifications](docs/integrations/notifications.md)** — Telegram, Slack, Email, webhooks\n- **[Deployment Guide](docs/deployment.md)** — Secure access away from localhost\n- **[Remote Access](docs/remote-access.md)** — External access configuration\n- **[BYO LLM](docs/byo-llm.md)** — OpenAI-compatible provider setup (GLM, OpenRouter, LM Studio, Ollama)\n- **[Troubleshooting](docs/troubleshooting.md)** — Common issues and fixes\n- **[Release Process](docs/release-process.md)** — Maintainer runbook for production releases\n- **[Disaster Recovery](docs/DISASTER_RECOVERY.md)** — Data loss and infrastructure failure recovery\n- **[Incident and Rollback Runbook](docs/incident-rollback-runbook.md)** — Deployment rollbacks and version pinning\n- **[TypeDoc API](https://onestepat4time.github.io/aegis/)** — Auto-generated TypeScript reference\n\n---\n\n## Support the Project\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/sponsors/OneStepAt4time\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/GitHub%20Sponsors-%E2%99%A5-ea4aaa.svg\" alt=\"GitHub Sponsors\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://ko-fi.com/onestepat4time\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-ff5e5b.svg\" alt=\"Ko-fi\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## License\n\nMIT — [Emanuele Santonastaso](https://github.com/OneStepAt4time)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonestepat4time%2Faegis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonestepat4time%2Faegis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonestepat4time%2Faegis/lists"}