# Freebuff Example Configurations: A Complete Guide to Starter Templates

> Explore Freebuff example configurations for starter templates. Discover agent definitions, MCP server schemas, and TypeScript tooling in our complete guide. Get started with freebuff init.

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

---

**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`](https://github.com/CodebuffAI/freebuff/blob/main/agent-config.d.ts) and [`tools.d.ts`](https://github.com/CodebuffAI/freebuff/blob/main/tools.d.ts) type definitions.

According to the source code, the README at [`common/src/templates/initial-agents-dir/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/SPEC.md) contains the complete JSON schema description and concrete examples. When you run `freebuff init`, the CLI generates an [`.agents/mcp.json`](https://github.com/CodebuffAI/freebuff/blob/main/.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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/agent-config.d.ts), [`tools.d.ts`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/SPEC.md). Below is the minimal [`mcp.json`](https://github.com/CodebuffAI/freebuff/blob/main/mcp.json) structure generated by the CLI:

```json
{
  "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`](https://github.com/CodebuffAI/freebuff/blob/main/.agents/examples/diff-reviewer.ts) in the template:

```typescript
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`](https://github.com/CodebuffAI/freebuff/blob/main/.agents/mcp.json) file, adjusting the commands and environment variables according to the schema documented in [`freebuff/SPEC.md`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/SPEC.md), supporting environment variable interpolation
- The **CLI release configuration** at [`freebuff/cli/release/package.json`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/SPEC.md), the release configuration in [`freebuff/cli/release/package.json`](https://github.com/CodebuffAI/freebuff/blob/main/freebuff/cli/release/package.json), and end-to-end test setups in [`freebuff/e2e/README.md`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/diff-reviewer.ts)) and modify the `run` function implementation. The existing type definitions in [`.agents/types/agent-config.d.ts`](https://github.com/CodebuffAI/freebuff/blob/main/.agents/types/agent-config.d.ts) and [`.agents/types/tools.d.ts`](https://github.com/CodebuffAI/freebuff/blob/main/.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`](https://github.com/CodebuffAI/freebuff/blob/main/common/src/templates/initial-agents-dir/skills/example-skill/SKILL.md) for implementation patterns.