Optional baseAgent and subagents fields for codebuff.json

Author: jahooma

backend/src/main-prompt.ts

@@ -102,7 +102,7 @@ export const mainPrompt = async (
     }
   }
 
-  // Determine agent type - prioritize CLI agent selection over cost mode
+  // Determine agent type - prioritize CLI agent selection, then config base agent, then cost mode
   let agentType: AgentTemplateType
   const { agentRegistry } = await getAllAgentTemplates({ fileContext })
 
@@ -126,16 +126,36 @@ export const mainPrompt = async (
       `Using CLI-specified agent: ${agentId}`
     )
   } else {
-    // Fall back to cost mode mapping
-    agentType = (
-      {
-        ask: AgentTemplateTypes.ask,
-        lite: AgentTemplateTypes.base_lite,
-        normal: AgentTemplateTypes.base,
-        max: AgentTemplateTypes.base_max,
-        experimental: AgentTemplateTypes.base_experimental,
-      } satisfies Record<CostMode, AgentTemplateType>
-    )[costMode]
+    // Check for base agent in config
+    const configBaseAgent = fileContext.codebuffConfig?.baseAgent
+    if (configBaseAgent) {
+      if (!(configBaseAgent in agentRegistry)) {
+        const availableAgents = Object.keys(agentRegistry)
+        throw new Error(
+          `Invalid base agent in config: "${configBaseAgent}". Available agents: ${availableAgents.join(', ')}`
+        )
+      }
+      agentType = configBaseAgent
+      logger.info(
+        {
+          configBaseAgent,
+          promptParams,
+          prompt: prompt?.slice(0, 50),
+        },
+        `Using config-specified base agent: ${configBaseAgent}`
+      )
+    } else {
+      // Fall back to cost mode mapping
+      agentType = (
+        {
+          ask: AgentTemplateTypes.ask,
+          lite: AgentTemplateTypes.base_lite,
+          normal: AgentTemplateTypes.base,
+          max: AgentTemplateTypes.base_max,
+          experimental: AgentTemplateTypes.base_experimental,
+        } satisfies Record<CostMode, AgentTemplateType>
+      )[costMode]
+    }
   }
 
   mainAgentState.agentType = agentType

backend/src/templates/agent-registry.ts

@@ -35,14 +35,20 @@ export async function getAllAgentTemplates({
     'claude4_gemini_thinking',
     'ask',
   ]
+
+  const configuredBaseAgent = fileContext.codebuffConfig?.baseAgent
+  const configuredSubagents = fileContext.codebuffConfig?.subagents
+
   for (const baseType of baseAgentTypes) {
-    if (agentRegistry[baseType]) {
+    if (agentRegistry[baseType] || baseType === configuredBaseAgent) {
       const baseTemplate = agentRegistry[baseType]
-      // Add user-defined agents to the base agent's subagents list
-      const updatedSubagents = [
+
+      // Use configured subagents list if present, otherwise use the base agent's subagents list plus user-defined agents
+      const updatedSubagents = configuredSubagents ?? [
         ...baseTemplate.subagents,
         ...userDefinedAgentTypes,
       ]
+
       agentRegistry[baseType] = {
         ...baseTemplate,
         subagents: updatedSubagents as any[],

codebuff.json

@@ -1,5 +1,11 @@
 {
   "description": "Template configuration for this project. See https://www.codebuff.com/config for all options.",
+  "baseAgent": "base_lite",
+  "subagents": [
+    "researcher",
+    "thinker",
+    "reviewer"
+  ],
   "startupProcesses": [
     {
       "name": "drizzle",

common/src/json-config/__tests__/__snapshots__/stringify-schema.test.ts.snap

@@ -77,7 +77,16 @@ exports[`stringifySchema should correctly stringify CodebuffConfigSchema 1`] = `
   ] | undefined,
 
   // (optional): Maximum number of turns agent will take before being forced to end, default: 12
-  "maxAgentSteps": number
+  "maxAgentSteps": number,
+
+  // (optional): Specify default base agent
+  "baseAgent": string | undefined,
+
+  // (optional): Specify complete list of subagents for the base agent
+  "subagents": [
+
+  string
+  ] | undefined
 }"
 `;
 

common/src/json-config/constants.ts

@@ -84,6 +84,16 @@ export const CodebuffConfigSchema = z
       .describe(
         'Maximum number of turns agent will take before being forced to end'
       ),
+    baseAgent: z
+      .string()
+      .optional()
+      .describe('Specify default base agent'),
+    subagents: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Specify complete list of subagents for the base agent'
+      ),
   })
   .describe(
     `Defines the overall Codebuff configuration file (e.g., ${codebuffConfigFile}). This schema defines the top-level structure of the configuration. This schema can be found at https://www.codebuff.com/config`

common/src/json-config/default.ts

@@ -6,5 +6,7 @@ export function getDefaultConfig(): CodebuffConfig {
     startupProcesses: [],
     fileChangeHooks: [],
     maxAgentSteps: 12,
+    baseAgent: undefined,
+    subagents: undefined,
   }
 }

common/src/util/file.ts

@@ -3,6 +3,7 @@ import * as os from 'os'
 import * as path from 'path'
 import { z } from 'zod'
 import { DynamicAgentTemplateSchema } from '../types/dynamic-agent-template'
+import { CodebuffConfigSchema } from '../json-config/constants'
 
 export const FileTreeNodeSchema: z.ZodType<FileTreeNode> = z.object({
   name: z.string(),
@@ -47,6 +48,7 @@ export const ProjectFileContextSchema = z.object({
   knowledgeFiles: z.record(z.string(), z.string()),
   userKnowledgeFiles: z.record(z.string(), z.string()).optional(),
   agentTemplates: z.record(z.string(), DynamicAgentTemplateSchema).default({}),
+  codebuffConfig: CodebuffConfigSchema.optional(),
   gitChanges: z.object({
     status: z.string(),
     diff: z.string(),
@@ -92,6 +94,7 @@ export const getStubProjectFileContext = (): ProjectFileContext => ({
   knowledgeFiles: {},
   userKnowledgeFiles: {},
   agentTemplates: {},
+  codebuffConfig: undefined,
   gitChanges: {
     status: '',
     diff: '',

npm-app/src/agents/load-agents.ts

@@ -8,6 +8,7 @@ import * as fs from 'fs'
 import * as path from 'path'
 import { cyan, green } from 'picocolors'
 import { getProjectRoot } from '../project-files'
+import { CodebuffConfig } from '@codebuff/common/json-config/constants'
 
 export let loadedAgents: Record<string, DynamicAgentTemplate> = {}
 
@@ -66,7 +67,9 @@ export async function loadLocalAgents({
         loadedAgents[file.slice(0, -'.ts'.length)] = {
           ...typedAgentConfig,
           systemPrompt: loadFileContents(typedAgentConfig.systemPrompt),
-          instructionsPrompt: loadFileContents(typedAgentConfig.instructionsPrompt),
+          instructionsPrompt: loadFileContents(
+            typedAgentConfig.instructionsPrompt
+          ),
           stepPrompt: loadFileContents(typedAgentConfig.stepPrompt),
 
           handleSteps: handleStepsString,
@@ -89,15 +92,30 @@ export function getLoadedAgentNames(): Record<string, string> {
 /**
  * Display loaded agents to the user
  */
-export function displayLoadedAgents() {
-  if (Object.keys(loadedAgents).length === 0) {
-    return
+export function displayLoadedAgents(codebuffConfig: CodebuffConfig) {
+  const baseAgent = codebuffConfig.baseAgent
+  if (baseAgent) {
+    console.log(`\n${green('Configured base agent:')} ${cyan(baseAgent)}`)
+  }
+
+  const subagents = codebuffConfig.subagents
+  if (subagents) {
+    console.log(
+      `${green('Configured subagents:')} ${subagents
+        .map((name) => cyan(name))
+        .join(', ')}\n`
+    )
+  } else if (Object.keys(loadedAgents).length > 0) {
+    const loadedAgentNames = Object.values(getLoadedAgentNames())
+    console.log(
+      `\n${green('Found custom agents:')} ${loadedAgentNames
+        .map((name) => cyan(name))
+        .join(', ')}\n`
+    )
+  } else if (baseAgent) {
+    // One more new line.
+    console.log()
   }
-  console.log(
-    `\n${green('Found custom agents:')} ${Object.values(getLoadedAgentNames())
-      .map((name) => cyan(name))
-      .join(', ')}\n`
-  )
 }
 
 export function loadFileContents(promptField: PromptField | undefined): string {

npm-app/src/cli.ts

@@ -832,7 +832,6 @@ export class CLI {
       clearScreen()
 
       // from index.ts
-      const config = loadCodebuffConfig()
       await killAllBackgroundProcesses()
       const processStartPromise = logAndHandleStartup()
       const initFileContextPromise = initProjectFileContextWithWorker(

npm-app/src/index.ts

@@ -26,6 +26,7 @@ import { CliOptions } from './types'
 import { initAnalytics, trackEvent } from './utils/analytics'
 import { findGitRoot } from './utils/git'
 import { logger } from './utils/logger'
+import { loadCodebuffConfig } from './json-config/parser'
 
 async function codebuff({
   initialInput,
@@ -74,7 +75,8 @@ async function codebuff({
     print,
     trace,
   })
-  await loadLocalAgents({ verbose: true }).then(() => displayLoadedAgents())
+  const codebuffConfig = loadCodebuffConfig()
+  await loadLocalAgents({ verbose: true }).then(() => displayLoadedAgents(codebuffConfig))
   const cli = CLI.getInstance()
 
   await cli.printInitialPrompt({ initialInput, runInitFlow })