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


### 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](sub-agents.md) 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](memory.md#using-codebuddyrules-for-modular-rules) 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](skills.md) 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](skills.md) 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](slash-commands.md) 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](settings.md) — Complete configuration field reference
- [Memory Management](memory.md) — Detailed guide to CODEBUDDY.md and the rule system
- [Sub-Agents](sub-agents.md) — Create and use custom sub-agents
- [Skills Documentation](skills.md) — In-depth guide to the skill system
- [Slash Commands](slash-commands.md) — Custom command reference
- [MCP Documentation](mcp.md) — MCP server configuration

---

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