# paoloanzn/free-code architecture

> Architecture diagram of the GitHub repository paoloanzn/free-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/paoloanzn/free-code
- Repository: https://github.com/paoloanzn/free-code

## Overview

1. This repository is a terminal-first AI coding agent CLI. The main runtime is Bun with TypeScript, and the primary user surface is an Ink/React-based TUI rather than a browser or server app.

2. The top-level execution path starts in `src/entrypoints/cli.tsx`, then flows into the REPL screen (`src/screens/REPL.tsx`) and the app shell in `src/components/App.tsx`. That shell coordinates prompt entry, message rendering, dialogs, shortcuts, and background status indicators.

3. The UI layer is built around a custom terminal rendering stack in `src/ink/`, not stock React DOM. That layer handles layout, focus, input events, scrolling, text measurement, and ANSI output, which is why the app can manage complex interactive panes inside a terminal.

4. User input is parsed through the command system and prompt-processing utilities. Slash commands live in `src/commands/`, while raw text, bash-like inputs, and special modes are normalized through `src/utils/processUserInput/` before reaching the main query loop.

5. The core AI orchestration lives in `src/QueryEngine.ts`, with supporting query config, token budgeting, stop hooks, and context analysis under `src/query/` and `src/utils/query*`. This layer is responsible for assembling conversation state, selecting the model/provider, and driving request/response turns.

6. Model access is abstracted behind provider logic in `src/utils/model/` and API clients in `src/services/api/`. The repo supports Anthropic directly plus alternate backends like OpenAI Codex, AWS Bedrock, Google Vertex AI, and Anthropic Foundry, so provider selection is a real architectural boundary, not just a config detail.

7. Tool use is a separate subsystem from the LLM query engine. Tool definitions live in `src/tools/`, orchestration in `src/services/tools/`, and tool registry wiring in `src/tools.ts`; the major tools include bash, file read/write/edit, search, LSP, MCP, agents, tasks, web fetch/search, notebook edits, and remote triggers.

8. Permissioning and safety are handled as a distinct flow around tool execution. The policy and approval logic is spread across `src/utils/permissions/`, `src/hooks/toolPermission/`, and `src/components/permissions/`, with separate UI for bash, filesystem, notebook, web fetch, and sandbox approvals.

9. Persistent app and conversation state is managed centrally in `src/state/`, with session/history helpers in `src/history.ts`, `src/bootstrap/`, `src/utils/session*`, and memory files under `src/memdir/`. This is where the app reconstructs prior sessions, resumes tasks, and tracks user/project memory.

10. The repo has several integration subsystems that connect the CLI to the outside world: MCP in `src/services/mcp/`, IDE bridge/remote control in `src/bridge/` and `src/remote/`, plugins in `src/plugins/` and `src/utils/plugins/`, OAuth in `src/services/oauth/`, and LSP in `src/services/lsp/`. These are separate boundaries because they introduce network transports, auth, and external process lifecycles.

11. Background and multi-agent behavior are modeled explicitly. `src/tasks/` and `src/services/task*` cover local, remote, shell, and teammate task lifecycles; `src/utils/swarm/` and `src/coordinator/` handle multi-agent/team coordination; and `src/services/compact/`, `src/services/contextCollapse/`, and memory extraction services manage long-running sessions under context pressure.

12. Cross-cutting services include logging/analytics, update checks, voice input, sandboxing, and system integration. In this fork, telemetry-related paths exist structurally but are intended to be stripped or stubbed; voice, auto-updater, sandbox, and platform-specific helpers live under `src/services/`, `src/voice/`, `src/utils/sandbox/`, and related utility modules.

13. Build and feature gating are also part of the architecture. `scripts/build.ts` and `bun.lock` show that the binary is compiled with feature flags, and the repo contains many gated capabilities under `src/constants/`, `src/utils/betas.ts`, and feature-specific modules, so the shipped binary shape depends on build-time configuration.

14. For an architecture diagram, the most important flow is: terminal input → command/prompt normalization → query engine → provider API + tools/permissions → state/session/memory updates → Ink UI render loop. Secondary flows branch out to IDE/remote bridges, MCP/LSP/plugin integrations, and background task orchestration.

Main entry points: [`src/QueryEngine.ts`](https://github.com/paoloanzn/free-code/blob/main/src/QueryEngine.ts) (Query engine), [`src/state/store.ts`](https://github.com/paoloanzn/free-code/blob/main/src/state/store.ts) (App state), [`src/components/App.tsx`](https://github.com/paoloanzn/free-code/blob/main/src/components/App.tsx) (App shell), [`src/tasks.ts`](https://github.com/paoloanzn/free-code/blob/main/src/tasks.ts) (Tasks & swarm)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime_ui["Runtime & UI"]
  node_entry_cli["CLI entry<br/>entrypoint<br/>[cli.tsx]"]
  node_repl_screen["REPL screen<br/>[REPL.tsx]"]
  node_app_shell["App shell<br/>ui shell<br/>[App.tsx]"]
  node_ink_stack["Ink stack<br/>terminal renderer"]
  node_prompt_input["Prompt input<br/>input pipeline<br/>[PromptInput.tsx]"]
  node_message_view["Message view<br/>conversation ui<br/>[Messages.tsx]"]
  node_command_system["Commands<br/>slash command system<br/>[commands.ts]"]
  node_input_normalizer["Input normalize<br/>input parser"]
end

subgraph group_ai_core["AI Core"]
  node_query_engine["Query engine<br/>orchestrator<br/>[QueryEngine.ts]"]
  node_query_config["Query config<br/>query policy<br/>[config.ts]"]
  node_model_providers["Providers<br/>model boundary<br/>[providers.ts]"]
  node_api_clients["API clients<br/>service client<br/>[client.ts]"]
end

subgraph group_tools_safety["Tools & Safety"]
  node_tool_registry["Tool registry<br/>tool catalog<br/>[tools.ts]"]
  node_tool_exec["Tool exec<br/>tool runtime"]
  node_permissions["Permissions<br/>approval policy<br/>[permissions.ts]"]
  node_permission_ui["Approval UI<br/>permission ui"]
end

subgraph group_state_memory["State & Memory"]
  node_app_state["App state<br/>state store<br/>[store.ts]"]
  node_session_memory["Session memory<br/>persistence<br/>[history.ts]"]
  node_memory_dir["Memory dir<br/>memory subsystem<br/>[memdir.ts]"]
end

subgraph group_integrations["Integrations"]
  node_bridge_remote["Bridge & remote<br/>integration bridge<br/>[bridgeMain.ts]"]
  node_mcp_lsp_plugins["MCP/LSP/plugins<br/>integration suite"]
  node_oauth_misc["OAuth & auth<br/>auth boundary<br/>[client.ts]"]
end

subgraph group_background["Background Systems"]
  node_tasks_swarm["Tasks & swarm<br/>background orchestration<br/>[tasks.ts]"]
end

node_entry_cli -->|"starts"| node_repl_screen
node_repl_screen -->|"mounts"| node_app_shell
node_app_shell -->|"renders via"| node_ink_stack
node_app_shell -->|"hosts"| node_prompt_input
node_app_shell -->|"shows"| node_message_view
node_prompt_input -->|"submits"| node_input_normalizer
node_input_normalizer -->|"routes commands"| node_command_system
node_input_normalizer -->|"routes prompt"| node_query_engine
node_command_system -->|"updates"| node_app_state
node_query_engine -->|"uses"| node_query_config
node_query_engine -->|"selects"| node_model_providers
node_model_providers -->|"calls"| node_api_clients
node_query_engine -->|"invokes tools"| node_tool_registry
node_tool_registry -->|"executes via"| node_tool_exec
node_tool_exec -->|"checks"| node_permissions
node_permissions -->|"prompts"| node_permission_ui
node_tool_exec -->|"records"| node_app_state
node_query_engine -->|"persists turn"| node_app_state
node_app_state -->|"hydrates"| node_session_memory
node_session_memory -->|"reads memory"| node_memory_dir
node_bridge_remote -->|"syncs"| node_app_state
node_bridge_remote -.->|"participates in"| node_permissions
node_mcp_lsp_plugins -->|"extends"| node_tool_registry
node_oauth_misc -->|"authenticates"| node_mcp_lsp_plugins
node_tasks_swarm -->|"tracks"| node_app_state
node_tasks_swarm -->|"uses"| node_tool_exec
node_tasks_swarm -->|"updates"| node_session_memory
node_query_engine -.->|"spawns"| node_tasks_swarm
node_app_shell -->|"surfaces"| node_bridge_remote

click node_entry_cli "https://github.com/paoloanzn/free-code/blob/main/src/entrypoints/cli.tsx"
click node_repl_screen "https://github.com/paoloanzn/free-code/blob/main/src/screens/REPL.tsx"
click node_app_shell "https://github.com/paoloanzn/free-code/blob/main/src/components/App.tsx"
click node_ink_stack "https://github.com/paoloanzn/free-code/tree/main/src/ink"
click node_prompt_input "https://github.com/paoloanzn/free-code/blob/main/src/components/PromptInput/PromptInput.tsx"
click node_message_view "https://github.com/paoloanzn/free-code/blob/main/src/components/Messages.tsx"
click node_command_system "https://github.com/paoloanzn/free-code/blob/main/src/commands.ts"
click node_input_normalizer "https://github.com/paoloanzn/free-code/blob/main/src/utils/processUserInput/processUserInput.ts"
click node_query_engine "https://github.com/paoloanzn/free-code/blob/main/src/QueryEngine.ts"
click node_query_config "https://github.com/paoloanzn/free-code/blob/main/src/query/config.ts"
click node_model_providers "https://github.com/paoloanzn/free-code/blob/main/src/utils/model/providers.ts"
click node_api_clients "https://github.com/paoloanzn/free-code/blob/main/src/services/api/client.ts"
click node_tool_registry "https://github.com/paoloanzn/free-code/blob/main/src/tools.ts"
click node_tool_exec "https://github.com/paoloanzn/free-code/blob/main/src/services/tools/toolOrchestration.ts"
click node_permissions "https://github.com/paoloanzn/free-code/blob/main/src/utils/permissions/permissions.ts"
click node_permission_ui "https://github.com/paoloanzn/free-code/blob/main/src/components/permissions/PermissionDialog.tsx"
click node_app_state "https://github.com/paoloanzn/free-code/blob/main/src/state/store.ts"
click node_session_memory "https://github.com/paoloanzn/free-code/blob/main/src/history.ts"
click node_memory_dir "https://github.com/paoloanzn/free-code/blob/main/src/memdir/memdir.ts"
click node_bridge_remote "https://github.com/paoloanzn/free-code/blob/main/src/bridge/bridgeMain.ts"
click node_mcp_lsp_plugins "https://github.com/paoloanzn/free-code/blob/main/src/services/mcp/MCPConnectionManager.tsx"
click node_oauth_misc "https://github.com/paoloanzn/free-code/blob/main/src/services/oauth/client.ts"
click node_tasks_swarm "https://github.com/paoloanzn/free-code/blob/main/src/tasks.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry_cli,node_repl_screen,node_app_shell,node_ink_stack,node_prompt_input,node_message_view,node_command_system,node_input_normalizer toneBlue
class node_query_engine,node_query_config,node_model_providers,node_api_clients toneAmber
class node_tool_registry,node_tool_exec,node_permissions,node_permission_ui toneMint
class node_app_state,node_session_memory,node_memory_dir toneRose
class node_bridge_remote,node_mcp_lsp_plugins,node_oauth_misc toneIndigo
class node_tasks_swarm toneTeal
```

## Components

### Runtime & UI

Terminal entrypoint, app shell, Ink rendering, and interactive screens.

- [CLI entry](https://github.com/paoloanzn/free-code/blob/main/src/entrypoints/cli.tsx): entrypoint · Terminal startup path for the Bun/TypeScript binary. · `src/entrypoints/cli.tsx`
- [REPL screen](https://github.com/paoloanzn/free-code/blob/main/src/screens/REPL.tsx): screen · Primary terminal screen that hosts the interactive loop. · `src/screens/REPL.tsx`
- [App shell](https://github.com/paoloanzn/free-code/blob/main/src/components/App.tsx): ui shell · Coordinates prompt entry, message rendering, dialogs, shortcuts, and status UI. · `src/components/App.tsx`
- [Ink stack](https://github.com/paoloanzn/free-code/tree/main/src/ink): terminal renderer · Custom terminal rendering, layout, focus, input, scrolling, and ANSI output. · `src/ink`
- [Prompt input](https://github.com/paoloanzn/free-code/blob/main/src/components/PromptInput/PromptInput.tsx): input pipeline · Interactive prompt box, history, modes, and user typing controls. · `src/components/PromptInput/PromptInput.tsx`
- [Message view](https://github.com/paoloanzn/free-code/blob/main/src/components/Messages.tsx): conversation ui · Renders user/assistant/tool messages and transcript state in the TUI. · `src/components/Messages.tsx`
- [Commands](https://github.com/paoloanzn/free-code/blob/main/src/commands.ts): slash command system · Slash commands and command handlers for session actions and modes. · `src/commands.ts`
- [Input normalize](https://github.com/paoloanzn/free-code/blob/main/src/utils/processUserInput/processUserInput.ts): input parser · Normalizes raw text, bash-like input, and slash commands before dispatch. · `src/utils/processUserInput/processUserInput.ts`

### AI Core

Query assembly, model/provider selection, and turn control.

- [Query engine](https://github.com/paoloanzn/free-code/blob/main/src/QueryEngine.ts): orchestrator · Main AI turn loop that assembles context and drives request/response turns. · `src/QueryEngine.ts`
- [Query config](https://github.com/paoloanzn/free-code/blob/main/src/query/config.ts): query policy · Token budgeting, stop hooks, and query-time configuration. · `src/query/config.ts`
- [Providers](https://github.com/paoloanzn/free-code/blob/main/src/utils/model/providers.ts): model boundary · Provider/model abstraction and backend selection across Anthropic, OpenAI Codex, Bedrock, Vertex, and Foundry. · `src/utils/model/providers.ts`
- [API clients](https://github.com/paoloanzn/free-code/blob/main/src/services/api/client.ts): service client · HTTP and SDK clients for model and platform APIs. · `src/services/api/client.ts`

### Tools & Safety

Tool registry, execution, and permission/approval flow.

- [Tool registry](https://github.com/paoloanzn/free-code/blob/main/src/tools.ts): tool catalog · Registers major tools and exposes the tool surface to the query loop. · `src/tools.ts`
- [Tool exec](https://github.com/paoloanzn/free-code/blob/main/src/services/tools/toolOrchestration.ts): tool runtime · Streaming execution, orchestration, and lifecycle handling for tool calls. · `src/services/tools/toolOrchestration.ts`
- [Permissions](https://github.com/paoloanzn/free-code/blob/main/src/utils/permissions/permissions.ts): approval policy · Policy, approval, and safety checks around tool execution. · `src/utils/permissions/permissions.ts`
- [Approval UI](https://github.com/paoloanzn/free-code/blob/main/src/components/permissions/PermissionDialog.tsx): permission ui · Terminal dialogs and request screens for bash, file, notebook, web, and sandbox approvals. · `src/components/permissions/PermissionDialog.tsx`

### State & Memory

Session persistence, history, memory, and resume/bootstrap.

- [App state](https://github.com/paoloanzn/free-code/blob/main/src/state/store.ts): state store · Central application store and selectors for UI and runtime state. · `src/state/store.ts`
- [Session memory](https://github.com/paoloanzn/free-code/blob/main/src/history.ts): persistence · Session/history recovery, memory files, and resume bootstrap. · `src/history.ts`
- [Memory dir](https://github.com/paoloanzn/free-code/blob/main/src/memdir/memdir.ts): memory subsystem · User/project/team memory discovery and scanning. · `src/memdir/memdir.ts`

### Integrations

External bridges and service boundaries such as MCP, IDE, plugins, LSP, remote, and OAuth.

- [Bridge & remote](https://github.com/paoloanzn/free-code/blob/main/src/bridge/bridgeMain.ts): integration bridge · IDE/remote control bridge and transport layer for external sessions. · `src/bridge/bridgeMain.ts`
- [MCP/LSP/plugins](https://github.com/paoloanzn/free-code/blob/main/src/services/mcp/MCPConnectionManager.tsx): integration suite · External process and network integrations for MCP, LSP, and plugins. · `src/services/mcp/MCPConnectionManager.tsx`
- [OAuth & auth](https://github.com/paoloanzn/free-code/blob/main/src/services/oauth/client.ts): auth boundary · OAuth, auth helpers, and related platform/service authentication. · `src/services/oauth/client.ts`

### Background Systems

Tasks, compaction, swarm coordination, and long-running session support.

- [Tasks & swarm](https://github.com/paoloanzn/free-code/blob/main/src/tasks.ts): background orchestration · Local/remote tasks, teammate coordination, compaction, and long-running session support. · `src/tasks.ts`

## Connections

- CLI entry → REPL screen: starts · CLI entry launches the REPL screen.
- REPL screen → App shell: mounts · The REPL screen renders the main app shell.
- App shell → Ink stack: renders via · App shell is built on the custom Ink terminal stack.
- App shell → Prompt input: hosts · Shell coordinates prompt entry and input mode handling.
- App shell → Message view: shows · Shell renders conversation and tool transcript content.
- Prompt input → Input normalize: submits · Typed input is normalized before dispatch.
- Input normalize → Commands: routes commands · Slash commands are dispatched to command handlers.
- Input normalize → Query engine: routes prompt · Plain prompt text is forwarded to the AI turn loop.
- Commands → App state: updates · Commands adjust session, mode, and UI state.
- Query engine → Query config: uses · Turn execution relies on budget and stop-hook configuration.
- Query engine → Providers: selects · Query engine chooses the active model/provider backend.
- Providers → API clients: calls · Provider abstractions delegate to concrete API clients.
- Query engine → Tool registry: invokes tools · The model-driven loop can request tool execution.
- Tool registry → Tool exec: executes via · Registered tools run through the tool orchestration layer.
- Tool exec → Permissions: checks · Tool runs are gated by policy and approval logic.
- Permissions → Approval UI: prompts · Approval decisions surface in dedicated dialogs.
- Tool exec → App state: records · Tool activity and results flow back into application state.
- Query engine → App state: persists turn · Conversation state and turn metadata are stored centrally.
- App state → Session memory: hydrates · Stored sessions and history are used for resume/recovery.
- Session memory → Memory dir: reads memory · Project and team memory files are scanned and tracked.
- Bridge & remote → App state: syncs · Bridge/remote sessions mirror state into the app store.
- Bridge & remote → Permissions: participates in · Remote control flows still respect approval boundaries.
- MCP/LSP/plugins → Tool registry: extends · Integrations add or augment available tools and capabilities.
- OAuth & auth → MCP/LSP/plugins: authenticates · OAuth supports integration setup and access.
- Tasks & swarm → App state: tracks · Background tasks and swarm status are reflected in state.
- Tasks & swarm → Tool exec: uses · Task and multi-agent flows reuse the tool execution layer.
- Tasks & swarm → Session memory: updates · Long-running work updates session history and memory.
- Query engine → Tasks & swarm: spawns · Agentic turns can fan out into tasks and teammate coordination.
- App shell → Bridge & remote: surfaces · The shell exposes bridge and remote-control status/UI.
