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

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 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.
• 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, 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. 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, the tool list from agents/types/tools.ts, and optional context pruning from 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, 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:

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

Install all dependencies using Bun:

bun install

Verify your setup by running the test suite:

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:

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:

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.
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 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 and implemented in packages/agent-runtime/tools/. Here is how to add a custom tool:

// 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:

// 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:

// 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:

bun run freebuff --agent my-agent

Key Files for Contributors

Understanding these critical files helps you navigate the codebase effectively:

• package.json (repo root): Defines the workspace structure, scripts, and development dependencies.
• 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: Core runtime engine that loads agents and executes LLM calls.
• packages/llm-providers/openai.ts: Shim implementing the OpenAI API within the unified provider interface.
• agents/types/agent-definition.ts: Type definitions for agent modules including prompt structures and tool configurations.
• agents/__tests__/base2.test.ts: Unit tests for the base2 family of agents, serving as a reference for writing new tests.
• CONTRIBUTING.md: Comprehensive contribution guidelines including coding standards and PR templates.
• 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 when applicable.
• The CI pipeline in .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. Each agent should export a definition object conforming to the AgentDefinition interface from agents/types/agent-definition.ts, including the prompt template, required tools from agents/types/tools.ts, and optional context pruning logic.

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