Antec PRD

Project Goal

The goal of this project is to create a repository with requirements for a Personal Agent system. Based on this documentation, users will be able to use Claude Code, OpenAI Codex, or similar AI coding assistants to implement the final system from scratch.

Every document in this repository is written to be 100% reproducible – containing exact data structures, algorithms, SQL schemas, API contracts, and configuration formats needed to rebuild the system without access to the original source code.

---

What is Antec

Antec is a self-hosted personal AI assistant delivered as a single Rust binary with zero mandatory external dependencies. All data stays local on the user’s machine.

Key characteristics:

• Single binary – no Docker, no cloud, no external databases. Download, run, pair, chat.
• Async Rust – built on Tokio with the Axum web framework for HTTP, WebSocket, and SSE.
• SQLite storage – all persistent state lives in a single SQLite database with WAL mode, FTS5 full-text search, and 21 versioned migrations.
• Vanilla web console – HTML + CSS + JS (ES modules) embedded in the binary via rust-embed. No frontend framework, no build step for the UI.
• Multi-channel – a unified agent core serves Discord, WhatsApp, iMessage, and the built-in web console through swappable channel adapters.
• Multi-provider LLM – supports Anthropic, OpenAI, Google, Ollama, and OpenRouter with automatic failover and cost-aware routing.
• Extensible – 50+ built-in tools, a skill system with Python/Node/WASM runtimes, MCP client integration, and a hands/extensions marketplace.
• Secure by default – 9 security layers including injection detection, secret vault, WASM sandbox with fuel metering, rate limiting, audit chain, and command blocklist.
• Bilingual – compile-time i18n with full EN and PL locale support.

---

System Architecture Overview

graph TB
    subgraph USER["User Interfaces"]
        CONSOLE["Web Console(16-CONSOLE)"]
        DISCORD["Discord"]
        WHATSAPP["WhatsApp"]
        IMESSAGE["iMessage"]
    end

    subgraph GATEWAY_LAYER["API & Communication Layer"]
        GW["HTTP Gateway(03-GATEWAY)REST + WebSocket + SSE"]
        CH["Channel Adapters(08-CHANNELS)Unified messaging"]
    end

    subgraph AI_ENGINE["AI Engine"]
        CORE["Agent Core(02-CORE)Agent loop, LLM routing,context management"]
        AGENTS["Multi-Agent System(12-AGENTS)12 specialists,parallel execution"]
        PERSONA["Persona & i18n(13-PERSONA)Personality, behaviors,EN/PL"]
    end

    subgraph CAPABILITIES["Capabilities Layer"]
        TOOLS["Tool Registry(04-TOOLS)43+ tools, risk tiers"]
        SKILLS["Skills Platform(09-SKILLS)66 builtin, 5 runtimes"]
        MCP["MCP Client(11-MCP)stdio/SSE/HTTP"]
        EXT["Extensions(17-EXTENSIONS)25 integrations"]
        SCHED["Scheduler(10-SCHEDULER)Cron, reminders"]
        WS["Workspace(15-WORKSPACE)File jail, REPL"]
    end

    subgraph DATA_LAYER["Data & Intelligence Layer"]
        MEM["Memory System(05-MEMORY)BM25 + TF-IDF +embeddings, RRF"]
        STORE["SQLite Storage(06-STORAGE)20 tables, FTS5,WAL mode"]
    end

    subgraph OPERATIONS["Operations & Security"]
        SEC["Security(07-SECURITY)9 layers, injectiondetection, vault"]
        STATS["Statistics(18-STATISTICS)Cost tracking, metrics,health probes"]
        CONFIG["Configuration(14-CONFIGURATION)TOML, hot reload,CLI, wizard"]
    end

    CONSOLE -->|WebSocket| GW
    DISCORD -->|REST| CH
    WHATSAPP -->|Bridge| CH
    IMESSAGE -->|AppleScript| CH
    CH --> GW
    GW --> CORE
    CORE --> AGENTS
    CORE --> PERSONA
    CORE --> TOOLS
    CORE --> MEM
    TOOLS --> SKILLS
    TOOLS --> MCP
    MCP --> EXT
    CORE --> SCHED
    TOOLS --> WS
    MEM --> STORE
    SEC -.->|protects| GW
    SEC -.->|protects| CORE
    SEC -.->|protects| TOOLS
    STATS -.->|monitors| CORE
    STATS -.->|monitors| TOOLS
    STATS -.->|monitors| STORE
    CONFIG -.->|configures| CORE
    CONFIG -.->|configures| GW
    CONFIG -.->|configures| CH

---

Data Flow: Message Lifecycle

sequenceDiagram
    participant U as User
    participant GW as Gateway
    participant SEC as Security
    participant CORE as Agent Core
    participant LLM as LLM Provider
    participant TOOLS as Tool Registry
    participant MEM as Memory
    participant DB as SQLite

    U->>GW: Send message (WebSocket/REST)
    GW->>SEC: Validate auth + rate limit
    SEC-->>GW: Approved
    GW->>CORE: Route to agent
    CORE->>MEM: Recall relevant memories
    MEM->>DB: FTS5 + TF-IDF query
    DB-->>MEM: Memory results
    MEM-->>CORE: Context enrichment
    CORE->>CORE: Assemble prompt (persona + context + memories + message)
    CORE->>CORE: Select model (heuristic routing)
    CORE->>LLM: Stream request
    LLM-->>CORE: Token stream

    opt Tool Call
        CORE->>SEC: Check tool risk level
        SEC-->>CORE: Safe / Needs approval
        CORE->>TOOLS: Execute tool
        TOOLS-->>CORE: Tool result
        CORE->>LLM: Continue with tool result
        LLM-->>CORE: Token stream
    end

    CORE->>MEM: Auto-extract memories
    CORE->>DB: Record usage metrics
    CORE-->>GW: Stream response tokens
    GW-->>U: Real-time response

---

Document Index

System Foundation

AI Engine

Communication

Capabilities

Intelligence

Operations & Security

User Interface & CLI

Deep Dives

Deployment

---

Crate Map

antec (workspace root)
 +-- src/main.rs                    # Binary entrypoint, CLI, boot sequence
 +-- crates/
      +-- antec-core/               # Agent loop, LLM providers, routing, metrics
      +-- antec-gateway/            # Axum HTTP/WS server, REST routes, auth
      +-- antec-channels/           # Discord, WhatsApp, iMessage, Console adapters
      +-- antec-tools/              # Tool registry, 43+ implementations, MCP bridge
      +-- antec-memory/             # Memory CRUD, FTS5, TF-IDF, embeddings, recall
      +-- antec-storage/            # SQLite pool, migrations, repository traits
      +-- antec-security/           # Injection detection, vault, rate limiting, audit
      +-- antec-skills/             # Skill loader, manifest, hub, 5 runtimes
      +-- antec-scheduler/          # Cron, reminders, heartbeat, poll loop
      +-- antec-sandbox/            # WASM + OS sandbox, capabilities, policy engine
      +-- antec-mcp/                # MCP client (stdio, SSE, HTTP transports)
      +-- antec-extensions/         # Integration templates, credential vault, health
      +-- antec-i18n/               # Translation macro, EN/PL locale TOML files
      +-- antec-console/            # Web console SPA (embedded static assets)
      +-- antec-hands/              # Operational capability definitions

---

Tech Stack Summary

---

Key Design Principles

---

Development Standards & AI-Assisted Coding

This project is designed for autonomous agentic coding – AI coding assistants build the system from the PRD documents with minimal human intervention. Three files govern how agents work:

Agent Instruction Files

CLAUDE.md is the primary instruction file. Claude Code reads it automatically at session start. It defines mandatory build checks, architecture constraints, coding standards, workflow orchestration (plan mode, subagents, verification loops), and session continuity via HANDOVER protocol.

AGENTS.md contains the same project context and coding standards in a framework-agnostic format that any AI coding tool can consume.

.claude/skills/rust/SKILL.md (mirrored to .agents/skills/rust/ for Codex) is the comprehensive Rust coding standard with 179 rules organized by priority (CRITICAL / HIGH / MEDIUM / LOW) across ownership, error handling, async patterns, API design, performance, testing, and more. All agents reference this file for Rust-specific decisions.

Channel Integration (Skill + Agent)

Implementing 9 messaging channels is a major effort. We use a Skill + Agent pattern – domain knowledge in a reusable skill, autonomous execution in a dedicated agent:

Why Skill + Agent together (not one or the other):

• Skill alone provides knowledge but runs in the main context – no isolation, can’t parallelize, clutters the conversation with implementation details
• Agent alone can execute in isolation but has no domain knowledge – it would need to research each platform API from scratch every time
• Skill + Agent = the agent spawns with full platform knowledge preloaded, works autonomously in isolated context, and can be launched in parallel for multiple channels simultaneously

Supported channels:

Usage – implement a single channel:

Use the channel-implementer agent to implement the Discord adapter

Usage – implement multiple channels in parallel:

Use the channel-implementer agent to implement Discord, Telegram, and Slack adapters in parallel

Language-agnostic design: The skill’s patterns (trait interface, normalized messages, connection patterns, security rules) apply to any language. The agent’s system prompt includes Rust-specific patterns but the skill itself works for Python, TypeScript, Go, etc. To adapt for another language, create a variant agent with language-specific instructions that still preloads the same channel-integration skill.

OpenAI Codex Configuration

Skills and agents are mirrored to Codex’s directory format for full compatibility:

.agents/                              # Codex skills (agent skills standard)
  skills/
    rust/
      SKILL.md                        # Same 179-rule Rust standard
      agents/openai.yaml              # Codex UI metadata + invocation policy
    channel-integration/
      SKILL.md                        # Same channel adapter pattern
      agents/openai.yaml
      references/                     # Same 9 per-platform API specs

.codex/                               # Codex config + agent roles
  config.toml                         # Multi-agent enabled, role registration
  agents/
    channel-implementer.toml          # Agent role config (model, instructions)

Codex multi-agent is enabled with channel-implementer registered as an agent role using gpt-5.3-codex with model_reasoning_effort = "high". Both skills use allow_implicit_invocation: true so Codex activates them automatically when the task matches.

LSP Integration (rust-analyzer)

We use Language Server Protocol via the rust-analyzer-lsp plugin to give AI agents real-time code intelligence during development.

Why LSP matters for agentic coding:

• Instant error detection – after every file edit, the language server analyzes changes and reports type errors, missing imports, and lifetime issues immediately. The agent catches and fixes mistakes in the same turn instead of discovering them during a full cargo build
• Precise navigation – go-to-definition, find-references, hover-for-types, and call hierarchy give the agent exact knowledge of the codebase structure. This is significantly more accurate than grep-based search, especially in a 15-crate workspace where the same name might appear in different contexts
• Reduced iteration cycles – without LSP, the agent writes code, runs the compiler, reads errors, and fixes them. With LSP, the agent sees diagnostics inline and resolves issues before compilation. On a project of Antec’s size, this eliminates entire rounds of build-fix-rebuild
• Cross-crate awareness – rust-analyzer understands the full workspace dependency graph. When the agent modifies a trait in antec-core, it immediately sees which implementations in antec-channels or antec-tools need updating

Setup:

# Install rust-analyzer (if not already present)
rustup component add rust-analyzer

# Install the Claude Code LSP plugin
/plugin install rust-analyzer-lsp@claude-plugins-official

Context7 MCP – Live Documentation

We use Context7 as an MCP (Model Context Protocol) server to provide AI agents with up-to-date library documentation during development.

Why Context7 matters:

• No stale knowledge – AI models have training cutoffs. Tokio 1.x, Axum 0.7, wasmtime 27, and rusqlite 0.32 may have API changes the model doesn’t know about. Context7 fetches current documentation on demand so the agent never guesses at function signatures or deprecated patterns
• Verified API usage – instead of hallucinating plausible-looking API calls, the agent queries the actual docs for tokio-rs/tokio, tokio-rs/axum, rusqlite/rusqlite, bytecodealliance/wasmtime, and rust-lang/reference before writing code. This eliminates a class of bugs that only surface at compile time
• Dependency evaluation – when considering a new crate, the agent can check its current API surface, version compatibility, and feature flags rather than relying on potentially outdated training data
• Language reference – complex Rust semantics (lifetime elision rules, trait object safety, async trait bounds) are verified against the official Rust reference rather than recalled from memory

Configuration (.claude/settings.json):

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

Key libraries to query:

Rust Coding Standard

The full coding standard lives in .claude/skills/rust/SKILL.md. It defines 179 rules across 14 prioritized categories:

---

How to Use This Documentation

1. Start with 01-ARCHITECTURE.md – understand the crate layout and system boundaries
2. Read 02-CORE.md – learn the agent loop, the central processing pipeline
3. Read 06-STORAGE.md – understand the database schema that underpins everything
4. Pick modules by need – each document is self-contained with all structs, traits, SQL, and API routes needed to implement that module
5. Use the Mermaid diagrams – every document includes flow diagrams that show how components interact
6. Reference 14-CONFIGURATION.md – the full TOML schema ties all modules together

Each document follows a consistent structure:

• Module Goal – one-sentence purpose
• Why This Module Exists – problem it solves and approach
• Business Benefits – concrete value table
• Technical sections – data models, traits, algorithms, API routes, Mermaid diagrams

---

License

License MIT