.codebuddy Directory Structure

A deep dive into the files and subdirectories under CodeBuddy Code's configuration directory ~/.codebuddy and the project-level .codebuddy directory.

CodeBuddy Code uses two configuration directories:

• Global directory ~/.codebuddy/: stores user-level configuration, history, runtime data, etc., affecting all projects
• Project directory .codebuddy/ (located at the project root): stores project-level configuration, rules, skills, commands, etc., shared with the team via version control

---

Global Directory ~/.codebuddy/

~/.codebuddy/
├── settings.json              # User-level global configuration
├── settings.local.json        # Local personal preferences (not shared)
├── CODEBUDDY.md               # User-level memory file
├── mcp.json                   # Global MCP server configuration
├── statusline-command.sh      # Custom status line script (optional)
│
├── agents/                    # User-level custom sub-agents (available to all projects)
├── rules/                     # User-level rule files (available to all projects)
├── skills/                    # User-level skills (available to all projects)
│
├── projects/                  # Per-project session and sub-agent runtime data
├── sessions/                  # Session data
├── plans/                     # Plans generated in plan mode
│
├── logs/                      # Runtime logs
├── traces/                    # Execution trace data (OpenTelemetry)
├── file-history/              # File change history
├── history.jsonl              # Conversation history
├── blobs/                     # Binary assets (images, screenshots, etc.)
├── tasks/                     # Task tracking data
├── teams/                     # Agent team runtime data
├── shell-snapshots/           # Bash sandbox snapshots
│
├── plugins/                   # Installed plugins
├── local_storage/             # CLI key-value persistent storage
├── channels/                  # Channel configuration (WeChat, etc.)
│
├── computer-use/              # Computer Use feature records
├── debug/                     # Debug information
└── usage-data/                # Usage statistics

Core Configuration Files

settings.json

User-level global configuration that applies to all projects. Manage it via the /config command or by editing it directly.

{
  "language": "English",
  "model": "gpt-5",
  "reasoningEffort": "high",
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(git:*)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "memory": {
    "autoMemoryEnabled": true,
    "typedMemory": true
  },
  "trustedDirectories": ["~/workspace/myproject"]
}

For the full list of configuration fields, see Settings.

settings.local.json

Local personal configuration. CodeBuddy Code does not auto-sync or share this file; it is suitable for storing overrides that only apply to the local machine (such as API keys, debug toggles, etc.).

CODEBUDDY.md

User-level memory file that takes effect across all projects. Suitable for personal coding preferences, common workflow notes, etc.

## Tool Preferences
- Use pnpm instead of npm
- Prefer functional programming style

## Code Style
- Use 2-space indentation

See Memory Management for details.

mcp.json

Global MCP server configuration. Same format as the project-level .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

See MCP Documentation for details.

---

User-Level Extension Directories

agents/

Stores user-level custom sub-agents that take effect across all projects. Each agent is a single .md file:

~/.codebuddy/agents/
├── code-reviewer.md      # Code review agent
└── translator.md         # Translation agent

File format (YAML frontmatter + system prompt):

---
name: code-reviewer
description: Code review expert; use proactively after writing code
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer focused on code quality, security, and best practices...

See Sub-Agent Documentation for details.

rules/

Stores user-level rule files that take effect across all projects. All .md files are loaded automatically; subdirectories are supported:

~/.codebuddy/rules/
├── preferences.md        # Personal coding preferences
└── workflows.md          # Common workflow conventions

Rule files support frontmatter to control loading behavior:

---
alwaysApply: false
paths: src/**/*.ts
---

# TypeScript Conventions

- Prefer `interface` over `type`
- Disallow `any`

See Memory Management - Rule System for details.

skills/

Stores user-level skills that take effect across all projects. Each skill is a self-contained directory containing a SKILL.md:

~/.codebuddy/skills/
└── pdf/
    └── SKILL.md

See Skills Documentation for details.

---

Runtime Data Directories

These directories are maintained automatically by CodeBuddy Code and typically do not require manual operation:

Directory	Description
projects/	Per-project runtime data, including session records (.jsonl) and sub-agent tool output (tool-results/)
sessions/	Active session data
plans/	Plan files generated in plan mode
logs/	Runtime logs grouped by date and process
traces/	OpenTelemetry execution trace data
file-history/	Snapshots of files operated on within each session, used by /rewind
history.jsonl	Global conversation history (used by /resume)
blobs/	Binary resources such as images and screenshots, stored by content hash
tasks/	Task management system data (TaskCreate/TaskUpdate)
teams/	Agent team (TeamCreate) runtime data
shell-snapshots/	Bash sandbox startup snapshots that speed up sandbox creation
plugins/	File contents of installed plugins
local_storage/	CLI internal key-value persistent storage (.info files named by content hash)

---

Project Directory .codebuddy/

Located at the project root and intended to be committed to version control so the team can share it:

.codebuddy/
├── settings.json              # Project shared configuration
├── settings.local.json        # Local personal configuration (auto-ignored by .gitignore)
├── CODEBUDDY.md               # Project-level memory file
│
├── agents/                    # Project-level custom sub-agents
├── rules/                     # Project-level rule files
├── skills/                    # Project-level skills
├── commands/                  # Custom slash commands

Configuration Files

settings.json

Project shared configuration synced with the team via version control. Suitable for setting team-wide model, permission rules, plugins, and so on:

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash(git:*)", "Bash(npm:*)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  },
  "enabledPlugins": {
    "pr-review-toolkit@company-tools": true
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "myorg/codebuddy-plugins"
      }
    }
  }
}

settings.local.json

Local personal configuration. CodeBuddy Code automatically adds it to .gitignore. Suitable for personal overrides (such as local debug ports or personal keys) that should not affect other team members.

CODEBUDDY.md

Project-level memory file shared via version control. Stores team knowledge such as project architecture, conventions, and common commands:

# Project Overview

This project is a TypeScript monorepo (Yarn workspaces).

## Common Commands

- `yarn build` — build all packages
- `yarn test` — run all tests

## Architectural Conventions

- Uses the CellJS dependency injection framework
- Protocol definitions live in `*-protocol.ts` files

Tip: You can also place the memory file at the project root as CODEBUDDY.md (outside the .codebuddy/ directory). Both locations are equivalent.

---

Project-Level Extension Directories

agents/

Stores project-specific sub-agents, which take precedence over user-level agents. When names collide, the project-level agent overrides the user-level one.

.codebuddy/agents/
├── blog-translator.md     # Blog translation agent
└── docs-reviewer.md       # Documentation review agent

rules/

Stores project-level rules shared via version control. Suitable for team-wide code conventions, workflow agreements, etc. Subdirectories are supported:

.codebuddy/rules/
├── code-style.md          # Code style conventions
├── testing.md             # Testing conventions
├── security.md            # Security requirements
└── frontend/
    ├── react.md           # React component conventions
    └── styles.md          # Styling conventions

All .md files are recursively loaded automatically.

skills/

Stores project-level skills. Each skill is its own directory containing a SKILL.md and optional supporting files:

.codebuddy/skills/
├── case-executor/
│   ├── SKILL.md           # Skill definition
│   ├── scripts/           # Helper scripts
│   └── references/        # Reference materials
└── cnb-api/
    └── SKILL.md

SKILL.md format:

---
name: case-executor
description: Executes JSON test cases and generates reports
allowed-tools: Read, Write, Bash
---

You are a test execution expert responsible for running UI test cases in JSON format...

See Skills Documentation for details.

commands/

Stores custom slash commands invoked via /command-name. Nested directories are supported (invoked using /group:command):

.codebuddy/commands/
├── deploy.md              # /deploy command
├── team/
│   ├── issue-start.md     # /team:issue-start command
│   └── create-issue.md    # /team:create-issue command
└── openspec/
    └── propose.md         # /openspec:propose command

Command file format:

---
description: Create a new Issue
argument-hint: "<description> ; <type> ; <product>"
allowed-tools: Bash
---

Create an Issue based on the following description: $ARGUMENTS

See Slash Command Documentation for details.

---

Configuration Priority

Multi-layer configuration is applied with the following priority (higher priority overrides lower priority):

Command-line arguments              (highest priority)
    ↓
.codebuddy/settings.local.json    (project local, not committed)
    ↓
.codebuddy/settings.json          (project shared, team-wide)
    ↓
~/.codebuddy/settings.json        (user global, personal preferences)
    ↓
Built-in product defaults           (lowest priority)

Priority for agents/skills/rules: project-level > user-level > plugin-level. When names collide, the project level wins.

Memory Loading Order

1. User-level memory: ~/.codebuddy/CODEBUDDY.md
2. User-level rules: ~/.codebuddy/rules/*.md (recursive)
3. Project-level memory: CODEBUDDY.md (searched recursively upward from cwd)
4. Project-level rules: .codebuddy/rules/*.md (cwd only, no upward search)
5. Project local memory: CODEBUDDY.local.md
6. Subdirectory memory: dynamically loaded `CODEBUDDY.md` from a subdirectory when tools operate on files there

Version Control Recommendations

File / Directory	Commit to VCS	Notes
.codebuddy/settings.json	✅ Recommended	Team shared configuration
.codebuddy/settings.local.json	❌ Do not commit	Auto-added to .gitignore
CODEBUDDY.md / .codebuddy/CODEBUDDY.md	✅ Recommended	Team shared knowledge
CODEBUDDY.local.md	❌ Do not commit	Auto-added to .gitignore
.codebuddy/agents/	✅ Recommended	Team shared sub-agents
.codebuddy/rules/	✅ Recommended	Team shared rules
.codebuddy/skills/	✅ Recommended	Team shared skills
.codebuddy/commands/	✅ Recommended	Team shared commands

Related Resources

• Settings — Complete configuration field reference
• Memory Management — Detailed guide to CODEBUDDY.md and the rule system
• Sub-Agents — Create and use custom sub-agents
• Skills Documentation — In-depth guide to the skill system
• Slash Commands — Custom command reference
• MCP Documentation — MCP server configuration

---

Use the .codebuddy directory wisely to help CodeBuddy Code better understand your project and team conventions.