📘 ANCIENT — Software Documentation

AI Coding Agent | Terminal UI | Bun/TypeScript/React Monorepo

1. Executive Overview

ANCIENT is a self-hosted AI coding agent designed to replace per-seat subscription costs for AI coding assistants. It consists of a terminal-based UI (packages/cli), an API server (packages/server), a shared type/schema library (packages/shared), and a Prisma-based database layer (packages/database).

Core Philosophy: Instead of paying per seat for hosted AI tools, ANCIENT runs locally (or self-hosted) using free/open-weight models (e.g., mistralai/devstral-2512:free via OpenRouter) with an agentic loop, built-in tools, MCP support, subagents, and session persistence.

2. Repository Structure

ancient/
├── .env.example              # Environment variable template
├── .gitignore                # Root ignore rules
├── README.md                 # Project overview and architecture target
├── bun.lock                  # Bun lockfile (monorepo dependency graph)
├── docker-compose.yml        # Infrastructure orchestration (Postgres + App)
├── package.json              # Root workspace configuration
├── tsconfig.base.json        # Shared TypeScript compiler options
└── packages/
    ├── cli/                  # Terminal UI (Bun, TypeScript, React, Ink)
    ├── database/             # Prisma ORM, schema, migrations, seed
    ├── server/               # FastAPI-style HTTP API (Bun/Hono)
    └── shared/               # Cross-package types, Zod schemas, constants

3. Package-Level Documentation

3.1 packages/cli — Terminal UI Application

Role: The primary user interface. A terminal application built with React and Ink (React for terminals) that provides screens, layouts, dialogs, theming, and keyboard shortcuts.

Key Technologies: Bun, TypeScript, React, Ink, OpenTUI

Entry Point: src/index.tsx → renders the root layout and mounts the Ink app.

Binary: bin/ANCIENT — executable shell script that invokes the CLI.

File Inventory & Logic

3.2 packages/server — API & Agent Runtime

Role: HTTP API server that handles authentication, chat streaming (SSE), session CRUD, provider connections, and tool execution. Serves as the bridge between the CLI UI and the LLM/agent logic.

Key Technologies: Bun, Hono (or similar lightweight HTTP framework), Zod, AI SDK (Vercel)

Entry Point: src/index.ts — starts the HTTP server and mounts route handlers.

File Inventory & Logic

3.3 packages/database — Data Persistence Layer

Role: Prisma ORM setup, database schema, migrations, and seed data. Shared across CLI (for local caching) and Server (for primary persistence).

Key Technologies: Prisma, PostgreSQL, TypeScript

File Inventory & Logic

3.4 packages/shared — Cross-Cutting Types & Schemas

Role: Prevents circular dependencies between cli and server by housing shared Zod schemas, TypeScript types, and provider constants.

Key Technologies: TypeScript, Zod

File Inventory & Logic

4. Connection & Dependency Graphs (Mermaid)

4.1 Monorepo Workspace Dependency Graph

graph TD
    subgraph Root["📁 Root Workspace"]
        R_PKG[package.json<br/> workspaces: packages/]
        R_TS[tsconfig.base.json]
        R_DOCK[docker-compose.yml]
        R_ENV[.env.example]
    end

    subgraph Shared["📦 @ANCIENT/shared"]
        S_IDX[src/index.ts]
        S_SCH[src/schemas.ts]
        S_MOD[src/models.ts]
        S_PRO[src/providers.ts]
    end

    subgraph DB["📦 @ANCIENT/database"]
        D_IDX[src/index.ts]
        D_CLI[src/client.ts]
        D_ENU[src/enums.ts]
        D_PRI[prisma/schema.prisma]
        D_MIG1[migrations/...initial]
        D_MIG2[migrations/...provider]
        D_MIG3[migrations/...status]
        D_SEED[seed.ts]
    end

    subgraph Server["📦 @ANCIENT/server"]
        SRV_IDX[src/index.ts]
        SRV_CHAT[src/routes/chat.ts]
        SRV_AUTH[src/routes/auth.ts]
        SRV_SESS[src/routes/sessions.ts]
        SRV_PROV[src/routes/provider-connections.ts]
        SRV_TOOL[src/tools/index.ts]
        SRV_MID1[src/middleware/require-auth.ts]
        SRV_MID2[src/middleware/byok-rate-limit.ts]
    end

    subgraph CLI["📦 @ANCIENT/cli"]
        CLI_IDX[src/index.tsx]
        CLI_ROOT[src/layouts/root-layout.tsx]
        CLI_HOME[src/screens/home.tsx]
        CLI_SES[src/screens/session.tsx]
        CLI_HK[src/hooks/use-chat.ts]
        CLI_API[src/lib/api-client.ts]
        CLI_OA[src/lib/oauth.ts]
    end

    CLI -->|imports types/schemas| Shared
    CLI -->|imports PrismaClient| DB
    Server -->|imports types/schemas| Shared
    Server -->|imports PrismaClient| DB
    DB -->|references| Shared
    Root -->|orchestrates| CLI
    Root -->|orchestrates| Server
    Root -->|orchestrates| DB

4.2 CLI Internal Component & Provider Network

graph TD
    subgraph Entry["CLI Entry"]
        BIN[bin/ANCIENT]
        IDX[src/index.tsx]
    end

    subgraph Providers["React Context Providers"]
        P_THEME[theme/index.tsx]
        P_DLG[dialog/index.tsx]
        P_TOAST[toast/index.tsx]
        P_KBD[Keyboard-layer/index.tsx]
        P_PROMPT[prompt-config/index.tsx]
    end

    subgraph Layouts["Layouts"]
        L_ROOT[root-layout.tsx]
        L_THEMED[themed-root.tsx]
    end

    subgraph Screens["Screens"]
        SCR_HOME[home.tsx]
        SCR_NEW[new-session.tsx]
        SCR_SES[session.tsx]
    end

    subgraph SessionUI["Session UI Components"]
        C_HEADER[header.tsx]
        C_INPUT[input-bar.tsx]
        C_STATUS[status-bar.tsx]
        C_SHELL[session-shell.tsx]
        C_MSG_IDX[messages/index.tsx]
        C_MSG_U[user-message.tsx]
        C_MSG_B[bot-message.tsx]
        C_MSG_E[error-message.tsx]
    end

    subgraph Dialogs["Dialog System"]
        D_IDX[dialogs/index.tsx]
        D_AGT[agents-dialog.tsx]
        D_MOD[models-dialog.tsx]
        D_SES[sessions-dialog.tsx]
        D_THM[theme-dialog.tsx]
        D_SL[dialog-search-list.tsx]
    end

    subgraph CommandMenu["Command Palette"]
        CM_IDX[command-menu/index.tsx]
        CM_CMD[commands.tsx]
        CM_FL[filter-commands.ts]
        CM_HK[use-command-menu.ts]
    end

    subgraph Lib["Client Libraries"]
        LIB_API[api-client.ts]
        LIB_AUTH[auth.ts]
        LIB_OA[oauth.ts]
    end

    BIN --> IDX
    IDX --> L_THEMED
    L_THEMED --> P_THEME
    L_THEMED --> P_DLG
    L_THEMED --> P_TOAST
    L_THEMED --> P_KBD
    L_THEMED --> P_PROMPT
    L_THEMED --> L_ROOT

    L_ROOT --> SCR_HOME
    L_ROOT --> SCR_NEW
    L_ROOT --> SCR_SES

    SCR_SES --> C_SHELL
    C_SHELL --> C_HEADER
    C_SHELL --> C_MSG_IDX
    C_SHELL --> C_INPUT
    C_SHELL --> C_STATUS

    C_MSG_IDX --> C_MSG_U
    C_MSG_IDX --> C_MSG_B
    C_MSG_IDX --> C_MSG_E

    SCR_SES -->|uses| LIB_API
    SCR_HOME -->|uses| LIB_API
    LIB_API -->|auth headers| LIB_AUTH
    LIB_AUTH -->|token| LIB_OA

    P_KBD -->|triggers| CM_IDX
    CM_IDX --> CM_CMD
    CM_IDX --> CM_FL
    CM_IDX --> CM_HK
    CM_IDX -->|opens| D_IDX

    D_IDX --> D_AGT
    D_IDX --> D_MOD
    D_IDX --> D_SES
    D_IDX --> D_THM
    D_MOD --> D_SL
    D_SES --> D_SL

    P_DLG -->|controls| D_IDX
    P_THEME -->|styles| C_SHELL
    P_TOAST -->|notifies| SCR_SES

4.3 Server API & Agent Runtime Network

graph TD
    subgraph ServerEntry["Server Entry"]
        SRV[src/index.ts]
    end

    subgraph Middleware["Middleware Stack"]
        M_AUTH[require-auth.ts]
        M_RL[byok-rate-limit.ts]
    end

    subgraph Routes["Route Handlers"]
        R_CHAT[chat.ts]
        R_AUTH[auth.ts]
        R_SESS[sessions.ts]
        R_PROV[provider-connections.ts]
    end

    subgraph AgentCore["Agent Core"]
        SYS[system-prompt.ts]
        TOOLS[tools/index.ts]
    end

    subgraph ToolSet["Built-in Tools"]
        T_READ[read-file.ts]
        T_WRITE[write-file.ts]
        T_EDIT[edit-file.ts]
        T_LS[list-directory.ts]
        T_GLOB[glob.ts]
        T_GREP[grep.ts]
        T_BASH[bash.ts]
    end

    subgraph Safety["Safety Layer"]
        SAFE_DANG[dangerous-commands.ts]
        SAFE_FS[fs-safety.ts]
        SAFE_URL[safe-url.ts]
    end

    subgraph Lib["Server Libraries"]
        L_AUTH[lib/auth.ts]
        L_CR[connection-crypto.ts]
        L_MOD[models.ts]
        L_VAL[provider-connection-validation.ts]
    end

    SRV --> M_AUTH
    SRV --> M_RL
    SRV --> R_CHAT
    SRV --> R_AUTH
    SRV --> R_SESS
    SRV --> R_PROV

    R_CHAT -->|protected by| M_AUTH
    R_SESS -->|protected by| M_AUTH
    R_PROV -->|protected by| M_AUTH
    R_PROV -->|rate limited by| M_RL

    R_CHAT --> SYS
    R_CHAT --> TOOLS
    R_CHAT --> L_MOD

    TOOLS --> T_READ
    TOOLS --> T_WRITE
    TOOLS --> T_EDIT
    TOOLS --> T_LS
    TOOLS --> T_GLOB
    TOOLS --> T_GREP
    TOOLS --> T_BASH

    T_BASH --> SAFE_DANG
    T_READ --> SAFE_FS
    T_WRITE --> SAFE_FS
    T_EDIT --> SAFE_FS
    T_LS --> SAFE_FS

    R_PROV --> L_CR
    R_PROV --> L_VAL
    R_AUTH --> L_AUTH

    R_CHAT -->|streams to| CLI_SESSION
    CLI_SESSION[CLI use-chat.ts]

4.4 Database Schema & Migration Flow

graph LR
    subgraph SchemaDef["Schema Definition"]
        PRISMA[prisma/schema.prisma]
    end

    subgraph Migrations["Migration History"]
        M1[20260802140000_initial_schema]
        M2[20260802150000_add_provider_connections]
        M3[20260802160000_add_provider_connection_status]
    end

    subgraph Runtime["Runtime Access"]
        CLIENT[src/client.ts]
        ENUMS[src/enums.ts]
        IDX[src/index.ts]
    end

    subgraph Consumers["Consumers"]
        SRV[Server Routes]
        CLI[CLI Local Cache]
    end

    PRISMA -->|generates| CLIENT
    PRISMA -->|generates| ENUMS

    M1 -->|applied before| M2
    M2 -->|applied before| M3
    M3 -->|matches| PRISMA

    CLIENT -->|exported via| IDX
    ENUMS -->|exported via| IDX

    IDX -->|imported by| SRV
    IDX -->|imported by| CLI

4.5 Data Flow — Chat Session Lifecycle

sequenceDiagram
    participant User
    participant CLI as CLI (Ink UI)
    participant Hook as use-chat.ts
    participant API as api-client.ts
    participant SRV as server/chat.ts
    participant LLM as AI SDK / LLM
    participant DB as database (Prisma)

    User->>CLI: Type message + Enter
    CLI->>Hook: submit(message)
    Hook->>API: POST /chat (SSE)
    API->>SRV: fetch with auth token
    SRV->>DB: Load session history
    SRV->>LLM: streamText({ messages, tools })
    
    loop Agentic Loop
        LLM-->>SRV: Tool call request (e.g., readFile)
        SRV->>SRV: tools/index.ts routes call
        SRV->>SRV: fs-safety.ts validates path
        SRV->>SRV: read-file.ts reads disk
        SRV-->>LLM: Tool result appended
        LLM-->>SRV: Next token / final response
    end

    SRV-->>API: SSE stream (chunks)
    API-->>Hook: onChunk callback
    Hook-->>CLI: Append to message state
    CLI-->>User: Render bot-message.tsx

    SRV->>DB: Save assistant message + tool calls
    SRV->>DB: Update session checkpoint

4.6 Authentication & Provider Connection Flow

graph TD
    subgraph User["User Terminal"]
        U_CLI[CLI Ink App]
        U_OA[lib/oauth.ts]
        U_API[lib/api-client.ts]
    end

    subgraph ServerAuth["Server Auth"]
        S_OAUTH[routes/auth.ts]
        S_JWT[lib/auth.ts]
        S_MID[middleware/require-auth.ts]
    end

    subgraph ProviderKeys["Provider API Keys"]
        R_PROV[routes/provider-connections.ts]
        R_CRYPTO[lib/connection-crypto.ts]
        R_VAL[lib/provider-connection-validation.ts]
        DB_PROV[(ProviderConnection<br/>Table)]
    end

    U_CLI -->|1. Init login| U_OA
    U_OA -->|2. Open browser| OAuthProvider[GitHub/Google OAuth]
    OAuthProvider -->|3. Callback + code| S_OAUTH
    S_OAUTH -->|4. Issue| S_JWT
    S_JWT -->|5. Return token| U_OA
    U_OA -->|6. Store ~/.ancient/| U_API

    U_CLI -->|7. Add API key| U_API
    U_API -->|8. POST /provider-connections| R_PROV
    R_PROV -->|9. Encrypt| R_CRYPTO
    R_PROV -->|10. Validate| R_VAL
    R_PROV -->|11. Save| DB_PROV

    U_API -->|12. Authenticated request| S_MID
    S_MID -->|13. Verify JWT| S_JWT
    S_MID -->|14. Allow| R_PROV
    R_PROV -->|15. Decrypt key| R_CRYPTO
    R_PROV -->|16. Proxy to LLM| LLMProvider[OpenAI/Anthropic/etc]

5. Reference Lines for Software Documentation

This documentation follows these software documentation standards:

1. IEEE 830 (Software Requirements Specifications) — Functional decomposition by package and component.
2. ISO/IEC/IEEE 42010 (Architecture Description) — Multiple architectural viewpoints (logical, process, development).
3. C4 Model (Simon Brown) — Level 2 (Container) and Level 3 (Component) diagrams rendered in Mermaid.
4. Diátaxis Framework — Separation into reference (file inventory), explanation (logic), and how-to (flow diagrams).

6. Key Architectural Decisions

7. Environment & Deployment

Local Development:

bun install          # Installs all workspace packages
bun run dev:server   # Hot-reloads server
bun run dev:cli      # Hot-reloads CLI

Docker (from docker-compose.yml):

• PostgreSQL container for persistence
• Server container exposing HTTP API
• CLI runs natively or inside a container with TTY access

Required Environment Variables (from .env.example):

• DATABASE_URL — PostgreSQL connection string
• JWT_SECRET — Signing key for auth tokens
• ENCRYPTION_KEY — Master key for connection-crypto.ts
• OPENROUTER_API_KEY — Default provider key (optional if using BYOK)

8. Status & Migration Notes

As noted in the README, this is a rebuild of HaMan with the terminal UI already live and the agent core being merged in. The architecture target shows a planned packages/agent directory that does not yet exist in the current tree. The current agent loop lives inside packages/server/src/routes/chat.ts and packages/server/src/tools/ as an interim consolidation step.