Configuration

Codebuff can be configured using a codebuff.json file in your project root. This file allows you to customize various aspects of how codebuff operates in your project.

Why configure codebuff?

Configuring codebuff helps you create a seamless development environment where codebuff becomes your central development hub. Instead of juggling multiple terminal windows and manually starting various services, you can let codebuff manage your entire development workflow.

Startup Processes

You can configure startup processes, which will run in the background every time codebuff starts! When you use this feature, codebuff will automatically:

Start your development processes:
- Servers (frontend, backend, etc.)
- Launch your database
- Run any other necessary background services
Manage all these processes for you
Read the logs and outputs and automatically handle any errors that arise

This means you can start your day with a single codebuff command, write code with codebuff's assistance, and when you're done, closing codebuff will cleanly shut down all your development processes. No more scattered terminal windows or forgotten running processes!

Configuration Schema

The configuration file follows this structure:

json

{
  "description": "Defines the overall Codebuff configuration file (e.g., codebuff.json). This schema defines the top-level structure of the configuration. This schema can be found at https://www.codebuff.com/config",
  "type": "object",
  "properties": {
    "description": {
      "description": "Does nothing. Put any thing you want here!"
    },
    "startupProcesses": {
      "description": "An array of startup processes.",
      "type": "array",
      "items": {
        "description": "Defines a single startup process.",
        "type": "object",
        "properties": {
          "name": {
            "description": "A user-friendly name for the process. Should be one word and unique.",
            "type": "string",
            "minLength": 1
          },
          "command": {
            "description": "The actual shell command to execute.",
            "type": "string",
            "minLength": 1
          },
          "cwd": {
            "description": "The working directory from which to run the command.",
            "type": "string"
          },
          "enabled": {
            "description": "Whether this process should be run",
            "default": true,
            "type": "boolean"
          },
          "stdoutFile": {
            "description": "Path to write the process's stdout. If not specified, stderr is not stored.",
            "type": "string"
          },
          "stderrFile": {
            "description": "Path to write the process's stderr. If not specified, stderr will be put into the stdoutFile.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "command"
        ]
      }
    },
    "fileChangeHooks": {
      "description": "An array of commands to run on file changes.",
      "type": "array",
      "items": {
        "description": "Defines a single file change hook.",
        "type": "object",
        "properties": {
          "name": {
            "description": "A user-friendly name for the hook. Should be one word and unique.",
            "type": "string",
            "minLength": 1
          },
          "command": {
            "description": "The actual shell command to execute.",
            "type": "string",
            "minLength": 1
          },
          "cwd": {
            "description": "The working directory from which to run the command.",
            "type": "string"
          },
          "filePattern": {
            "description": "Glob pattern to match files.",
            "type": "string"
          },
          "enabled": {
            "description": "Whether this command should be run",
            "default": true,
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "command"
        ]
      }
    },
    "maxAgentSteps": {
      "description": "Maximum number of turns agent will take before being forced to end",
      "default": 25,
      "type": "number"
    },
    "baseAgent": {
      "description": "Specify default base agent",
      "type": "string"
    },
    "addedSpawnableAgents": {
      "description": "Specify additional agents that the base agent can spawn",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "removedSpawnableAgents": {
      "description": "Specify which agents the base agent cannot spawn",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "spawnableAgents": {
      "description": "Specify complete list of spawnable agents for the base agent",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "additionalProperties": {}
}

Example Configuration

Here's an example configuration file that starts a development server and database:

json

{
"description": "Development environment configuration",
"startupProcesses": [
{
"name": "nextjs-server",
"command": "npm run dev",
"cwd": "./web",
"enabled": true
},
{
"name": "database",
"command": "docker-compose up",
"cwd": "./backend/db",
"stdoutFile": "logs/db-stdout.log",
"stderrFile": "logs/db-stderr.log"
}
]
}

Best Practices

Process Names: Use descriptive names that clearly indicate what each process does.
Working Directories: Use relative paths for cwd to maintain portability.
Logging: Consider using stdoutFile and stderrFile for important processes to help with debugging.
Process Management: Use the enabled flag to temporarily disable processes without removing them from the configuration.

Troubleshooting

If your startup processes aren't working as expected:

Check that the commands work when run manually from the specified working directory
Verify that any referenced paths (for logs or cwd) exist and are writable
Check the process output in the specified log files if you've configured them
Make sure the JSON syntax in your configuration file is valid

Need more help? Check out our Troubleshooting guide or join our Discord community.