# How to Integrate Freebuff into an Existing Project: CLI and SDK Methods

> Easily integrate Freebuff into your project with the global CLI for instant AI coding or the TypeScript SDK for advanced programmatic control in CI/CD pipelines.

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

---

**You can integrate Freebuff into an existing project using either the global CLI for immediate AI-assisted coding or the TypeScript SDK for programmatic control over agents, custom tools, and CI/CD pipelines.**

Freebuff is a TypeScript-based AI-coding platform from the CodebuffAI/freebuff repository that enhances existing codebases without requiring complex configuration. Whether you need one-off refactoring or automated testing workflows, you can integrate Freebuff into an existing project through two primary entry points that operate directly on your filesystem.

## CLI Integration Method

The CLI provides the fastest path to integration. Install the tool globally and run it from any project directory:

```bash

# Install the global command

npm install -g freebuff

# Navigate to your project

cd /path/to/your/project

# Launch Freebuff

freebuff

```

When you execute the `freebuff` command, the system performs four operations defined in the [`cli/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/cli/README.md) source. First, it **scans the repository** using file-finding agents that automatically filter out sensitive files such as `.env` according to the file-filter policy documented in [`sdk/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/README.md). Second, it **selects an appropriate agent**, defaulting to the base agent unless you specify an alternative ID. Third, it **executes the agent**, allowing it to invoke built-in tools like `read_files` and `write_files`. Finally, it **applies the changes** directly to your working directory and reports a summary.

The CLI requires no API keys for the bundled free tier models—only a working internet connection to reach the hosted endpoints.

## SDK Integration Method

For projects requiring CI/CD automation, custom user interfaces, or complex multi-agent orchestration, install the **Codebuff SDK** as a dependency:

```bash
npm install @codebuff/sdk

```

Import the `CodebuffClient` class and invoke the `run()` method to execute agents programmatically:

```typescript
import { CodebuffClient } from '@codebuff/sdk'

async function runFreebuff() {
  const client = new CodebuffClient({
    // Optional: omit for free tier, or set for custom providers
    apiKey: process.env.CODEBUFF_API_KEY,
    cwd: process.cwd(),
  })

  const result = await client.run({
    agent: 'codebuff/base@0.0.16',
    prompt: 'Add unit tests for the existing calculator class',
  })

  if (result.output.type === 'error') {
    console.error('Freebuff failed:', result.output.message)
  } else {
    console.log('Freebuff succeeded:', result.output)
  }
}

runFreebuff()

```

The `CodebuffClient` constructor accepts `apiKey` and `cwd` parameters, while the `run()` method accepts `agent` and `prompt` configurations. Error states are accessible via `result.output.type` for robust pipeline handling.

### Custom Agents and Tools

The SDK supports **custom agents** and **custom tools** that you define yourself. Pass `agentDefinitions` and `customToolDefinitions` to the `run()` method to extend the AI's capabilities with domain-specific logic. The [`sdk/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/README.md) file contains a complete Example 2 demonstrating a sentiment-analysis agent and a `fetch_api_data` tool implementation.

### Knowledge Files and Filtering

Freebuff automatically discovers **knowledge files** such as [`knowledge.md`](https://github.com/CodebuffAI/freebuff/blob/main/knowledge.md) or [`AGENTS.md`](https://github.com/CodebuffAI/freebuff/blob/main/AGENTS.md) in your repository root to provide project context to the agent, as documented in the SDK's Knowledge Files section. You can override the default `.env` blocklist by supplying a custom `fileFilter` function if your project requires special file handling rules.

## Core Components and Source Locations

Understanding the repository structure helps when debugging integration issues or extending functionality:

- **CLI Entry Point**: [`cli/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/cli/README.md) documents the command-line interface that wraps the SDK client and handles terminal output.
- **SDK Client**: [`sdk/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/README.md) defines the `CodebuffClient` class and the `loadLocalAgents` helper for programmatic integration.
- **Agent Runtime**: [`packages/agent-runtime/src/templates/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/src/templates/README.md) contains the orchestration logic for agent execution and tool dispatch, used by both CLI and SDK.
- **Knowledge Discovery**: The logic for loading [`knowledge.md`](https://github.com/CodebuffAI/freebuff/blob/main/knowledge.md) and [`AGENTS.md`](https://github.com/CodebuffAI/freebuff/blob/main/AGENTS.md) is documented in the Knowledge Files section of [`sdk/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/README.md).
- **File Filtering**: Security policies excluding files like `.env` are implemented in the File Filtering section of [`sdk/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/README.md).

## Step-by-Step Integration Checklist

1. **Choose your integration style**: Use the CLI for one-off tasks and the SDK for programmatic or automated workflows.
2. **Install the package**: Run `npm install -g freebuff` for CLI access, or `npm install @codebuff/sdk` for SDK embedding.
3. **Execute Freebuff**: Type `freebuff` from your project root, or instantiate `new CodebuffClient().run()` in your TypeScript code.
4. **(Optional) Configure custom tools**: Follow the SDK Example 2 to pass `customToolDefinitions` and `agentDefinitions` to the `run()` method.
5. **(Optional) Add knowledge context**: Place [`knowledge.md`](https://github.com/CodebuffAI/freebuff/blob/main/knowledge.md) or [`AGENTS.md`](https://github.com/CodebuffAI/freebuff/blob/main/AGENTS.md) files in your repository to improve agent accuracy.

## Summary

- **Two integration paths exist**: The global CLI (`freebuff` command) for immediate use, and the `@codebuff/sdk` package for embedded TypeScript/JavaScript applications.
- **No API key required** for the free tier bundled models, though you can configure custom providers via the `apiKey` parameter in `CodebuffClient`.
- **Security by default**: The system automatically excludes sensitive files like `.env` via file filtering policies defined in the SDK, with override options available.
- **Extensible architecture**: You can define custom agents, tools, and knowledge files to tailor the AI's behavior to your specific domain.
- **Source documentation**: Key implementation details reside in [`cli/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/cli/README.md), [`sdk/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/README.md), and [`packages/agent-runtime/src/templates/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/packages/agent-runtime/src/templates/README.md).

## Frequently Asked Questions

### Do I need an API key to integrate Freebuff into an existing project?

No. The free tier bundles its own hosted models, eliminating the need for API keys or local GPU resources. You only need a stable internet connection. However, you may optionally provide an `apiKey` in the `CodebuffClient` constructor if you wish to use your own AI provider instead of the bundled models.

### Can I use Freebuff in a CI/CD pipeline?

Yes. The SDK integration method is designed for programmatic use. Import `CodebuffClient` from `@codebuff/sdk`, configure it with your project `cwd`, and invoke `run()` within your pipeline scripts. Check `result.output.type` for error handling to ensure builds fail appropriately when agents cannot complete tasks.

### How does Freebuff handle sensitive files like `.env`?

By default, Freebuff automatically filters out sensitive files including `.env` from the agent's context. This policy is documented in the File Filtering section of [`sdk/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/README.md). You can customize this behavior by passing a `fileFilter` function to the SDK configuration if your project requires access to specific configuration files.

### What is the difference between the CLI and SDK integration methods?

The **CLI** (`npm install -g freebuff`) provides an interactive, terminal-based experience where you type natural language requests and receive immediate file modifications—it is ideal for ad-hoc development tasks. The **SDK** (`npm install @codebuff/sdk`) exposes the `CodebuffClient` class for embedding AI capabilities directly into applications, supporting custom toolchains, automated testing, and CI/CD workflows where programmatic control is required.