How paoloanzn/free-code works
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: QueryEngine.ts Query engine · store.ts App state · App.tsx App shell · tasks.ts Tasks & swarm
Components 23
Runtime & UI
Terminal entrypoint, app shell, Ink rendering, and interactive screens.
- CLI entry · Terminal startup path for the Bun/TypeScript binary.
src/entrypoints/cli.tsx - REPL screen · Primary terminal screen that hosts the interactive loop.
src/screens/REPL.tsx - App shell · Coordinates prompt entry, message rendering, dialogs, shortcuts, and status UI.
src/components/App.tsx - Ink stack · Custom terminal rendering, layout, focus, input, scrolling, and ANSI output.
src/ink - Prompt input · Interactive prompt box, history, modes, and user typing controls.
src/components/PromptInput/PromptInput.tsx - Message view · Renders user/assistant/tool messages and transcript state in the TUI.
src/components/Messages.tsx - Commands · Slash commands and command handlers for session actions and modes.
src/commands.ts - Input normalize · 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 · Main AI turn loop that assembles context and drives request/response turns.
src/QueryEngine.ts - Query config · Token budgeting, stop hooks, and query-time configuration.
src/query/config.ts - Providers · Provider/model abstraction and backend selection across Anthropic, OpenAI Codex, Bedrock, Vertex, and Foundry.
src/utils/model/providers.ts - API clients · 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 · Registers major tools and exposes the tool surface to the query loop.
src/tools.ts - Tool exec · Streaming execution, orchestration, and lifecycle handling for tool calls.
src/services/tools/toolOrchestration.ts - Permissions · Policy, approval, and safety checks around tool execution.
src/utils/permissions/permissions.ts - Approval 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 · Central application store and selectors for UI and runtime state.
src/state/store.ts - Session memory · Session/history recovery, memory files, and resume bootstrap.
src/history.ts - Memory dir · 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 · IDE/remote control bridge and transport layer for external sessions.
src/bridge/bridgeMain.ts - MCP/LSP/plugins · External process and network integrations for MCP, LSP, and plugins.
src/services/mcp/MCPConnectionManager.tsx - OAuth & auth · 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 · Local/remote tasks, teammate coordination, compaction, and long-running session support.
src/tasks.ts
Connections 29
- 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.