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

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:

# 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 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. 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:

npm install @codebuff/sdk

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

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 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 or 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 documents the command-line interface that wraps the SDK client and handles terminal output.
• SDK Client: sdk/README.md defines the CodebuffClient class and the loadLocalAgents helper for programmatic integration.
• Agent Runtime: 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 and AGENTS.md is documented in the Knowledge Files section of sdk/README.md.
• File Filtering: Security policies excluding files like .env are implemented in the File Filtering section of 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 or 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, sdk/README.md, and 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. 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.

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