# How to Contribute to the Freebuff Project: A Developer's Guide to the AI Agent Framework

> Learn how to contribute to the Freebuff AI agent framework. Fork the repo, install dependencies, branch, and submit a pull request to join the Freebuff project.

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

---

**To contribute to Freebuff, fork the repository on GitHub, install dependencies using Bun, create a feature branch following the naming convention `feat/<description>` or `fix/<description>`, and submit a pull request targeting the `main` branch after verifying all tests pass with `bun test`.**

Freebuff is a TypeScript monorepo that provides a composable AI-coding agent framework. The project uses a modular architecture split across several packages to enable plugin-style runtime behavior, CLI interfaces, and LLM provider integrations. This guide walks you through how to contribute to the Freebuff project by understanding its structure and following the established development workflow.

## Understanding the Freebuff Architecture

Before contributing, you need to understand how the codebase is organized. Freebuff follows a monorepo structure with clear separation of concerns across multiple packages.

### Core Packages and Their Roles

The repository is organized into logical packages that together form the complete framework:

- **`cli/`**: Implements the **OpenTUI and React-based** command-line interface used for interactive sessions. The entry point is configured in [`cli/tsconfig.json`](https://github.com/CodebuffAI/freebuff/blob/main/cli/tsconfig.json) and uses Bun for execution.
- **`sdk/`**: Exposes the **JavaScript/TypeScript SDK** that external users import to drive agents programmatically, providing type definitions and agent-runtime bindings.
- **`common/`**: Houses **shared types, schemas, and utilities** leveraged across the repo, centralizing configuration in [`common/tsconfig.json`](https://github.com/CodebuffAI/freebuff/blob/main/common/tsconfig.json).
- **`agents/`**: Contains **public agent definitions** such as `base2`, `base3`, and `base-chat`. Each agent is a TypeScript module exporting a `definition` that the runtime instantiates, composed of prompt templates, tool definitions, and optional post-processing logic.
- **`packages/agent-runtime/`**: The **runtime engine** that loads agents, resolves tools from [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts), and orchestrates LLM calls via dependency injection.
- **`packages/code-map/`**: Supplies **source-parsing helpers** for code-aware features like file selection and context pruning, using the TypeScript compiler API to build AST maps.
- **`packages/llm-providers/`**: Provides **shims** for various LLM backends (OpenAI, Claude, etc.), normalizing request/response formats so agents remain provider-agnostic.
- **`freebuff/`**: Packages the **CLI binary**, release artifacts, and end-to-end tests, including scripts under `scripts/tmux/` for automated UI testing.

### Runtime Execution Flow

Understanding the execution flow helps you debug and extend the system:

1. **CLI Startup**: The user runs the `freebuff` binary defined in [`freebuff/package.json`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/package.json). The CLI parses arguments and creates a runtime instance from `packages/agent-runtime`.
2. **Agent Selection**: Based on CLI flags (e.g., `--agent base2-free`), the runtime loads the corresponding agent module from `agents/`. The definition includes the prompt template from files like [`agents/base2/base2-free.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/base2/base2-free.ts), the tool list from [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts), and optional context pruning from [`agents/context-pruner.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/context-pruner.ts).
3. **Tool Resolution**: When the LLM requests a tool, the runtime resolves it against the tool registry defined in [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts), with implementations living in `packages/agent-runtime/tools/`.
4. **LLM Invocation**: The runtime forwards prompts to an LLM provider via shims in `packages/llm-providers/`.
5. **Result Handling**: Responses undergo post-processing and feed back to the CLI for display.

## Setting Up Your Development Environment

To contribute effectively, you need **Bun** installed on your system. Freebuff uses Bun exclusively for package management and execution.

First, fork the repository using the Fork button on GitHub. Then clone your fork:

```bash
git clone https://github.com/<your-username>/freebuff.git
cd freebuff

```

Install all dependencies using Bun:

```bash
bun install

```

Verify your setup by running the test suite:

```bash
bun test

```

All tests under `agents/__tests__/` and `freebuff/evals/` must pass before you submit changes. The project uses the `.prettierrc` configuration for code formatting.

## Contributing Workflow Step-by-Step

Freebuff follows a standard GitHub workflow with specific quality gates enforced by continuous integration.

### Forking and Cloning

Create your own copy of the repository by forking it on GitHub. Clone your fork locally and add the upstream remote:

```bash
git remote add upstream https://github.com/CodebuffAI/freebuff.git

```

### Installing Dependencies and Running Tests

After cloning, run `bun install` to install workspace dependencies. Before making changes, ensure the test suite passes:

```bash
bun test

```

### Making Changes and Submitting PRs

Follow these steps to ensure your contribution meets quality standards:

1. Create a feature branch following the naming convention `feat/<description>` or `fix/<description>`.
2. Make changes within the appropriate package (`agents/`, `packages/`, etc.).
3. Run linting and formatting: `bun lint` and `bun format`.
4. Write unit tests for new functionality, placing them alongside existing test files like [`agents/__tests__/base2.test.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/__tests__/base2.test.ts).
5. Commit your changes and push to your fork.
6. Open a Pull Request targeting the `main` branch.

The continuous-integration pipeline defined in [`.github/workflows/ci.yml`](https://github.com/CodebuffAI/freebuff/blob/main/.github/workflows/ci.yml) automatically runs lint, type-check, and the full test matrix on every PR.

## Extending Freebuff: Adding Tools and Agents

The modular architecture allows you to extend functionality by adding new tools or agents without modifying core runtime code.

### Creating a New Tool

Tools are defined in [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts) and implemented in `packages/agent-runtime/tools/`. Here is how to add a custom tool:

```typescript
// File: packages/agent-runtime/tools/my-tool.ts
import { Tool } from '../../agents/types/tools';

export const myTool: Tool = {
  name: 'myTool',
  description: 'Performs a custom operation for agents.',
  async run(args: any) {
    // Custom logic here
    return { result: 'ok', data: args };
  },
};

```

Register the tool in the runtime's tool map in [`packages/agent-runtime/runtime.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/runtime.ts):

```typescript
// File: packages/agent-runtime/runtime.ts
import { myTool } from './tools/my-tool';

const toolRegistry = {
  ...defaultTools,
  myTool,
};

```

### Defining a Custom Agent

Agents are TypeScript modules exporting a definition. Create a new agent in the `agents/` directory:

```typescript
// File: agents/base2/my-agent.ts
import { AgentDefinition } from '../types/agent-definition';
import { myTool } from '../../packages/agent-runtime/tools/my-tool';

export const myAgent: AgentDefinition = {
  name: 'my-agent',
  prompt: `You are a helpful coding assistant. Use {{tool}} when needed.`,
  tools: [myTool],
  // Optional: custom context pruner
  pruneContext: (ctx) => ctx.slice(-5),
};

```

Test your agent using the CLI:

```bash
bun run freebuff --agent my-agent

```

## Key Files for Contributors

Understanding these critical files helps you navigate the codebase effectively:

- **[`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json)** (repo root): Defines the workspace structure, scripts, and development dependencies.
- **[`agents/base2/base2-free.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/base2/base2-free.ts)**: Example implementation of a ready-to-use "free" agent demonstrating prompt templates and tool integration.
- **[`packages/agent-runtime/runtime.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/runtime.ts)**: Core runtime engine that loads agents and executes LLM calls.
- **[`packages/llm-providers/openai.ts`](https://github.com/CodebuffAI/freebuff/blob/main/packages/llm-providers/openai.ts)**: Shim implementing the OpenAI API within the unified provider interface.
- **[`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/agent-definition.ts)**: Type definitions for agent modules including prompt structures and tool configurations.
- **[`agents/__tests__/base2.test.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/__tests__/base2.test.ts)**: Unit tests for the `base2` family of agents, serving as a reference for writing new tests.
- **[`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md)**: Comprehensive contribution guidelines including coding standards and PR templates.
- **[`README.md`](https://github.com/CodebuffAI/freebuff/blob/main/README.md)**: High-level project overview and quick-start instructions.

## Summary

- Freebuff is a TypeScript monorepo with a modular architecture separating CLI, SDK, runtime, and agent definitions.
- Use **Bun** for all package management and testing commands (`bun install`, `bun test`).
- Follow the branch naming convention `feat/<description>` or `fix/<description>` when contributing.
- All changes require passing tests under `agents/__tests__/` and `freebuff/evals/`, plus linting and formatting checks.
- New functionality should include unit tests and documentation updates to [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) when applicable.
- The CI pipeline in [`.github/workflows/ci.yml`](https://github.com/CodebuffAI/freebuff/blob/main/.github/workflows/ci.yml) enforces quality standards on every pull request.

## Frequently Asked Questions

### What programming language is Freebuff written in?

Freebuff is written in **TypeScript** and organized as a monorepo. The project uses Bun as its JavaScript runtime and package manager, and it leverages the TypeScript compiler API for code-aware features like AST parsing in `packages/code-map/`.

### Do I need to understand AI or LLM internals to contribute?

No, you do not need deep AI expertise to contribute. While the project orchestrates LLM calls through `packages/llm-providers/`, many contributions involve standard TypeScript development such as adding tools in `packages/agent-runtime/tools/`, improving the CLI interface in `cli/`, or writing tests. The architecture abstracts LLM complexity behind provider shims.

### How do I test my changes before submitting a pull request?

Run `bun test` to execute the full test suite including unit tests under `agents/__tests__/` and evaluation tests in `freebuff/evals/`. Additionally, run `bun lint` and `bun format` to ensure code style compliance. You can manually test agents using `bun run freebuff --agent <agent-name>`.

### Where should I place new agent definitions?

Place new agent definitions in the `agents/` directory, following the pattern established by [`agents/base2/base2-free.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/base2/base2-free.ts). Each agent should export a definition object conforming to the `AgentDefinition` interface from [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/agent-definition.ts), including the prompt template, required tools from [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts), and optional context pruning logic.