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

> Learn how to contribute to the freebuff project. Clone the monorepo, install dependencies, build locally, and submit pull requests to help develop this open-source tool.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/utils/ask-user-bridge.ts) for cross-package communication.
- **`agents/`** – Defines built-in agent configurations like [`agents/base3-lite.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/base3-lite.ts) and [`agents/base3-free-deepseek.ts`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/release.ts).
- **`scripts/tmux/`** – Includes helper scripts like [`scripts/tmux/tmux-start.sh`](https://github.com/CodebuffAI/freebuff/blob/main/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:
   ```bash
   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`](https://github.com/CodebuffAI/freebuff/blob/main/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:

```bash
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:

```bash
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`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/agent-definition.ts).

Here is a complete example of a custom agent implementation:

```typescript
// 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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/release.ts) alongside the `cli/` source files.