How the pieces of 8gent Code fit together on main today. Only what is wired and running.

8gent Code is a Bun monorepo: apps/ for things you run, packages/ for the parts they share. This page covers the path a request takes and the packages on it.

The path of a request

You type in the workspace                     apps/tui
  -> the tab's agent loop                     packages/eight/agent.ts
       -> model call                          packages/providers  ->  packages/local-model-server
       -> tool call                           packages/ai/tools.ts, packages/eight/tools.ts
            -> hooks (hooks.yaml PreToolUse)  packages/hooks
            -> shell commands only:
                 deny patterns                packages/permissions
                 injection check              packages/permissions/shell-sanitizer.ts
                 System One                   packages/permissions/system-one-gate.ts -> packages/decide
                 approval card                apps/tui (InlineApprovalPrompt)
  <- reply streams back into the chat

The packages on that path

Package	What it does
`apps/tui`	The workspace: Ink (React for the terminal). Tabs, keys, cards, the DJ deck, the living 8
`packages/eight`	The agent loop: turns, tool dispatch, abort, checkpoints, sessions, the system prompt
`packages/eight/tool-registry.ts`	Deferred tools: core tools load first, other categories on `discover_tools`
`packages/ai`	Tool definitions (`agentTools`), the text tool protocol for local models, vision routing
`packages/providers`	The provider registry, `~/.8gent/providers.json`, failover chains, keys
`packages/local-model-server`	One interface over local engines. Ollama and llama-server adapters pass the same contract tests
`packages/permissions`	Permission modes per tab, allow and deny patterns, the approval channel, the System One gate
`packages/decide`	System One: rules, the read-only allowlist, and the judge backends (in-process llama.cpp, Ollama)
`packages/memory`	Local memory: SQLite with full-text search, optional embeddings
`packages/goal`	The `/goal` loop: budgets, the judge, the signed ledger
`packages/orchestration`	Sub-agents and the build pipeline roles
`packages/hooks`	`hooks.json` and `hooks.yaml`
`packages/mcp`	MCP client (`~/.8gent/mcp.json`) and `8gent mcp-server`
`packages/hands`, `packages/eyes`, `packages/handeyes`	Computer use on macOS: act, perceive, and both together
`packages/music`	The DJ: playback, radio, key estimate, producer
`packages/settings`	`~/.8gent/settings.json` schema and defaults
`packages/daemon`	The background daemon (`8gent daemon`): a pool of up to 10 agent sessions and the goal RPC

Design choices that shape everything

Local by default. Providers that need a key are off until you add one. Nothing leaves the machine unless you pick a hosted model.
Per-tab state. Each chat tab holds its own agent, model and permission mode. A tool call carries its tab's mode, so one tab in Infinite never makes another tab's call infinite.
Stop, never allow. System One can block a command or put it to you. It cannot wave a command past your rules or the card.
One judge per machine. The System One judge is served once by the local Ollama for every process, with an in-process fallback.
Small prompt. Tools load by category when needed, not all at once.

For contributors, the repository's own docs/ and packages/*/README.md go deeper. See Contributing.

Architecture

The path of a request

The packages on that path

Design choices that shape everything

On this page