# How to Use inheritParentSystemPrompt in Codebuff: System Prompt Inheritance and Caching

> Learn how to override system prompts with inheritParentSystemPrompt in Codebuff. Reuse parent prompts for caching efficient token use and consistent agent behavior. Discover prompt inheritance basics.

- Repository: [Codebuff/codebuff](https://github.com/CodebuffAI/codebuff)
- Tags: how-to-guide
- Published: 2026-03-09

---

**Enable `inheritParentSystemPrompt` on child agents to reuse the parent's system prompt for prompt caching, reducing token usage while maintaining consistent behavior across agent hierarchies.**

The `inheritParentSystemPrompt` feature in the CodebuffAI/codebuff repository enables sophisticated prompt caching across hierarchical agent structures. This mechanism allows sub-agents to inherit the exact system prompt from their parent, eliminating redundant token consumption and ensuring uniform high-level behavior. Understanding when and how to implement this inheritance pattern is essential for building cost-effective, multi-agent systems.

## What is inheritParentSystemPrompt?

**`inheritParentSystemPrompt`** is a boolean configuration option in the `AgentDefinition` type that instructs a sub-agent to reuse the exact system prompt of its parent agent. Instead of generating or defining a unique system message, the child agent receives the cached parent prompt, enabling **prompt caching** at the runtime level. This is implemented in [`.agents/types/agent-definition.ts`](https://github.com/CodebuffAI/codebuff/blob/main/.agents/types/agent-definition.ts) (lines 84-90), where the property is defined alongside validation rules that prevent conflicts with custom system prompts.

## When to Enable System Prompt Inheritance

Enable `inheritParentSystemPrompt` when you need to optimize token usage and maintain behavioral consistency across agent hierarchies. The following situations warrant its use:

- **You maintain large, stable system prompts.** When the parent agent defines a lengthy system message (e.g., "You are a senior full-stack developer..."), reusing it avoids re-sending identical text for every sub-agent invocation.

- **You require prompt caching for performance.** The runtime sends the parent's system prompt only once in [`packages/agent-runtime/src/run-agent-step.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/run-agent-step.ts), then passes the cached version to all children that inherit it, significantly reducing API costs.

- **The child agent's behavior is tool-driven.** When the sub-agent's functionality is defined primarily by its available tools and `instructionsPrompt` rather than a unique personality or constraints, inheritance keeps the configuration lightweight.

- **You need strict behavioral constraints.** Inheritance prevents accidental divergence; the schema validation in [`common/src/types/dynamic-agent-template.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/types/dynamic-agent-template.ts) (lines 85-98) rejects any non-empty `systemPrompt` when `inheritParentSystemPrompt` is enabled.

## When to Avoid Inheritance

Do not use `inheritParentSystemPrompt` when the child agent requires a **different high-level personality or constraints** than the parent. If the sub-agent needs to override part of the parent's system prompt or operate under distinct behavioral guidelines, define a separate `systemPrompt` instead. Inheritance is inappropriate when you want the child to deviate from the parent's core instructions in any way.

## How It Works Under the Hood

The implementation spans schema validation, runtime execution, and documentation generation.

### Schema Validation

The Zod schema in [`common/src/types/dynamic-agent-template.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/types/dynamic-agent-template.ts) enforces mutual exclusivity between inheritance and custom prompts. When `inheritParentSystemPrompt` is `true`, the validator ensures `systemPrompt` is either missing or empty, throwing an error if both fields are present.

### Runtime Execution

In [`packages/agent-runtime/src/run-agent-step.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/run-agent-step.ts), the runner decides whether to reuse the parent's system prompt and tools. Lines 54-57 determine tool inheritance, while lines 78-81 handle the system prompt:

```typescript
// Decide whether to use the parent's tools for prompt caching
const useParentTools =
  agentTemplate.inheritParentSystemPrompt && parentTools !== undefined

// Build system prompt – reuse parent if inheritance is enabled
let system: string
if (agentTemplate.inheritParentSystemPrompt && parentSystemPrompt) {
  system = parentSystemPrompt
} else {
  const systemPrompt = await getAgentPrompt({ … })
  system = systemPrompt ?? ''
}

```

### Documentation Generation

When rendering agent descriptions for sub-agents, the template in [`packages/agent-runtime/src/templates/prompts.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/templates/prompts.ts) (lines 31-35) automatically appends an indication that the agent is inheriting its system prompt from the parent, ensuring transparency in the agent hierarchy.

## Step-by-Step Implementation

Follow these steps to implement system prompt inheritance in your Codebuff agents.

### Define the Parent Agent

Create the parent agent with a complete `systemPrompt` that establishes the foundational behavior:

```typescript
import { AgentDefinition } from '.agents/types/agent-definition'

export const parent: AgentDefinition = {
  id: 'parent-agent',
  version: '0.1.0',
  displayName: 'Parent Agent',
  model: 'anthropic/claude-sonnet-4.6',
  systemPrompt: `
You are an expert software architect.
- Always write production-grade TypeScript.
- Follow the project's linting rules.
- Keep explanations concise.
`,
  instructionsPrompt: 'Help the user solve coding problems.',
  toolNames: ['read_files', 'write_file', 'spawn_agents'],
  spawnableAgents: ['child-agent'],
}
export default parent

```

### Configure the Child Agent

Define the child agent with `inheritParentSystemPrompt: true` and **omit the `systemPrompt` field**. Use `instructionsPrompt` for child-specific modifications:

```typescript
import { AgentDefinition } from '.agents/types/agent-definition'

export const child: AgentDefinition = {
  id: 'child-agent',
  version: '0.1.0',
  displayName: 'Child Agent',
  model: 'anthropic/claude-sonnet-4.6',
  // Inherit the parent's system prompt – do NOT set systemPrompt
  inheritParentSystemPrompt: true,
  // Child-specific instructions – these are appended after the inherited system prompt
  instructionsPrompt: `
You are a code-review sub-assistant.
- Focus on TypeScript type safety.
- Suggest improvements only when they reduce complexity.
`,
  toolNames: ['read_files', 'write_file'],
}
export default child

```

### Spawn the Child Agent

Use the `spawn_agents` tool within a `handleSteps` generator to instantiate the child. The runtime automatically applies the cached parent system prompt:

```typescript
function* handleSteps({ logger }) {
  logger.info('Spawning child agent')
  yield {
    toolName: 'spawn_agents',
    input: {
      agents: [
        {
          agent_type: 'child-agent',
          // No custom systemPrompt – inheritance is automatic
          input: { /* any child inputs */ },
        },
      ],
    },
  }

  // Continue with parent logic…
}

```

If you need the child to access conversation history, explicitly set `includeMessageHistory: true` in the agent definition. Inheritance does not automatically include message history.

## Validation Errors and Troubleshooting

Attempting to set both `inheritParentSystemPrompt: true` and a custom `systemPrompt` triggers a validation error. The test suite in [`packages/agent-runtime/src/__tests__/prompt-caching-subagents.test.ts`](https://github.com/CodebuffAI/codebuff/blob/main/packages/agent-runtime/src/__tests__/prompt-caching-subagents.test.ts) (lines 329-361) demonstrates this behavior:

```typescript
// This will throw during validation:
const badAgent: AgentDefinition = {
  id: 'bad',
  inheritParentSystemPrompt: true,
  systemPrompt: 'I want a different system prompt', // ❌ invalid
}

```

Running this code produces the error: "Cannot specify both systemPrompt and inheritParentSystemPrompt. When inheritParentSystemPrompt is true, systemPrompt must be empty."

## Summary

- **Enable `inheritParentSystemPrompt`** on child agents to reuse the parent's system prompt and achieve prompt caching.
- **Never set `systemPrompt`** when inheritance is enabled; the schema in [`dynamic-agent-template.ts`](https://github.com/CodebuffAI/codebuff/blob/main/dynamic-agent-template.ts) enforces this constraint.
- **Use `instructionsPrompt`** to provide child-specific behavioral modifications without breaking inheritance.
- **Enable `includeMessageHistory` separately** if the child requires access to conversation context.
- **Reference the source files**: [`.agents/types/agent-definition.ts`](https://github.com/CodebuffAI/codebuff/blob/main/.agents/types/agent-definition.ts) for type definitions, [`run-agent-step.ts`](https://github.com/CodebuffAI/codebuff/blob/main/run-agent-step.ts) for runtime logic, and [`prompt-caching-subagents.test.ts`](https://github.com/CodebuffAI/codebuff/blob/main/prompt-caching-subagents.test.ts) for validation examples.

## Frequently Asked Questions

### Can I set a custom systemPrompt when inheritParentSystemPrompt is true?

No. The Zod schema validator in [`common/src/types/dynamic-agent-template.ts`](https://github.com/CodebuffAI/codebuff/blob/main/common/src/types/dynamic-agent-template.ts) explicitly forbids this combination. When `inheritParentSystemPrompt` is enabled, the `systemPrompt` field must be empty or omitted entirely. Attempting to set both will result in a schema validation error before the agent runs.

### Does inheritance include message history?

No. The `inheritParentSystemPrompt` flag controls only the system prompt inheritance. If you need the child agent to view the conversation history from the parent, you must separately enable `includeMessageHistory: true` in the agent definition. These are distinct configuration options with separate behaviors.

### How does this improve performance?

By reusing the parent's system prompt, Codebuff avoids re-sending identical system text for every sub-agent invocation. This **prompt caching** reduces token consumption significantly when spawning multiple children, as the runtime sends the system prompt only once and references the cached version for subsequent inherited agents.

### What happens if the parent changes its system prompt?

Child agents inherit the parent's system prompt at runtime when spawned. If the parent's `systemPrompt` is modified, subsequent spawns of the child agent will receive the updated system prompt automatically. However, already-running child agents retain the system prompt they received at initialization.