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

> Learn to configure Freebuff settings using CLI, agents, and MCP setup. Master Freebuff configuration with our easy-to-follow guide.

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

---

**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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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:

```typescript
// 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`](https://github.com/CodebuffAI/freebuff/blob/main/cli.json) inside the configuration directory. The CLI reads this file at startup via [`cli/src/utils/create-run-config.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/create-run-config.ts) to determine UI themes, logging levels, and feature flags.

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

```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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/my-assistant.agent.json))
3. Optionally add an [`mcp.json`](https://github.com/CodebuffAI/freebuff/blob/main/mcp.json) file for model credentials (see next section)

Example agent definition following the schema in [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/agent-definition.ts):

```json
{
  "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`](https://github.com/CodebuffAI/freebuff/blob/main/load-mcp-config.ts) module handles loading and environment variable interpolation:

```json
{
  "$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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/tools.ts).

Example tool definition:

```json
{
  "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`](https://github.com/CodebuffAI/freebuff/blob/main/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:

```bash

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

```typescript
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:**

```typescript
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:**

```typescript
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`](https://github.com/CodebuffAI/freebuff/blob/main/cli.json) file controls UI themes, log levels, and feature flags as processed by [`cli/src/utils/create-run-config.ts`](https://github.com/CodebuffAI/freebuff/blob/main/cli/src/utils/create-run-config.ts).
- Agent definitions follow the schema in [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/freebuff/blob/main/agents/types/agent-definition.ts) and are auto-discovered by [`sdk/src/agents/load-agents.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/agents/load-agents.ts).
- MCP credentials in [`mcp.json`](https://github.com/CodebuffAI/freebuff/blob/main/mcp.json) support environment variable interpolation via `resolveMcpEnv` in [`sdk/src/agents/load-mcp-config.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/src/agents/load-mcp-config.ts).
- Custom tools require JSON schema definitions in `.agents/tools/` matching [`agents/types/tools.ts`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/.agent.json). Define the agent's `id`, `model`, `systemPrompt`, and `tools` array according to the schema in [`agents/types/agent-definition.ts`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/mcp.json) using the `$` prefix (e.g., `"apiKey": "$OPENAI_API_KEY"`). The [`load-mcp-config.ts`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/config-dir.ts) utility checks this variable before defaulting to `~/.config/freebuff/`, making it ideal for CI pipelines, Docker containers, or multi-user systems.