.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.

json

{
  "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.

markdown

## 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:

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):

markdown

---
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:

markdown

---
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:

json

{
  "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:

markdown

# 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:

markdown

---
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:

markdown

---
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

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.

.codebuddy Directory Structure ​

Global Directory ~/.codebuddy/ ​

Core Configuration Files ​

settings.json ​

settings.local.json ​

CODEBUDDY.md ​

mcp.json ​

User-Level Extension Directories ​

agents/ ​

rules/ ​

skills/ ​

Runtime Data Directories ​

Project Directory .codebuddy/ ​

Configuration Files ​

settings.json ​

settings.local.json ​

CODEBUDDY.md ​

Project-Level Extension Directories ​

agents/ ​

rules/ ​

skills/ ​

commands/ ​

Configuration Priority ​

Memory Loading Order ​

Version Control Recommendations ​

Related Resources ​

.codebuddy Directory Structure

Global Directory `~/.codebuddy/`

Core Configuration Files

`settings.json`

`settings.local.json`

`CODEBUDDY.md`

`mcp.json`

User-Level Extension Directories

`agents/`

`rules/`

`skills/`

Runtime Data Directories

Project Directory `.codebuddy/`

Configuration Files

`settings.json`

`settings.local.json`

`CODEBUDDY.md`

Project-Level Extension Directories

`agents/`

`rules/`

`skills/`

`commands/`

Configuration Priority

Memory Loading Order

Version Control Recommendations

Related Resources