Architecture

How the Atom agent program fits together, module by module. Names below come from the project structure; one-liners state each module's documented role. For behavior details, follow the guide links.

Interface

• src/cli.tsx - entry: --help prints usage and exits, everything else starts the TUI.
• src/App.tsx - Ink TUI: transcript, pickers, modes, approvals, status line.

The loop

• src/zen.ts - provider dispatch plus the agentic loop: streaming SSE, retries, tool rounds.
• src/system.ts - base system prompt assembled with the repo overlay.
• src/context-manager.ts - the single place answering how much context is available, used, and what gets sent.
• src/context-windows.ts - curated per-model verified windows driving the footer percent and compact threshold.
• src/compact.ts - compaction mechanics: trigger math, head and tail split, summary request with tools off.

Providers

• src/providers.ts - 7-provider registry: endpoint, key env vars, defaults, fallback model lists.
• src/adapters.ts - Anthropic and Gemini translation plus SSE parsing, models-list parsing, key validation.
• src/auth.ts - ~/.atom/auth.json store with env-first resolution.
• src/prompt-cache.ts - cache-friendly prefix assembly per provider.

Tools and control

• src/tools.ts - 13 local executors plus function schemas; the TOOL_DEFINITIONS table is the source of truth.
• src/permissions.ts - pure allow and deny matcher behind /allow, /deny, /rules.
• src/skills.ts - skill discovery registry plus auto-match scoring.
• src/snapshots.ts - pre-mutation file snapshots behind /rewind.
• src/session.ts - atomic save, resume, clear semantics.
• src/env-block.ts - per-turn environment block kept out of the cached prefix.

Read next

• Agent loop for runtime behavior of the loop row above.
• Development for scripts, verification standard, and the agent workflow in this repo.
• Providers for the caching design inside the providers row.