Freebuff Example Configurations: A Complete Guide to Starter Templates

Freebuff ships with ready-made example configurations in common/src/templates/initial-agents-dir/ that demonstrate agent definitions, MCP server schemas, and TypeScript tooling, automatically bootstrapped into your .agents directory when you run freebuff init.

The CodebuffAI/freebuff repository contains comprehensive starter templates that illustrate how to structure a functional agent workspace. These examples cover everything from basic agent definitions to MCP server integration, providing a runnable baseline for building custom AI agents. By examining these templates, you can understand the required file layout, type definitions, and JSON schemas without starting from scratch.

Where to Find Freebuff Example Configurations

The repository organizes example configurations across several key directories, each demonstrating different aspects of the framework.

Initial Agents Template

The primary example lives in common/src/templates/initial-agents-dir/ and contains a complete starter set including agents like diff-reviewer, file-picker, and researcher. This template demonstrates the required directory structure with .agents/types and .agents/examples subdirectories, along with agent-config.d.ts and tools.d.ts type definitions.

According to the source code, the README at common/src/templates/initial-agents-dir/README.md explains the folder layout and lists each starter agent, while common/src/templates/initial-agents-dir/skills/example-skill/SKILL.md provides a minimal skill implementation showing the required run function structure.

MCP Configuration Schema

For Model Context Protocol setup, freebuff/SPEC.md contains the complete JSON schema description and concrete examples. When you run freebuff init, the CLI generates an .agents/mcp.json file based on these specifications, demonstrating environment variable interpolation and required fields like command, env, and stdin.

CLI Release Configuration

The freebuff/cli/release/package.json file provides a concrete example of how to package an agent for distribution. This template includes the required version, description, and entry-point definitions used by the freebuff cli release command.

E2E Test Configuration

For full-stack testing examples, freebuff/e2e/README.md sketches a complete test environment showing how a sample .agents folder is laid out for end-to-end validation from agent definition through tool execution.

Understanding the Initial Agents Directory Structure

The starter template uses a strict directory hierarchy that the CLI expects when loading agents. The structure includes:

• .agents/types/ – Contains TypeScript definition files (agent-config.d.ts, tools.d.ts) that provide intellisense for agent development
• .agents/examples/ – Houses the starter agent implementations including the diff-reviewer and file-picker examples
• skills/ – Contains individual skill definitions with their own SKILL.md documentation files

When you first execute freebuff in a project, the CLI auto-generates these sub-folders and copies the example agents from common/src/templates/initial-agents-dir/ into your local workspace.

MCP Server Configuration Example

The MCP configuration follows a specific JSON schema defined in freebuff/SPEC.md. Below is the minimal mcp.json structure generated by the CLI:

{
  "mcpServers": {
    "localTool": {
      "command": "node",
      "args": ["scripts/run-tool.js"],
      "env": {
        "TOOL_PATH": "$HOME/.local/tool"
      }
    }
  }
}

This example demonstrates environment variable interpolation using $HOME and shows the required fields: command specifies the executable, args provides arguments as an array, and env sets environment variables for the server context.

Creating Custom Agents from Examples

The starter agents provide TypeScript templates that you can copy and modify. Here is the diff-reviewer agent found at .agents/examples/diff-reviewer.ts in the template:

import { createPlan, runTerminalCommand, setOutput } from '@codebuff/sdk';

export const diffReviewer = {
  name: 'diffReviewer',
  description: 'Shows a diff and asks the user to approve it.',
  async run(context) {
    const plan = await createPlan('Run git diff');
    const diff = await runTerminalCommand('git diff');
    await setOutput(diff);
  }
};

This example illustrates the required agent structure: a named export containing name, description, and an async run function that receives a context object. The implementation uses SDK functions like createPlan, runTerminalCommand, and setOutput to interact with the system.

Bootstrapping Your Workspace with Examples

To utilize the freebuff example configurations in your own project:

1. Initialize the workspace – Run freebuff in your project root to auto-generate the .agents directory and copy the starter templates from common/src/templates/initial-agents-dir/

2. Configure MCP servers – Edit the generated .agents/mcp.json file, adjusting the commands and environment variables according to the schema documented in freebuff/SPEC.md

3. Customize agents – Copy any example agent from .agents/examples/ (such as the diff-reviewer) and modify the TypeScript code; the associated type definitions in .agents/types/ are already configured for intellisense

Because these examples are validated against the CLI's expectations, they provide a guaranteed runnable baseline that adheres to the framework's requirements.

Summary

• Freebuff example configurations are located in common/src/templates/initial-agents-dir/ within the CodebuffAI/freebuff repository
• The initial agents template provides starter agents (diff-reviewer, file-picker, researcher) with complete TypeScript type definitions
• MCP server configuration follows the JSON schema defined in freebuff/SPEC.md, supporting environment variable interpolation
• The CLI release configuration at freebuff/cli/release/package.json demonstrates how to package agents for distribution
• Running freebuff init automatically copies these templates into your local .agents directory with proper structure and examples

Frequently Asked Questions

Where are the freebuff example configurations located in the repository?

The main example configurations reside in common/src/templates/initial-agents-dir/ according to the CodebuffAI/freebuff source code. Additional examples include the MCP schema in freebuff/SPEC.md, the release configuration in freebuff/cli/release/package.json, and end-to-end test setups in freebuff/e2e/README.md.

How do I initialize the example agents in my own project?

Run the freebuff command in your project root (or explicitly freebuff init) to automatically create the .agents directory and copy the starter templates from common/src/templates/initial-agents-dir/. This bootstraps the required folder structure, type definitions, and example agents into your workspace.

What is the structure of an MCP server configuration in Freebuff?

The MCP configuration uses a JSON format with a top-level mcpServers object containing server definitions. Each server requires a command field (the executable), an optional args array for arguments, and an optional env object for environment variables. The schema supports variable interpolation like $HOME and is fully documented in freebuff/SPEC.md.

How do I customize the starter agents for my own use?

Copy any TypeScript agent file from .agents/examples/ (such as diff-reviewer.ts) and modify the run function implementation. The existing type definitions in .agents/types/agent-config.d.ts and .agents/types/tools.d.ts provide full TypeScript support, and you can reference the skill example at common/src/templates/initial-agents-dir/skills/example-skill/SKILL.md for implementation patterns.

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