# codebuffai/freebuff architecture

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

- Interactive diagram: https://gitdiagram.com/codebuffai/freebuff
- Repository: https://github.com/codebuffai/freebuff

## Overview

#### Purpose and Product Surface
Freebuff is a Bun/TypeScript monorepo for an AI coding and research platform. This repository primarily implements the terminal CLI, reusable Codebuff agent runtime, public SDK, agent definitions, and shared product policy. The runnable CLI starts through `cli/src/entry.ts` / `cli/src/index.tsx`; development uses the root Bun workspace. Packaged CLI launch/release wrappers live in `cli/release-core/launcher.js` and `cli/release/index.js`.

#### Terminal Application Layer
The CLI is a React terminal UI that owns user interaction, chat rendering, local state, authentication, and command routing. `cli/src/app.tsx` composes the application; `cli/src/chat.tsx` drives chat presentation; `cli/src/commands/router.ts` dispatches slash and input-mode commands. Stores and hooks bridge UI actions to streamed agent runs and persisted conversation state: `cli/src/state/chat-store.ts`, `cli/src/hooks/use-send-message.ts`, and `cli/src/hooks/use-chat-streaming.ts`.

#### Agent Runtime and Execution Loop
`packages/agent-runtime` is the framework core used by product clients and SDK. It builds prompts, calls models, parses streaming model/tool output, iterates agent steps, manages history compaction, and emits structured updates. Key control points are `packages/agent-runtime/src/run-agent-step.ts`, `packages/agent-runtime/src/prompt-agent-stream.ts`, and `packages/agent-runtime/src/tool-stream-parser.ts`. Context-budget boundaries and compaction are handled by `packages/agent-runtime/src/compact-history.ts` and `packages/agent-runtime/src/util/fit-tool-results.ts`.

#### Agent Catalog and Delegation
Specialized agent definitions encode task roles and model/prompt variants: planning and orchestration (`agents/base2/base2.ts`, `agents/base3.ts`), implementation (`agents/editor/editor.ts`), repository discovery (`agents/file-explorer/file-picker.ts`), reasoning (`agents/thinker/thinker.ts`), review (`agents/reviewer/code-reviewer.ts`), research/browser workflows, and multi-agent delegation. Agents are typed through `agents/types/agent-definition.ts`; runtime templates and registry support live in `packages/agent-runtime/src/templates/agent-registry.ts`. The control flow is user request → primary agent selects context/tools/subagents → streamed steps and tool results → final response and optional edits/review.

#### Tool Boundary and Local Effects
Tools are declared with shared parameter schemas in `common/src/tools/params/tool/` and executed by runtime handlers in `packages/agent-runtime/src/tools/handlers/tool/`. This separates model-supplied calls from trusted local implementations. Material capabilities include filesystem reads/writes and patches (`read-files.ts`, `write-file.ts`, `apply-patch.ts`), shell execution (`run-terminal-command.ts`), search, web/docs access, skills, MCP, and subagent spawning. The CLI renders tool progress/results through `cli/src/components/tools/registry.ts`. Local execution is bounded by project paths, sandbox-related SDK tools, and terminal process control.

#### SDK and Embedding Interface
`@codebuff/sdk` exposes programmatic agent execution separate from the interactive CLI. Its public surface begins at `sdk/src/index.ts`; `sdk/src/run.ts` manages a run/session; `sdk/src/impl/agent-runtime.ts` adapts the shared runtime; and `sdk/src/client.ts` handles service connectivity. It supports custom agents, skills, MCP configuration, BYOK credentials, streamed events, filesystem tools, and cancellation.

#### Shared Policy, Providers, and Infrastructure
`common` centralizes cross-client contracts, tool schemas, model catalog/access rules, analytics, ads, and environment validation: `common/src/constants/model-config.ts`, `common/src/constants/freebuff-models.ts`, and `common/src/env-schema.ts`. Provider integration spans Codebuff web APIs, Claude, Gemini, Context7, and Serper in `packages/agent-runtime/src/llm-api/`; generic OpenAI-compatible adapters are in `packages/llm-providers/src/openai-compatible/`. Product infrastructure includes API/auth/usage calls, analytics/log shipping, Composio and MCP integrations, and Supabase-oriented sponsored/ads contracts. Docker plus `.env.local` support local service development.

#### Code Intelligence and Evaluation
Repository-aware symbol mapping uses Tree-sitter across major languages in `packages/code-map/src/parse.ts` and query assets under `packages/code-map/src/tree-sitter-queries/`. This supports agent file discovery/context selection alongside ripgrep-backed local search. Agent quality is measured by the BuffBench harness in `evals/buffbench/main.ts`, which runs competing agent runners and judges repository tasks.

Main entry points: [`packages/agent-runtime/src/run-agent-step.ts`](https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/run-agent-step.ts) (Agent step loop), [`cli/src/app.tsx`](https://github.com/codebuffai/freebuff/blob/main/cli/src/app.tsx) (Terminal app and chat), [`cli/src/state/chat-store.ts`](https://github.com/codebuffai/freebuff/blob/main/cli/src/state/chat-store.ts) (Chat state and streaming hooks), [`common/src/constants/model-config.ts`](https://github.com/codebuffai/freebuff/blob/main/common/src/constants/model-config.ts) (Shared policy and contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Terminal CLI"]
  node_cli_entry["CLI entry and release launchers<br/>Bun entrypoints<br/>[entry.ts]"]
  node_cli_app["Terminal app and chat<br/>React terminal UI<br/>[app.tsx]"]
  node_command_router["Command router<br/>input dispatch<br/>[router.ts]"]
  node_chat_state["Chat state and streaming hooks<br/>UI state<br/>[chat-store.ts]"]
  node_tool_renderer["Tool progress renderer<br/>UI registry<br/>[registry.ts]"]
end

subgraph group_runtime["Agent Execution"]
  node_agent_loop{{"Agent step loop<br/>runtime core<br/>[run-agent-step.ts]"}}
  node_prompt_stream["Prompt and model stream<br/>LLM streaming"]
  node_tool_parser["Tool stream parser"]
  node_history_budget["History compaction<br/>context management<br/>[compact-history.ts]"]
  node_tool_handlers["Trusted tool handlers<br/>local execution"]
  node_provider_layer["LLM and service providers<br/>provider integrations"]
end

subgraph group_catalog["Agent Catalog"]
  node_agent_registry["Agent registry<br/>runtime templates<br/>[agent-registry.ts]"]
  node_agent_definitions["Specialized agents<br/>agent definitions<br/>[base2.ts]"]
  node_agent_types["Agent definition types<br/>shared typing"]
end

subgraph group_platform["Shared Platform"]
  node_sdk["Public SDK<br/>embedding API<br/>[index.ts]"]
  node_sdk_runtime_adapter["SDK runtime adapter<br/>[agent-runtime.ts]"]
  node_shared_policy["Shared policy and contracts<br/>common package<br/>[model-config.ts]"]
  node_tool_schemas["Tool parameter schemas<br/>tool contracts"]
  node_code_map["Repository code map<br/>Tree-sitter analysis<br/>[parse.ts]"]
end

node_evaluation["BuffBench evaluation<br/>agent benchmark<br/>[main.ts]"]

node_cli_entry -->|"starts"| node_cli_app
node_cli_app -->|"routes input"| node_command_router
node_cli_app -->|"uses"| node_chat_state
node_chat_state -->|"streams runs"| node_agent_loop
node_agent_loop -->|"requests next step"| node_prompt_stream
node_prompt_stream -->|"calls models"| node_provider_layer
node_agent_loop -->|"parses output"| node_tool_parser
node_agent_loop -->|"compacts context"| node_history_budget
node_agent_loop -->|"executes calls"| node_tool_handlers
node_tool_handlers -->|"validates against"| node_tool_schemas
node_tool_renderer -->|"shows streamed tools"| node_chat_state
node_agent_loop -->|"resolves agent"| node_agent_registry
node_agent_registry -->|"registers"| node_agent_definitions
node_agent_definitions -->|"implements"| node_agent_types
node_agent_loop -.->|"selects repository context"| node_code_map
node_sdk -->|"creates runs"| node_sdk_runtime_adapter
node_sdk_runtime_adapter -->|"uses"| node_agent_loop
node_shared_policy -.->|"governs model access"| node_provider_layer
node_shared_policy -->|"hosts"| node_tool_schemas
node_evaluation -.->|"benchmarks runners"| node_agent_loop

click node_cli_entry "https://github.com/codebuffai/freebuff/blob/main/cli/src/entry.ts"
click node_cli_app "https://github.com/codebuffai/freebuff/blob/main/cli/src/app.tsx"
click node_command_router "https://github.com/codebuffai/freebuff/blob/main/cli/src/commands/router.ts"
click node_chat_state "https://github.com/codebuffai/freebuff/blob/main/cli/src/state/chat-store.ts"
click node_tool_renderer "https://github.com/codebuffai/freebuff/blob/main/cli/src/components/tools/registry.ts"
click node_agent_loop "https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/run-agent-step.ts"
click node_prompt_stream "https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/prompt-agent-stream.ts"
click node_tool_parser "https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/tool-stream-parser.ts"
click node_history_budget "https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/compact-history.ts"
click node_agent_registry "https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/templates/agent-registry.ts"
click node_agent_definitions "https://github.com/codebuffai/freebuff/blob/main/agents/base2/base2.ts"
click node_agent_types "https://github.com/codebuffai/freebuff/blob/main/agents/types/agent-definition.ts"
click node_sdk "https://github.com/codebuffai/freebuff/blob/main/sdk/src/index.ts"
click node_sdk_runtime_adapter "https://github.com/codebuffai/freebuff/blob/main/sdk/src/impl/agent-runtime.ts"
click node_shared_policy "https://github.com/codebuffai/freebuff/blob/main/common/src/constants/model-config.ts"
click node_code_map "https://github.com/codebuffai/freebuff/blob/main/packages/code-map/src/parse.ts"
click node_evaluation "https://github.com/codebuffai/freebuff/blob/main/evals/buffbench/main.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_cli_entry,node_cli_app,node_command_router,node_chat_state,node_tool_renderer toneBlue
class node_agent_loop,node_prompt_stream,node_tool_parser,node_history_budget,node_tool_handlers,node_provider_layer toneAmber
class node_agent_registry,node_agent_definitions,node_agent_types toneMint
class node_sdk,node_sdk_runtime_adapter,node_shared_policy,node_tool_schemas,node_code_map toneRose
class node_evaluation toneNeutral
```

## Components

### Terminal CLI

Interactive Bun terminal application.

- [CLI entry and release launchers](https://github.com/codebuffai/freebuff/blob/main/cli/src/entry.ts): Bun entrypoints · Starts the packaged or workspace CLI. · `cli/src/entry.ts`
- [Terminal app and chat](https://github.com/codebuffai/freebuff/blob/main/cli/src/app.tsx): React terminal UI · Composes interaction and chat presentation. · `cli/src/app.tsx`
- [Command router](https://github.com/codebuffai/freebuff/blob/main/cli/src/commands/router.ts): input dispatch · Routes slash and input-mode commands. · `cli/src/commands/router.ts`
- [Chat state and streaming hooks](https://github.com/codebuffai/freebuff/blob/main/cli/src/state/chat-store.ts): UI state · Bridges sends, streamed runs, and persisted conversations. · `cli/src/state/chat-store.ts`
- [Tool progress renderer](https://github.com/codebuffai/freebuff/blob/main/cli/src/components/tools/registry.ts): UI registry · Renders tool progress and results. · `cli/src/components/tools/registry.ts`

### Agent Execution

Shared execution loop and integrations.

- [Agent step loop](https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/run-agent-step.ts): runtime core · Iterates model steps and emits structured updates. · `packages/agent-runtime/src/run-agent-step.ts`
- [Prompt and model stream](https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/prompt-agent-stream.ts): LLM streaming · Builds prompts and invokes streaming models. · `packages/agent-runtime/src/prompt-agent-stream.ts`
- [Tool stream parser](https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/tool-stream-parser.ts): stream parser · Parses model tool output. · `packages/agent-runtime/src/tool-stream-parser.ts`
- [History compaction](https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/compact-history.ts): context management · Fits history and tool results within context limits. · `packages/agent-runtime/src/compact-history.ts`
- **Trusted tool handlers**: local execution · Executes filesystem, shell, search, web, MCP, and subagent actions.
- **LLM and service providers**: provider integrations · Connects Codebuff APIs, Claude, Gemini, Context7, and Serper.

### Agent Catalog

Role definitions and delegation.

- [Agent registry](https://github.com/codebuffai/freebuff/blob/main/packages/agent-runtime/src/templates/agent-registry.ts): runtime templates · Resolves registered agent templates. · `packages/agent-runtime/src/templates/agent-registry.ts`
- [Specialized agents](https://github.com/codebuffai/freebuff/blob/main/agents/base2/base2.ts): agent definitions · Planning, editing, discovery, reasoning, review, research, and delegation roles. · `agents/base2/base2.ts`
- [Agent definition types](https://github.com/codebuffai/freebuff/blob/main/agents/types/agent-definition.ts): shared typing · `agents/types/agent-definition.ts`

### Shared Platform

Contracts, SDK, and code intelligence.

- [Public SDK](https://github.com/codebuffai/freebuff/blob/main/sdk/src/index.ts): embedding API · Offers programmatic sessions, events, cancellation, and custom capabilities. · `sdk/src/index.ts`
- [SDK runtime adapter](https://github.com/codebuffai/freebuff/blob/main/sdk/src/impl/agent-runtime.ts): runtime adapter · Adapts shared agent execution for SDK runs. · `sdk/src/impl/agent-runtime.ts`
- [Shared policy and contracts](https://github.com/codebuffai/freebuff/blob/main/common/src/constants/model-config.ts): common package · Centralizes tool schemas, models, analytics, and environment validation. · `common/src/constants/model-config.ts`
- **Tool parameter schemas**: tool contracts · Defines model-facing tool call parameters.
- [Repository code map](https://github.com/codebuffai/freebuff/blob/main/packages/code-map/src/parse.ts): Tree-sitter analysis · Maps symbols for repository context and discovery. · `packages/code-map/src/parse.ts`

### Other components

- [BuffBench evaluation](https://github.com/codebuffai/freebuff/blob/main/evals/buffbench/main.ts): agent benchmark · Runs and judges competing agents on repository tasks. · `evals/buffbench/main.ts`

## Connections

- CLI entry and release launchers → Terminal app and chat: starts
- Terminal app and chat → Command router: routes input
- Terminal app and chat → Chat state and streaming hooks: uses
- Chat state and streaming hooks → Agent step loop: streams runs
- Agent step loop → Prompt and model stream: requests next step
- Prompt and model stream → LLM and service providers: calls models
- Agent step loop → Tool stream parser: parses output
- Agent step loop → History compaction: compacts context
- Agent step loop → Trusted tool handlers: executes calls
- Trusted tool handlers → Tool parameter schemas: validates against
- Tool progress renderer → Chat state and streaming hooks: shows streamed tools
- Agent step loop → Agent registry: resolves agent
- Agent registry → Specialized agents: registers
- Specialized agents → Agent definition types: implements
- Agent step loop → Repository code map: selects repository context
- Public SDK → SDK runtime adapter: creates runs
- SDK runtime adapter → Agent step loop: uses
- Shared policy and contracts → LLM and service providers: governs model access
- Shared policy and contracts → Tool parameter schemas: hosts
- BuffBench evaluation → Agent step loop: benchmarks runners