codebuddy --agents '{
  "code-reviewer": {
    "description": "Code review expert. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "gemini-3.0-flash"
  }
}'

---
name: your-sub-agent-name
description: Describes when this subagent should be called.
tools: tool1, tool2, tool3  # Optional - If omitted, all tools are inherited.
model: gpt-5.1-codex  # Optional - Specify a model alias or 'inherit'.
permissionMode: default  # Optional - The permission mode for the subagent.
skills: skill1, skill2  # Optional - Skills to load automatically.
---

Write the system prompt for the subagent here. It can contain multiple paragraphs.
Clearly define the subagent's role, capabilities, and approach to solving problems.

Include specific instructions, best practices, and any constraints that the subagent should follow.

---
name: docs-searcher
description: Use the existing docs MCP for search.
tools:
  - Read
mcpServers:
  - docs
---

---
name: browser-checker
description: Use a private MCP for browser inspection.
tools:
  - ToolSearch
  - DeferExecuteTool
mcpServers:
  - browser_private:
      type: stdio
      command: node
      args:
        - /absolute/path/to/browser-mcp-server.js
      defer_loading: true
---

{
  "enabledMcpjsonServers": ["browser_private"]
}

codebuddy --settings '{"enabledMcpjsonServers":["browser_private"]}'

tools:
  - ToolSearch
  - DeferExecuteTool
mcpServers:
  - finance_data:
      type: stdio
      command: node
      args:
        - /absolute/path/to/finance-mcp-server.js

mcpServers:
  - finance_data:
      type: stdio
      command: node
      args:
        - /absolute/path/to/finance-mcp-server.js
      defer_loading: false

/agents

# Create a project subagent
mkdir -p .codebuddy/agents
echo '---
name: test-runner
description: Proactively run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively run the corresponding tests.
If tests fail, analyze the causes and fix them while preserving the original test intent.' > .codebuddy/agents/test-runner.md

# Create a user subagent
mkdir -p ~/.codebuddy/agents
# ... Create the subagent file

> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent check my recent changes.
> Ask the debugger subagent to investigate this error.

User: Find all places that handle authentication and update them to use the new token format.

CodeBuddy Code: [Invoke the general-purpose subagent]
[The agent searches the codebase for authentication-related code.]
[The agent reads and analyzes multiple files.]
[The agent makes the necessary edits.]
[Return a detailed description of the changes made.]

User: [In plan mode] Help me refactor the authentication module.

CodeBuddy Code: Let me first look into your authentication implementation...
[Internally invokes the Plan subagent to explore authentication-related files]
[The Plan subagent searches the codebase and returns findings]
CodeBuddy Code: Based on my research, here is my proposed plan...

User: Where are client errors handled?

CodeBuddy Code: [Invoke the Explore subagent with "medium" thoroughness]
[Explore uses Grep to search for error handling patterns]
[Explore uses Read to inspect potentially relevant files]
[Return findings with absolute file paths]
CodeBuddy Code: Client errors are handled in src/services/process.ts:712...

User: What is the structure of the codebase?

CodeBuddy Code: [Invoke the Explore subagent with "quick" thoroughness]
[Explore uses Glob and ls to map the directory structure]
[Return an overview of key directories and their purposes]

---
name: code-reviewer
description: Code review expert. Proactively review code quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer who ensures high standards of code quality and security.

When invoked:
1. Run git diff to view recent changes
2. Focus on modified files
3. Start the review immediately

Review Checklist:
- Code is clear and readable.
- Functions and variables are well named.
- No duplicate code.
- Proper error handling
- No exposed secrets or API keys.
- Input validation implemented.
- Good test coverage
- Performance issues considered.

Organize feedback by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Contains specific examples of how to fix the issue.

---
name: debugger
description: Debugging expert for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert-level debugger specializing in root cause analysis.

When invoked:
1. Capture error messages and stack traces.
2. Determine the reproduction steps.
3. Isolate the fault location.
4. Implement the minimal fix.
5. Verify that the solution is effective.

Debugging process:
- Analyze error messages and logs.
- Check recent code changes.
- Form and test hypotheses.
- Add strategic debug logs.
- Check the variable status.

For each question, provide the following:
- Root cause explanation.
- Evidence supporting the diagnosis.
- Specific code fixes.
- Test methods.
- Prevention recommendations.

Focus on fixing the root cause rather than just the symptoms.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: gpt-5.1-codex
---

You are a data scientist specializing in SQL and BigQuery analytics.

When invoked:
1. Understand the data analysis requirements.
2. Write efficient SQL queries.
3. Use the BigQuery command-line tool (bq) when appropriate.
4. Analyze and summarize the results.
5. Present findings clearly.

Key Practices:
- Write optimized SQL queries with appropriate filters.
- Use appropriate aggregations and joins.
- Include comments that explain complex logic.
- Format the results to improve readability.
- Provide data-driven recommendations.

For each analysis:
- Explain the query method.
- Document any assumptions.
- Highlight key findings.
- Recommend next steps based on the data.

Always ensure that queries are efficient and cost-effective.

> First, use the code-analyzer subagent to identify performance issues, and then use the optimizer subagent to fix them.

> Start reviewing the authentication module using the code-analyzer agent.

[The agent completes the initial analysis and returns agentId: "abc123"]

> Resume agent abc123 and continue analyzing the authorization logic.

[The agent continues to use the full context of the previous conversation.]

~/.codebuddy/projects/{projectDir}/
  └── {parentSessionId}/
      ├── tool-results/                          ← Tool output files for the main session
      └── subagents/                             ← Subagent data
          ├── agent-{agentId}.jsonl              ← Subagent conversation history
          └── agent-{agentId}/
              └── tool-results/                  ← Tool output files for the subagent
                  └── {callId}.txt

{
  "description": "Continue analysis",
  "prompt": "Now check the error handling pattern",
  "subagent_type": "code-analyzer",
  "resume": "abc123"  // Agent ID from a previous execution
}

> Run the code-analyzer agent in the background to review the entire codebase.

[Task started in the background. Task ID: task-abc123]

**Get background task output:**

Use the `TaskOutput` tool to query the status and results of background tasks:


**Background task status:**

| Status | Description |
| :--- | :--- |
| `pending` | The task has been created and is waiting to be executed. |
| `running` | The task is running. |
| `completed` | The task has been completed successfully. |
| `failed` | The task failed to execute. |
| `cancelled` | The task was cancelled by the user. |
| `killed` | The task was forcibly terminated. |

**Programmatic Usage:**

If you use the Agent SDK or interact with the Agent tool directly, you can pass the `run_in_background` parameter:

```typescript
{
  "description": "Analyze the codebase",
  "prompt": "Review all TypeScript files for potential issues",
  "subagent_type": "code-analyzer",
  "run_in_background": true  // Run in the background
}