ANCIENT Logo [![Version](https://img.shields.io/badge/version-3.1.0-8A2BE2?style=flat-square)](https://github.com/D-engahmed/ancient/releases) [![License](https://img.shields.io/badge/license-Proprietary-ff6b6b?style=flat-square)](LICENSE) [![Bun](https://img.shields.io/badge/built%20with-Bun-f9f1a5?style=flat-square&logo=bun)](https://bun.sh) [![TypeScript](https://img.shields.io/badge/TypeScript-5.4-3178c6?style=flat-square&logo=typescript)](https://www.typescriptlang.org) [![React](https://img.shields.io/badge/React-Ink-61dafb?style=flat-square&logo=react)](https://github.com/vadimdemedes/ink) **[Quick Start](#-quick-start)** ยท **[Features](#-what-makes-ancient-different)** ยท **[Agent System](#-the-sub-agent-system)** ยท **[Architecture](#-architecture)** ยท **[Roadmap](#-roadmap)**
--- ## ๐Ÿš€ What is ANCIENT? **ANCIENT** is a self-hosted, terminal-native AI coding agent that replaces per-seat subscription costs with full control over your AI workforce. Unlike Claude Code, Cursor, or GitHub Copilot โ€” ANCIENT lets you **design custom agent teams**, **assign different LLM models to each agent**, and **orchestrate them through 6 coordination protocols** โ€” all from your terminal. > **Honesty note:** the multi-agent surface below is the *documented intent*. The **as-built** > reality (what currently runs, what is un-wired, and the state/persistence limits) is recorded > in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) and the assumption register > [`docs/architecture/ASSUMPTIONS.md`](docs/architecture/ASSUMPTIONS.md). Trust those over this > README for engineering decisions. Built for teams who refuse to pay $20โ€“$40/month per developer for black-box AI tools. ```bash # One command. Your entire AI team ready. $ ancient init $ ancient team use elite-squad $ ancient "Build a React dashboard with real-time WebSocket charts" ๐Ÿค– Coordinator (gpt-4o) โ†’ Planning task decomposition... ๐Ÿค– Architect (claude-sonnet) โ†’ Designing system structure... ๐Ÿค– Coder A (claude-sonnet) โ†’ Writing implementation... ๐Ÿค– Coder B (gpt-4o) โ†’ Writing alternative implementation... ๐Ÿค– Judge (gpt-4o) โ†’ Evaluating solutions... โœ… Best solution selected. Files written. Tests passing. ``` --- ## โœจ What Makes ANCIENT Different? | Feature | Claude Code | Cursor | Copilot | **ANCIENT** | |---------|-------------|--------|---------|-------------| | **Self-Hosted** | โŒ | โŒ | โŒ | โœ… **Full control** | | **Per-Seat Cost** | $20/mo | $20/mo | $19/mo | โœ… **Free / BYOK** | | **Multi-Agent Teams** | โŒ | โŒ | โŒ | โœ… **Design your squad** | | **Per-Agent Model Routing** | โŒ | โŒ | โŒ | โœ… **gpt-4o + Claude + Local** | | **Coordination Protocols** | โŒ | โŒ | โŒ | โœ… **6 patterns** | | **Terminal-Native** | โœ… | โŒ | โŒ | โœ… **Ink + React** | | **Model Fallback Chains** | โŒ | โŒ | โŒ | โœ… **Auto-recovery** | | **Checkpoint & Rewind** | โœ… | โŒ | โŒ | โœ… **Git-backed** | | **MCP Support** | โœ… | โŒ | โŒ | โœ… **Extensible** | | **Proprietary License** | N/A | N/A | N/A | โœ… **Commercial ready** | --- ## ๐Ÿง  The Sub-Agent System ANCIENT 3.0 introduces a **multi-agent orchestration framework** built into an AI coding assistant. Design teams, assign roles, pick models, and watch them collaborate. > See `docs/ARCHITECTURE.md` ยง2 for what of this is actually wired today (and ยง5 for the > "complexity must be earned" strategy ladder that governs whether a team protocol is used for a > given task). ### 6 Coordination Protocols ```mermaid flowchart TB subgraph HIERARCHICAL["๐Ÿข HIERARCHICAL"] direction TB H1[๐Ÿ‘‘ Coordinator
gpt-4o] --> H2[๐Ÿ—๏ธ Architect
Claude] H1 --> H3[๐Ÿ’ป Coder
Claude] H1 --> H4[๐Ÿ” Reviewer
GPT-4o-mini] end subgraph PIPELINE["๐Ÿ”„ PIPELINE"] direction LR P1[Plan] --> P2[Design] --> P3[Code] --> P4[Review] --> P5[Test] end subgraph SWARM["๐Ÿ SWARM"] direction TB S1[Coder A] --> Judge S2[Coder B] --> Judge S3[Coder C] --> Judge Judge[โš–๏ธ Judge] --> Result[โœ… Best Solution] end subgraph CONSENSUS["๐Ÿ—ณ๏ธ CONSENSUS"] direction TB C1[Reviewer 1] --> Vote C2[Reviewer 2] --> Vote C3[Reviewer 3] --> Vote C4[Reviewer 4] --> Vote C5[Reviewer 5] --> Vote Vote{Majority
Threshold} --> Approved[โœ… Approved] end subgraph DEBATE["โš”๏ธ DEBATE"] direction TB D1[Architect A] <--> Moderator D2[Architect B] <--> Moderator Moderator[๐ŸŽฏ Moderator] --> Synthesis[๐Ÿ“„ Synthesis] end subgraph ROUNDROBIN["๐Ÿ” ROUND-ROBIN"] direction TB R1[Turn 1: Coder] --> R2[Turn 2: Reviewer] --> R3[Turn 3: Optimizer] end ``` ### 12 Built-In Agent Roles Every role comes with **pre-configured system prompts**, **capability flags**, **tool access**, and **preferred model lists**. | Role | Purpose | Default Model | |------|---------|---------------| | ๐Ÿ‘‘ **Coordinator** | Delegates, plans, synthesizes | `gpt-4o` | | ๐Ÿ“‹ **Planner** | Breaks tasks into milestones | `claude-3.5-sonnet` | | ๐Ÿ—๏ธ **Architect** | Designs system structure | `claude-3.5-sonnet` | | ๐Ÿ’ป **Coder** | Writes implementation | `claude-3.5-sonnet` | | ๐Ÿ” **Reviewer** | Quality gate, finds bugs | `gpt-4o-mini` | | ๐Ÿงช **Tester** | Writes tests, verifies coverage | `gpt-4o-mini` | | ๐Ÿ› **Debugger** | Root-cause analysis | `claude-3.5-sonnet` | | ๐Ÿ“š **Researcher** | Gathers docs, evaluates approaches | `gpt-4o` | | ๐Ÿ“ **Documenter** | READMEs, API docs, ADRs | `claude-3.5-sonnet` | | ๐ŸŽฏ **Specialist** | Domain expert (customizable) | `claude-3.5-sonnet` | | โšก **Executor** | Runs shell commands safely | `gpt-4o-mini` / Free | | โœ… **Validator** | Final approval gate | `gpt-4o` | ### Per-Agent Model Routing Assign **different models and providers** to every agent. Fallback chains auto-recover on failure. ```typescript const team = TeamBuilder.create("EliteSquad") .withCoordinator("boss", { model: "gpt-4o", provider: "openai", fallbackModels: [{ model: "claude-3.5-sonnet", provider: "anthropic" }] }) .addAgent("senior-dev", { role: "coder", model: "claude-3.5-sonnet", provider: "anthropic", reportsTo: "boss" }) .addAgent("cost-cutter", { role: "reviewer", model: "mistralai/devstral-2512:free", provider: "openrouter", // FREE TIER reportsTo: "boss" }) .useProtocol("hierarchical", { maxDepth: 3 }) .build(); ``` --- ## ๐Ÿ— Architecture ```mermaid flowchart TB subgraph Terminal["๐Ÿ’ป TERMINAL (Ink UI)"] direction LR Chat["๐Ÿ’ฌ Chat Screen"] Menu["๐Ÿ“‹ Command Menu"] Viewer["๐ŸŒณ Agent Hierarchy Viewer"] end subgraph Agent["@ANCIENT/agent"] direction TB Arena["๐ŸŽฏ Arena
Coordinator
6 protocols"] Team["๐Ÿ‘ฅ Team
Builder
12 roles"] Runtime["โš™๏ธ Runtime
Executor โ†’ Scheduler
StateManager โ†’ Context"] Tasks["๐Ÿ“‹ Tasks
Decomposer
Assigner
Tracker"] Backends["๐Ÿ”Œ Backends
Router
Factory
Registry"] end subgraph Server["@ANCIENT/server (Hono)"] direction LR Auth["๐Ÿ” /auth
OAuth/JWT"] ChatAPI["๐Ÿ’ฌ /chat
SSE Stream"] AgentAPI["๐Ÿค– /agent/*
REST API"] end subgraph Database["@ANCIENT/database (Prisma)"] direction LR Users["๐Ÿ‘ค Users"] Sessions["๐Ÿ“… Sessions"] Messages["๐Ÿ’ฌ Messages"] TeamsDB["๐Ÿ‘ฅ Teams"] AgentsDB["๐Ÿค– Agents"] Executions["โšก Executions"] Checkpoints["๐Ÿ“ธ Checkpoints"] Providers["๐Ÿ”‘ ProviderConnections"] end Terminal --> Agent Agent --> Server Server --> Database style Terminal fill:#1a1a2e,stroke:#8A2BE2,color:#fff style Agent fill:#0f3460,stroke:#7FC4BE,color:#fff style Server fill:#16213e,stroke:#ff6b6b,color:#fff style Database fill:#0a1931,stroke:#f9f1a5,color:#fff ``` ### Monorepo Structure ```mermaid graph TD Root["ancient/"] --> Packages["packages/"] Root --> DockerCompose["docker-compose.yml"] Root --> EnvExample[".env.example"] Root --> License["LICENSE"] Packages --> CLI["cli/
Terminal UI
React + Ink"] Packages --> Agent["agent/
Multi-agent system"] Packages --> Server["server/
Hono HTTP API"] Packages --> Database["database/
Prisma + PostgreSQL"] Packages --> Shared["shared/
Zod schemas + types"] Agent --> Arena["src/arena/
6 coordination protocols"] Agent --> Team["src/team/
12 roles + templates"] Agent --> Tasks["src/tasks/
Decomposer, assigner, tracker"] Agent --> Runtime["src/runtime/
Execution engine"] Agent --> Backends["src/backends/
Model router"] style Root fill:#8A2BE2,stroke:#fff,color:#fff style Packages fill:#7FC4BE,stroke:#fff,color:#000 style Agent fill:#ff6b6b,stroke:#fff,color:#fff ``` --- ## โšก Quick Start ### Prerequisites - [Bun](https://bun.sh) 1.3.5 (the version used by CI and release builds) - [Docker](https://docker.com) (for PostgreSQL) - API keys for at least one provider (OpenAI, Anthropic, OpenRouter, or local Ollama) ### 1. Clone & Install ```bash git clone https://github.com/D-engahmed/ancient.git cd ancient bun install ``` ### 2. Configure Environment ```bash cp .env.example .env # Edit .env with your API keys ``` ```env DATABASE_URL="postgresql://ancient:ancient@localhost:5432/ancient?schema=public" JWT_SECRET="your-super-secret-jwt-key" ENCRYPTION_KEY="your-32-byte-encryption-key" OPENROUTER_API_KEY="sk-or-v1-..." # Optional โ€” supports BYOK per user ``` ### 3. Start Infrastructure ```bash docker compose up -d # PostgreSQL bun run db:generate bun run db:migrate # Run Prisma migrations bun run db:seed # Seed default data ``` ### 4. Run in Terminal Mode (Claude Code Style) ```bash bun run dev:cli # Terminal UI with local agent execution ``` ### 5. Or Start the Full Stack ```bash bun run dev:server # API server bun run dev:cli # Terminal UI (in another terminal) ``` --- ## ๐ŸŽฎ Usage ### Terminal Commands ```bash # Start a new session with default team $ ancient # Use a built-in template $ ancient team use swarm-coding $ ancient "Implement a red-black tree in TypeScript" # Create custom team interactively $ ancient team new ? Team name: MySquad ? Protocol: hierarchical / pipeline / swarm / consensus / debate / round-robin ? Add agent: coder (claude-3.5-sonnet) ? Add agent: reviewer (gpt-4o-mini) โœ… Team "MySquad" created with 3 agents # View agent hierarchy $ ancient agents ๐Ÿ“Š MySquad (hierarchical) โ”œโ”€โ”€ ๐Ÿค– boss (coordinator) โ€” gpt-4o โ”œโ”€โ”€ ๐Ÿง‘โ€๐Ÿ’ป coder (coder) โ€” claude-3.5-sonnet โ””โ”€โ”€ ๐Ÿ” reviewer (reviewer) โ€” gpt-4o-mini # Execute with specific team $ ancient --team MySquad "Refactor auth module to use JWT" ``` ### Programmatic API ```typescript import { ExecutionEngine, TeamBuilder } from "@ANCIENT/agent"; const engine = new ExecutionEngine(); const team = TeamBuilder.create("DebugSquad") .withCoordinator("commander", { model: "gpt-4o", provider: "openai" }) .addAgent("debugger", { role: "debugger", model: "claude-3.5-sonnet", provider: "anthropic", reportsTo: "commander" }) .addAgent("tester", { role: "tester", model: "gpt-4o-mini", provider: "openai", reportsTo: "commander" }) .useProtocol("hierarchical") .build(); const result = await engine.execute(team, "Fix the memory leak in the WebSocket handler"); console.log(result.output); ``` --- ## ๐Ÿ”ง Configuration ### Agent Teams (`~/.ancient/teams/`) Teams are stored as JSON files in your home directory for instant loading: ```json { "id": "elite-squad", "name": "Elite Squad", "protocol": { "type": "hierarchical", "maxDepth": 3 }, "agents": [ { "name": "boss", "role": "coordinator", "backend": { "provider": "openai", "model": "gpt-4o" } } ] } ``` ### Provider Connections ANCIENT supports **Bring-Your-Own-Key** (BYOK) per user. Each team member can use their own API keys, encrypted at rest with AES-256-GCM. | Provider | Models Supported | |----------|-----------------| | **OpenAI** | GPT-4o, GPT-4o-mini, o1 | | **Anthropic** | Claude 3.5 Sonnet, Claude 3 Opus | | **OpenRouter** | 100+ models, including free tiers | | **Google** | Gemini Pro | | **Ollama** | Local models โ€” Llama 3, Mistral, CodeLlama | | **Local** | Any OpenAI-compatible endpoint | --- ## ๐Ÿ›ก Safety & Guardrails ANCIENT is built for production teams: - ๐Ÿ”’ **Encrypted API Keys** โ€” AES-256-GCM at rest - ๐Ÿ›ก **Filesystem Sandboxing** โ€” Agents cannot escape the project directory - โš ๏ธ **Dangerous Command Blocklist** โ€” `rm -rf /`, `mkfs`, `dd` require explicit approval - ๐Ÿ“‹ **Checkpoint System** โ€” Shadow-git snapshots before every BUILD turn. `/rewind` restores files + history - ๐Ÿง  **Smart Model Routing** โ€” Free models for simple queries, premium models for complex reasoning - ๐Ÿ“Š **Cost Tracking** โ€” Per-execution cost breakdown across all agents --- ## ๐Ÿ“ˆ Roadmap ```mermaid gantt title ANCIENT Development Roadmap dateFormat YYYY-MM section Completed v1.0 Terminal UI :done, 2024-01, 2024-06 v2.0 Skills & MCP :done, 2024-07, 2025-03 v3.0 Multi-agent System :done, 2025-04, 2026-08 section In Progress v3.1 VS Code Extension :done, 2026-08, 2026-09 v3.2 Web Dashboard :2026-09, 2027-02 section Planned v4.0 Self-improving Agents :2027-03, 2027-09 v4.0 Agent Marketplace :2027-06, 2027-12 ``` | Phase | Feature | Status | |-------|---------|--------| | โœ… v1.0 | Terminal UI + basic chat | Released | | โœ… v2.0 | Skills, subagents, MCP, checkpoints | Released | | โœ… v3.0 | **Multi-agent system** (Arena, Team, Tasks, Runtime, Backends) | **Current** | | โœ… v3.1 | VS Code Extension | Released in the current 3.1 release line | | ๐Ÿ“‹ v3.2 | Web Dashboard for team management | Planned | | ๐Ÿ“‹ v4.0 | Self-improving agents (meta-learning) | Planned | | ๐Ÿ“‹ v4.0 | Agent marketplace (shareable team templates) | Planned | --- ## ๐Ÿค Contributing ANCIENT is **proprietary software** (not open source). We welcome: - ๐Ÿ› **Bug reports** via GitHub Issues - ๐Ÿ’ก **Feature requests** via GitHub Discussions - ๐Ÿข **Enterprise partnerships** โ€” contact us for custom deployments For commercial licensing, multi-tenant SaaS deployment, or white-label solutions, please reach out. --- ## ๐Ÿ“„ License **Proprietary License** โ€” All rights reserved. This software is provided under a commercial license. See [LICENSE](LICENSE) for full terms. | Permission | Status | |------------|--------| | โœ… **Self-host** for your organization | Allowed | | โœ… **Modify** for internal use | Allowed | | โŒ **Redistribute** without authorization | Prohibited | | โŒ **Use** in competing products | Prohibited | For licensing inquiries: [Contact Us](mailto:contact@ancient.dev) ---
**Built with ๐Ÿ’œ by the ANCIENT Team** [โญ Star us on GitHub](https://github.com/D-engahmed/ancient) ยท [๐Ÿ› Report Bug](https://github.com/D-engahmed/ancient/issues) ยท [๐Ÿ’ก Request Feature](https://github.com/D-engahmed/ancient/discussions)