How codebuffai/freebuff works
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: run-agent-step.ts Agent step loop · app.tsx Terminal app and chat · chat-store.ts Chat state and streaming hooks · model-config.ts Shared policy and contracts
Components 20
Terminal CLI
Interactive Bun terminal application.
- CLI entry and release launchers · Starts the packaged or workspace CLI.
cli/src/entry.ts - Terminal app and chat · Composes interaction and chat presentation.
cli/src/app.tsx - Command router · Routes slash and input-mode commands.
cli/src/commands/router.ts - Chat state and streaming hooks · Bridges sends, streamed runs, and persisted conversations.
cli/src/state/chat-store.ts - Tool progress renderer · Renders tool progress and results.
cli/src/components/tools/registry.ts
Agent Execution
Shared execution loop and integrations.
- Agent step loop · Iterates model steps and emits structured updates.
packages/agent-runtime/src/run-agent-step.ts - Prompt and model stream · Builds prompts and invokes streaming models.
packages/agent-runtime/src/prompt-agent-stream.ts - Tool stream parser · Parses model tool output.
packages/agent-runtime/src/tool-stream-parser.ts - History compaction · Fits history and tool results within context limits.
packages/agent-runtime/src/compact-history.ts - Trusted tool handlers · Executes filesystem, shell, search, web, MCP, and subagent actions.
- LLM and service providers · Connects Codebuff APIs, Claude, Gemini, Context7, and Serper.
Agent Catalog
Role definitions and delegation.
- Agent registry · Resolves registered agent templates.
packages/agent-runtime/src/templates/agent-registry.ts - Specialized agents · Planning, editing, discovery, reasoning, review, research, and delegation roles.
agents/base2/base2.ts - Agent definition types
agents/types/agent-definition.ts
Shared Platform
Contracts, SDK, and code intelligence.
- Public SDK · Offers programmatic sessions, events, cancellation, and custom capabilities.
sdk/src/index.ts - SDK runtime adapter · Adapts shared agent execution for SDK runs.
sdk/src/impl/agent-runtime.ts - Shared policy and contracts · Centralizes tool schemas, models, analytics, and environment validation.
common/src/constants/model-config.ts - Tool parameter schemas · Defines model-facing tool call parameters.
- Repository code map · Maps symbols for repository context and discovery.
packages/code-map/src/parse.ts
Other components
- BuffBench evaluation · Runs and judges competing agents on repository tasks.
evals/buffbench/main.ts
Connections 20
- 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