Agent Architecture

Freebuff

Freebuff (the product formerly named Codebuff; the adapter id stays codebuff) is an open-source terminal coding agent with a codebase-indexing product story, an npm CLI install path, and repository folders for agents, CLI, docs, evals, packages, and SDK. Its connector surfaces are MCP, skills, subagents, and memory under .agents.

Source reviewed #21Checked 2026-07-06

Setup guide Source

Run type

CLI

Adapter

mcp-only

Source

OSS · CodebuffAI/freebuff

Stars

★ 12k

Archive Context

This page is one host entry inside the full architecture archive and keeps multi-surface products visible instead of collapsing them into a single run type.

42 host archive

Host page

codebuff

Run cohort

CLI: 30

Archive route

/agents

Host Surface Perspectives

The host is the primary architecture boundary. Each runnable surface below separates what the host owns from what agent-connector can safely install for Freebuff.

1 surface entry

CLI

cli

Host entry: A terminal command owns the process, current working directory, stdin/stdout, shell environment, and project file discovery.
Host owns: The CLI host owns agent loop timing, approval prompts, tool execution, session files, and how hook or MCP subprocesses are launched.
Connector role: agent-connector can only write the host's documented CLI config, prompt, memory, hook, MCP, or package files and point them at the home binary. Current wired connector surfaces: MCP server, Skills, Subagents, Memory.
Implementation consequence: A CLI surface is byte-addressable and smoke-testable from a temporary HOME, but terminal UI behavior still belongs to the host process. No visible host-native gap is currently tracked for this surface.

Verified Architecture

Source-checked on 2026-07-06. These notes are intentionally separate from the generated surface matrix below.

Sequence #21

Source pass

Current source review findings are kept as the first architecture section so readers can separate external evidence from the generated local coverage model.

Freebuff is the renamed Codebuff (repository, npm package, and binary all moved to freebuff on 2026-09-02); the adapter id stays codebuff and the .agents config contract did not move.
The repository describes a multi-agent flow with file picker, planner, editor, and reviewer agents, so subagent support is a host-native concept here.
`knowledge.md` and `.agents/types` are generated by `/init`, which makes memory and custom agent authoring concrete file-backed surfaces.

Runtime boundary

The adapter target is the terminal CLI. Codebuff owns project indexing, code edits, command execution, conversation flow, and product account behavior; agent-connector should only claim the local files and runtime hooks it can verify.

The npm package and binary were renamed from codebuff to freebuff; the config contract did not move.
The repository contains CLI, agents, docs, evals, packages, and SDK folders.
The product story emphasizes whole-codebase understanding and multi-turn workflows.

MCP registration

MCP registration is the adapter's runtime surface: sdk/src/agents/load-mcp-config.ts searches <cwd>/.agents/mcp.json, <cwd>/../.agents/mcp.json, and ~/.agents/mcp.json for the mcpServers root key, and the adapter writes that file.

The lookup order means a parent-directory .agents/mcp.json can serve several sibling projects.
Do not infer additional MCP semantics from the repository's SDK folder alone.

Hook bridge

Freebuff is mcp-only in the connector matrix: no user-installable lifecycle hook file is documented, so agent-connector wires no hook bridge. Benchmark, indexing, and terminal workflow behavior stay Freebuff-owned agent logic.

Runtime interception, if it ever appears, would need a documented hook file or event contract before the coverage chip changes.
Project indexing and code-generation loops are host behavior, not hook semantics.

Content surfaces

Content surfaces are wired under .agents: skills as .agents/skills (AgentSkills format, verified in load-skills.ts) and subagents as project-scoped .agents/<id>.ts AgentDefinition modules that default-export one object. Memory is AGENTS.md. Slash commands are not a host surface.

Subagent modules must not use type-only imports; the host loads them as plain modules.
The .codebuffignore file is a host-specific project filter, separate from these content surfaces.

Marketplace and host-only affordances

The host-only affordance is fast whole-codebase indexing plus a public benchmark and SDK story around terminal coding. That makes Freebuff useful for comparing codebase-awareness architectures against editor-first agents.

BuffBench and generated workflow evaluation are product/evaluation surfaces.
The SDK folder is a future integration signal, not automatic connector SDK compatibility.

Host-specific shape

Freebuff (formerly Codebuff) is mcp-only for runtime interception but has strong project content: skills, memory, and TypeScript AgentDefinition modules for subagents.

Form factor: CLI.
Native surfaces: MCP server, Skills, Subagents, Memory.
Wired surfaces: MCP server, Skills, Subagents, Memory.
Visible gaps: none.

Hooks

No user-installable lifecycle hook boundary is confirmed for this host.

MCP

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace and affordances

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

Runtime handlers: none.
User-visible affordances: Users see managed skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary..

Known Limits

MCP and hook claims need local adapter or source evidence rather than product-page inference.
The public website is marketing-heavy; detailed internals should come from repository/docs review.
SDK presence should be separated from implemented agent-connector support.

Evidence checked

Freebuff website Freebuff repository

Architecture Diagram

Host-specific flow for the CLI surface.

mcp-only

1
Entry point: CLI
Terminal agent process reads user/project config and invokes the connector home binary for runtime callbacks.
2
Connector package
defineConnector package declares server, hooks, content, memory, and actions.
3
Adapter module: codebuff
mcp-only renderer at src/adapters/codebuff/index.ts.
4
Native host artifacts
Adapter writes MCP config + content files + memory/rules through this host's native file, package, or marketplace surface.
5
Runtime boundary
host calls MCP tools through its client
6
User-visible surface
Users see managed skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary.
7
Coverage ceiling
4/4 native surfaces wired. No visible host-native gap in the current coverage matrix.

Component Diagram

Static parts of the Freebuff integration and which side owns each one.

Freebuff host
CLI surface owns the model loop, UI shell, config discovery, and native lifecycle for this integration.
agent-connector package
Normalizes connector declarations into MCP, hook, memory, content, and action payloads before delegating to a host adapter.
codebuff adapter
Implements the mcp-only translation layer in src/adapters/codebuff/index.ts.
Native artifacts
Adapter writes MCP config + content files + memory/rules through this host's native file, package, or marketplace surface.
Runtime bridge
host calls MCP tools through its client
User-visible surface
Users see managed skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary.

Runtime Sequence Flow

Message order from install to runtime for the CLI surface.

1 · User / project
Choose host adapter
Install or update starts against Freebuff; the selected surface is CLI.
2 · agent-connector
Resolve connector declaration
The package reads connector metadata and routes it to the codebuff adapter instead of exposing a generic host contract.
3 · codebuff adapter
Render host-native shape
Adapter writes MCP config + content files + memory/rules through this host's native file, package, or marketplace surface.
4 · Freebuff
Host loads artifacts
host calls MCP tools through its client
5 · Agent runtime
Run through host boundary
Users see managed skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary.
6 · Coverage matrix
Expose remaining ceiling
4/4 native surfaces wired. No visible host-native gap in the current coverage matrix.

Architecture Archive

The same five study axes are rendered for every host: runtime shape, hooks, MCP, memory, and host-only affordances.

Host-specific shape

Freebuff (formerly Codebuff) is mcp-only for runtime interception but has strong project content: skills, memory, and TypeScript AgentDefinition modules for subagents.

Form factor: CLI.
Native surfaces: MCP server, Skills, Subagents, Memory.
Wired surfaces: MCP server, Skills, Subagents, Memory.
Visible gaps: none.

Hooks

No user-installable lifecycle hook boundary is confirmed for this host.

MCP

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace and affordances

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

Runtime handlers: none.
User-visible affordances: Users see managed skills + subagents + memory surfaces after install; runtime-only surfaces stay behind the host boundary..

Special Feature Inventory

Host-specific capabilities separated from the generic surface matrix: lifecycle hooks, MCP registration, memory/rules, marketplace delivery, and UI or content affordances owned by the host.

Lifecycle hooks

Not confirmed

No user-installable lifecycle hook boundary is confirmed for this host.

MCP registration

Wired

The adapter writes this host's native MCP registration dialect, including its root key, scope, transport fields, and environment syntax.

Memory and rules

Wired

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace delivery

Direct files

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

Host-only affordances

2/2 wired

Wired host affordances: Skills, Subagents. Host-native gaps: none. Not confirmed: Commands, Statusline handler, Action affordances.

Source Review Notes

Latest source pass for host-specific architecture details. This is separate from generated adapter coverage and local drift guards.

Checked 2026-07-06Open review source

CodebuffAI/freebuff repository

Freebuff is the renamed Codebuff (repository, npm package, and binary all moved to freebuff on 2026-09-02); the adapter id stays codebuff and the .agents config contract did not move.
The repository describes a multi-agent flow with file picker, planner, editor, and reviewer agents, so subagent support is a host-native concept here.
`knowledge.md` and `.agents/types` are generated by `/init`, which makes memory and custom agent authoring concrete file-backed surfaces.

Evidence Map

Each host page ties public source evidence to the local adapter and drift guards that keep the rendered archive aligned with code.

Public source: CodebuffAI/freebuff

Primary public repository or product source used for current host status and source links.

external

Open source

Local adapter implementation

Defines the install/uninstall behavior, native config rendering, capability flags, and any runtime parse/format bridge for this host.

local

src/adapters/codebuff/index.ts

Platform metadata and host-native matrix

Records the form factor, public source target, ranking source, native host surfaces, and current agent-connector coverage cells.

local

site/src/platform-data.ts

Architecture drift guard

Asserts that every registered host has a page, diagram, host-specific brief, source link, form-factor band, and adapter-aligned surface data.

local

tests/docs/platform-drift.test.ts

Runtime Shape

The host accepts MCP registration, but has no confirmed hook bridge for agent-connector to call.

MCP registration: Wired through this adapter
Hook bridge: No confirmed hook surface

Connector Surfaces

Static content

MCP server, Skills, Subagents, Memory

Runtime handlers

No runtime handler surfaces wired

Surface Matrix

Wired means agent-connector installs it now. Host native marks support we know about but have not wired yet.

SurfaceStatus

MCP server

Static content

agent-connector installs this surface today.

Wired

Hooks

Static content

No confirmed host-native surface.

N/A

Commands

Static content

No confirmed host-native surface.

N/A

Skills

Static content

agent-connector installs this surface today.

Wired

Subagents

Static content

agent-connector installs this surface today.

Wired

Memory

Static content

agent-connector installs this surface today.

Wired

Statusline handler

Runtime handler

No confirmed host-native surface.

N/A

Action affordances

Runtime handler

No confirmed host-native surface.

N/A