How to Contribute to the Freebuff Project: A Complete Guide for Developers

To contribute to the freebuff project, clone the TypeScript monorepo, install dependencies with Bun, build the SDK or CLI locally, and submit pull requests that modify only the public-facing packages.

Freebuff is an open-source collection of AI-powered developer tools built on the Codebuff multi-agent framework. As a TypeScript monorepo, it orchestrates lightweight agents that run locally or in hosted sandboxes to power Desktop, CLI, Web, Cloud, and Chat interfaces. Whether you want to fix bugs, add new agent definitions, or extend the SDK, understanding the repository structure is the first step to making effective contributions.

Understanding the Freebuff Repository Structure

Freebuff organizes its codebase into logical packages that separate concerns between the user interface, core runtime, and shared utilities.

Key directories include:

• cli/ – Houses the terminal UI and command-line interface entry points. Launch locally with bun start-cli.
• sdk/ – Contains the public JavaScript/TypeScript SDK (@codebuff/sdk on npm) used by both internal tools and external developers.
• common/ – Stores shared types and utilities such as common/src/utils/ask-user-bridge.ts for cross-package communication.
• agents/ – Defines built-in agent configurations like agents/base3-lite.ts and agents/base3-free-deepseek.ts.
• packages/agent-runtime/ – Implements the core runtime that loads agents, dispatches tools, and manages parallel workspaces.
• packages/code-map/ – Provides source-code parsing utilities that help agents locate relevant files during execution.
• packages/llm-providers/ – Contains provider shims for various LLM back-ends, including packages/llm-providers/src/openai-compatible/openai-compatible-provider.ts for OpenAI-compatible APIs.
• freebuff/ – Holds build artifacts and scripts for the Freebuff binary, with the CLI entry point at freebuff/cli/release.ts.
• scripts/tmux/ – Includes helper scripts like scripts/tmux/tmux-start.sh for running parallel agents in tmux sessions.

Setting Up Your Development Environment

Contributing to freebuff requires Bun as the package manager and build tool. The repository enforces a strict build pipeline to ensure consistency across the monorepo.

1. Clone the repository and navigate to the root directory.

2. Install dependencies using Bun:

   bun install

3. Build the required packages based on your changes:

   • Compile the SDK: bun run build:sdk
   • Build the Freebuff binary: bun run build:freebuff

The build process references tsconfig.base.json for shared compiler settings across all sub-projects, ensuring type consistency between cli/, sdk/, and packages/.

Local Development Workflow

After building, verify your changes by running the CLI directly from the source.

Start the interactive CLI session with:

bun start-cli

This command launches the terminal interface defined in the cli/ directory, allowing you to test agent behaviors, SDK modifications, or runtime changes in real-time. For testing the distributed binary workflow, you can also install the global CLI via npm:

npm install -g freebuff
cd ~/my-project
freebuff

Making Contributions

When you contribute to the freebuff project, focus exclusively on the public directories documented in the repository structure. Do not modify private backend, billing, or deployment code—these systems reside in separate private repositories.

The contribution process follows these steps:

1. Limit changes to public packages (cli/, sdk/, common/, agents/, packages/, freebuff/, scripts/).
2. Open a Pull Request against the main branch.
3. Pass automated validation – The repository runs three automated checks on every PR to validate the title, description, and scope.
4. Await maintainer review – After approval, maintainers port your changes into the private source repository. The next public export synchronizes your contribution back to the open-source repository.

This workflow ensures that proprietary infrastructure remains secure while allowing the community to enhance the public tooling.

Extending Freebuff with Custom Agents

One of the most impactful ways to contribute is by adding new agent definitions to the agents/ directory. Agents follow a structured definition pattern exported from agents/types/agent-definition.ts.

Here is a complete example of a custom agent implementation:

// agents/my-custom-agent.ts
import { AgentDefinition } from "./types/agent-definition";

export const myCustomAgent: AgentDefinition = {
  name: "my-custom-agent",
  description: "Performs a specific code transformation",
  // Define the toolset the agent can use
  tools: ["file-search", "edit"],
  // Simple plan: find files, apply a regex replace, commit
  async run(context) {
    const files = await context.runTool("file-search", { pattern: "**/*.ts" });
    for (const f of files) {
      await context.runTool("edit", { file: f, replace: /TODO/g, with: "DONE" });
    }
  },
};

Study agents/base3-lite.ts for production-grade examples of lightweight agent architectures used by the Desktop and CLI products.

Summary

• Freebuff is a TypeScript monorepo using Bun for package management and builds.
• Public directories (cli/, sdk/, agents/, packages/) are open for contribution; private backend code is off-limits.
• Build commands (bun run build:sdk, bun run build:freebuff) compile changes before testing.
• Local testing uses bun start-cli or the globally installed freebuff npm package.
• Pull requests undergo automated validation (title, description, scope) before maintainer review and private repository porting.
• Agent definitions reside in agents/ and implement the AgentDefinition interface to extend functionality.

Frequently Asked Questions

What package manager does the freebuff project use?

The freebuff project uses Bun exclusively for dependency management, scripting, and builds. After cloning the repository, run bun install to fetch all dependencies. The package.json at the repository root defines workspace configurations and build scripts like build:sdk and build:freebuff.

Can I modify the backend or billing systems when contributing?

No. Contributors must limit changes to public-facing directories such as cli/, sdk/, common/, agents/, and packages/. Backend infrastructure, billing logic, and deployment configurations reside in private repositories. The maintainers handle porting approved public PRs into these private systems.

How do I test changes to the SDK locally?

After modifying SDK code in the sdk/ directory, rebuild the package using bun run build:sdk from the repository root. The compiled output appears in the dist/ directory, which you can reference locally or link to other projects for integration testing. The CLI automatically consumes the local SDK when you run bun start-cli.

Where is the CLI entry point located in the source code?

The CLI entry point and command parsing logic reside in freebuff/cli/release.ts. This file handles the execution flow for the Freebuff binary, while the interactive terminal UI components live in the cli/ directory. For deep customization of CLI behavior, examine release.ts alongside the cli/ source files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}