System Flow

8gent processes user intent through a layered pipeline:

User Intent
    |
8gent TUI (Ink/React)
    |-- Animations & Effects
    |-- ADHD Mode
    |-- Ghost Suggestions
    |-- Kanban Board
    |
Proactive Planner (BMAD)
    |
Multi-Agent Orchestration
    |
Toolshed (capability discovery)
    |
+--------------------------------------+
| MCP | LSP | Web | Shell | AST | FS  |
| PDF | Image | Notebook | Background |
+--------------------------------------+
    |
Evidence Collection & Validation
    |
Completion Report + Voice Output

The key design principle is that the agent prompt stays small. Tools and capabilities are discovered through the toolshed at runtime rather than loaded into context upfront.

The project uses a Bun workspace monorepo with two main directories: apps/ for user-facing applications and packages/ for shared libraries. The package set is large and growing; the list below is selective — see the repo for the full inventory.

8gent-code/
|-- apps/
|   |-- tui/             # Terminal UI (Ink v6, React for CLI). Primary surface.
|   |-- 8gent-bot/       # Telegram orchestrator routing messages to officer vessels
|   |-- 8gent-computer/  # Voice-first ambient computer-use agent for macOS (Swift NSPanel)
|   |-- dashboard/       # Next.js admin panel
|   |-- debugger/        # Session debugger (Next.js)
|   |-- lil-eight/       # Lightweight 8gent variant (Swift dock pet)
|   |-- linkedin-vessel/ # LinkedIn outreach vessel with HyperAgent self-improvement
|   |-- convex/          # Convex backend functions
|-- packages/
|   |-- eight/          # Core agent engine, REPL, system prompt
|   |-- providers/      # Adaptive router across 11 wired providers
|   |-- ai/             # Vercel AI SDK integration + tool registry
|   |-- daemon/         # Persistent vessel daemon (Fly.io Amsterdam)
|   |-- orchestration/  # Multi-agent coordination, role registry
|   |-- self-autonomy/  # Reflection, evolution, HyperAgent meta-mutation
|   |-- memory/         # SQLite + FTS5 memory store with embeddings
|   |-- music/          # DJ + MusicProducer (mpv, sox, Replicate)
|   |-- voice/          # Speech-to-Text via Whisper, TTS routing
|   |-- hands/          # Desktop automation tools (cliclick, screencapture)
|   |-- computer/       # CUA-style computer-use bridge
|   |-- ast-index/      # TypeScript AST parsing for token-efficient retrieval
|   |-- mcp/            # MCP client implementation
|   |-- lsp/            # LSP client for code intelligence
|   |-- planning/       # Proactive BMAD planning engine
|   |-- kernel/         # RL fine-tuning pipeline (off by default)
|   |-- quarantine/     # Skill security sandbox
|   |-- toolshed/       # Capability discovery and registry
|   |-- validation/     # Evidence collection
|   |-- reporting/      # Completion reports
|   |-- skills/         # Skill framework + bundled SKILL.md files
|   |-- tools/          # Web, PDF, image, notebook tools
|   |-- settings/       # ~/.8gent/settings.json schema + helpers
|   |-- auth/           # Authentication
|   |-- db/             # Convex reactive database
|   |-- harness-cli/    # Headless CLI for session inspection
|-- benchmarks/
|   |-- autoresearch/   # Karpathy-style iterative improvement loop
|-- config/
|-- docs/
|   |-- specs/          # Daemon Protocol v1.0, etc

Core Packages

packages/eight

The main agent engine. Contains the REPL, agent loop with abort + checkpoint restore, context engineering, and system prompt. Provider clients live in packages/providers/ rather than here so the registry can be swapped without touching the agent.

Key files: agent.ts, prompts/system-prompt.ts, session-sync.ts, tools.ts.

packages/providers

Adaptive router across 11 wired providers: 8gent, ollama, openrouter, groq, grok, openai, anthropic, mistral, together, fireworks, replicate. Apple Foundation, Apfel (localhost:11500), and DeepSeek are available as auto-detected runtime clients but are not part of the core registry. Failover chain: local 8gent → local Qwen → OpenRouter :free. auto:free resolves dynamically to the best currently-available :free model on OpenRouter.

packages/daemon

Persistent vessel runtime hosted on Fly.io Amsterdam at eight-vessel.fly.dev. Speaks the WebSocket Daemon Protocol v1.0 with auth, sessions, streaming. Holds an AgentPool of up to 10 concurrent sessions; sessions carry a channel field (os, app, telegram, discord, api) for third-party terminal hosts.

packages/planning

The proactive BMAD planner. Classifies tasks into categories (Code, Creative, Research, Planning, Communication), generates step-by-step plans, tracks momentum, and predicts upcoming steps.

packages/toolshed

The capability layer inspired by Stripe's agent architecture. Tools register themselves with capabilities and permissions. The agent queries the toolshed by capability (e.g., code.symbol) rather than loading every tool into its prompt.

packages/ast-index

TypeScript AST parsing for symbol-level code retrieval. Instead of reading entire files, the agent fetches specific symbols, significantly reducing token usage per operation.

packages/kernel

The RL fine-tuning pipeline. Four phases: proxy management, judge scoring (Gemini Flash), GRPO training orchestration, and production loop with MadMax scheduling. Off by default.

packages/validation

Evidence collection system. Gathers pass/fail signals after file writes, command executions, and git commits. Feeds into the completion report.

packages/orchestration

Multi-agent coordination. Supports spawning subagents for complex tasks and parallel tool execution.

TUI Architecture

The TUI at apps/tui/ follows a design-system-first approach:

apps/tui/src/
|-- theme/          # Tokens, semantic colors, ThemeProvider
|-- components/
|   |-- primitives/ # AppText, MutedText, Heading, Stack, Card, Badge
|   |-- feedback/   # Alert, SpinnerRow, ProgressBar
|   |-- forms/      # TextField, SelectField
|   |-- data-display/ # Table, KeyValueList
|   |-- navigation/ # Header, Footer
|-- hooks/          # useHotkeys, useViewport, useGhostSuggestion
|-- lib/            # Text utils (truncate, wrap), formatters
|-- screens/        # ChatScreen, OnboardingScreen
|-- app/            # Providers (ThemeProvider + ADHDMode)

Screens compose primitives and widgets. No raw Ink <Text> or <Box> elements appear in screen-level code.

Data Flow

User input enters through the TUI's command input component
Ghost suggestion system checks git state, plan context, and history to offer predictions
Slash commands are intercepted and handled locally (e.g., /kanban, /model)
Chat messages are sent to the agent engine (packages/eight)
The planner classifies the task and generates a BMAD plan
The tool loop executes plan steps, querying the toolshed for needed capabilities
Evidence collector captures verification signals after each tool call
Results stream back to the TUI as messages with typing effects
Kanban board updates automatically as plan steps progress
Completion report summarizes the session with evidence counts