
[](https://github.com/D-engahmed/ancient/releases)
[](LICENSE)
[](https://bun.sh)
[](https://www.typescriptlang.org)
[](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)