How to Configure Freebuff Settings: CLI, Agents, and MCP Setup

Configure Freebuff by creating JSON files in ~/.config/freebuff/ for global CLI preferences and .agents/ folders in your projects for agent definitions, with MCP credentials stored in mcp.json using environment variable references.

Freebuff’s configuration system in the CodebuffAI/freebuff repository uses a portable, file-based approach that separates user preferences from agent logic. All settings are defined through JSON files located in a central configuration directory or project-specific folders, allowing you to customize the CLI, SDK, and custom agents without touching the source code.

Configuration Directory Structure

Freebuff resolves its configuration directory at runtime using the logic in cli/src/utils/config-dir.ts. By default, it uses ~/.config/freebuff/, but you can override this with the FREEBUFF_CONFIG_DIR environment variable.

The resolution logic follows this priority:

// From cli/src/utils/config-dir.ts
const home = process.env.HOME ?? os.homedir();
const configDir = path.join(home, '.config', 'freebuff');

if (process.env.FREEBUFF_CONFIG_DIR) {
  return process.env.FREEBUFF_CONFIG_DIR;
}
return configDir;

If configuration files are missing, Freebuff falls back to sensible defaults such as built-in light themes and empty agent registries.

Customizing the CLI with cli.json

Global CLI behavior is controlled by cli.json inside the configuration directory. The CLI reads this file at startup via cli/src/utils/create-run-config.ts to determine UI themes, logging levels, and feature flags.

Create or edit ~/.config/freebuff/cli.json:

{
  "theme": "dark",
  "logLevel": "info",
  "binaryPath": "/usr/local/bin/freebuff",
  "featureFlags": {
    "enableTelemetry": false,
    "useExperimentalRenderer": true
  }
}

• theme: Accepts "light" or "dark"
• logLevel: Options are "error", "warn", "info", or "debug"
• binaryPath: Optional custom location for the Freebuff binary
• featureFlags: Toggle experimental capabilities and telemetry

Changes take effect immediately upon restarting the CLI.

Defining Agents in Project Directories

Agents are defined in .agents/ folders located at the root or any subdirectory of your project. Freebuff automatically discovers these directories by walking the project tree, as implemented in sdk/src/agents/load-agents.ts.

To create an agent:

1. Create a .agents folder in your project root
2. Add an agent definition file (e.g., my-assistant.agent.json)
3. Optionally add an mcp.json file for model credentials (see next section)

Example agent definition following the schema in agents/types/agent-definition.ts:

{
  "id": "my-assistant",
  "model": "gpt-4o-mini",
  "systemPrompt": "You are a helpful coding assistant.",
  "tools": ["search-files", "run-command"],
  "maxTokens": 4096,
  "temperature": 0.2,
  "description": "An agent tuned for quick code look-ups."
}

Agents become selectable via the CLI's --agent <id> flag or programmatically through the SDK.

Configuring MCP Connections

Model-Control-Plane (MCP) settings manage API endpoints and authentication for LLM providers. Store these in <project>/.agents/mcp.json to keep credentials out of your repository.

The load-mcp-config.ts module handles loading and environment variable interpolation:

{
  "$schema": "https://codebuff.ai/schemas/mcp.json",
  "mcpServers": {
    "openrouter": {
      "type": "http",
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "$OPENROUTER_API_KEY"
    },
    "anthropic": {
      "type": "http",
      "baseUrl": "https://api.anthropic.com",
      "apiKey": "$ANTHROPIC_API_KEY"
    }
  }
}

Values prefixed with $ are expanded from the process environment via the resolveMcpEnv function in sdk/src/agents/load-mcp-config.ts. This ensures secrets remain in environment variables while agents retain access to necessary endpoints.

Registering Custom Tools

Custom tools extend agent capabilities beyond the built-in set. Define tools in <project>/.agents/tools/*.json following the schema in agents/types/tools.ts.

Example tool definition:

{
  "id": "deploy-to-staging",
  "description": "Deploy the current repo to the staging environment.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "branch": { "type": "string", "default": "main" }
    },
    "required": []
  }
}

Agents that list this tool in their tools array can invoke it via the SDK's runTool API. The actual implementation resides in the CLI's tool handlers within packages/agent-runtime/src/tools/handlers/.

Overriding Settings with Environment Variables

All configuration files are optional; you can modify behavior at runtime using environment variables. These are read early in the startup sequence in cli/src/utils/config-dir.ts:

• FREEBUFF_CONFIG_DIR: Forces Freebuff to read CLI config from a non-standard path
• FREEBUFF_MODE: Enables debug mode with verbose logs and disabled telemetry when set to "true"
• FREEBUFF_BINARY: Overrides the binary path used by the SDK when spawning subprocesses
• FREEBUFF_INSTANCE_ID: Manually sets the freebuff_instance_id header for server-side session tracking

Quick Setup Guide

Initialize a complete Freebuff configuration from scratch:

# 1. Create the global config directory

mkdir -p ~/.config/freebuff

# 2. Write CLI preferences

cat > ~/.config/freebuff/cli.json <<'EOF'
{
  "theme": "dark",
  "logLevel": "debug",
  "featureFlags": { "enableTelemetry": false }
}
EOF

# 3. Create a project-specific agent

mkdir -p my-project/.agents
cat > my-project/.agents/coder.agent.json <<'EOF'
{
  "id": "project-coder",
  "model": "gpt-4o-mini",
  "systemPrompt": "You are an expert TypeScript developer.",
  "tools": ["search-files", "run-command"]
}
EOF

# 4. Configure MCP with environment references

cat > my-project/.agents/mcp.json <<'EOF'
{
  "mcpServers": {
    "openai": {
      "type": "http",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "$OPENAI_API_KEY"
    }
  }
}
EOF

# 5. Set your API key

export OPENAI_API_KEY=sk-...

Restart the Freebuff CLI to apply these settings immediately.

Accessing Configuration Programmatically

Load configuration directly in your TypeScript applications using SDK utilities:

Resolving the config directory:

import { resolveConfigDir } from '@codebuff/cli/utils/config-dir';
import { readFileSync } from 'fs';

const cfgPath = `${resolveConfigDir()}/cli.json`;
const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
console.log('Current theme:', cfg.theme);

Loading project agents:

import { loadAgents } from '@codebuff/sdk';

(async () => {
  const agents = await loadAgents({ cwd: './my-project' });
  const coder = agents.find(a => a.id === 'project-coder');
  console.log('Loaded agent:', coder);
})();

Executing custom tools:

import { runTool } from '@codebuff/sdk';

await runTool('deploy-to-staging', { branch: 'feature-x' });

Summary

• Freebuff stores global settings in ~/.config/freebuff/ and project-specific agents in .agents/ folders.
• The cli.json file controls UI themes, log levels, and feature flags as processed by cli/src/utils/create-run-config.ts.
• Agent definitions follow the schema in agents/types/agent-definition.ts and are auto-discovered by sdk/src/agents/load-agents.ts.
• MCP credentials in mcp.json support environment variable interpolation via resolveMcpEnv in sdk/src/agents/load-mcp-config.ts.
• Custom tools require JSON schema definitions in .agents/tools/ matching agents/types/tools.ts.
• Environment variables like FREEBUFF_CONFIG_DIR override file-based configuration for CI/CD environments.

Frequently Asked Questions

Where does Freebuff store its configuration files?

Freebuff stores global configuration in ~/.config/freebuff/ by default, determined by the config-dir.ts module. Project-specific agents and tools reside in .agents/ folders within your repository. You can override the global path by setting the FREEBUFF_CONFIG_DIR environment variable.

How do I add a custom agent to Freebuff?

Create a .agents folder in your project root and add a JSON file ending in .agent.json. Define the agent's id, model, systemPrompt, and tools array according to the schema in agents/types/agent-definition.ts. Freebuff automatically discovers these files when scanning the project directory tree.

How do I keep API keys secure when configuring Freebuff?

Store API keys in environment variables, then reference them in mcp.json using the $ prefix (e.g., "apiKey": "$OPENAI_API_KEY"). The load-mcp-config.ts module expands these variables at runtime, ensuring credentials never appear in your repository files while remaining accessible to agents.

Can I change the configuration directory without modifying the source code?

Yes. Set the FREEBUFF_CONFIG_DIR environment variable to any absolute path before launching Freebuff. The config-dir.ts utility checks this variable before defaulting to ~/.config/freebuff/, making it ideal for CI pipelines, Docker containers, or multi-user systems.

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