Complete reference for Codi’s configuration system: directory structure, manifest, flags, and MCP.

Directory Structure

.codi/
  codi.yaml                    # Project manifest
  flags.yaml                   # Behavioral flags (16 flags)
  state.json                   # Generation state (auto-managed)
  mcp.yaml                     # MCP server configuration
  rules/                       # All rules (managed_by: codi or user)
  skills/
    {name}/
      SKILL.md                 # Skill definition
      scripts/                 # Skill scripts
      references/              # Reference materials
      assets/                  # Static assets
      evals/                   # Evaluation files
  agents/                      # Agent definitions (Markdown)
  brands/                      # Brand definitions (BRAND.md + assets)
  presets/                     # Installed presets
  backups/                     # Automatic backups (max 5)
  hooks/
    codi-skill-tracker.cjs     # InstructionsLoaded hook (Claude Code)
    codi-skill-observer.cjs    # Stop hook (Claude Code + Codex)
  .session/
    active-skills.json         # Per-session skill tracking (auto-managed)
  feedback/
    {timestamp}-{artifact}-{id}.json  # One file per collected observation
  operations-ledger.json       # Audit trail of all CLI operations

Manifest (codi.yaml)

The manifest declares your project name, target agents, and optional settings.

name: my-project
version: "1"

# Which agents to generate config for
agents:
  - claude-code
  - cursor
  - codex
  - windsurf
  - cline

# Pin minimum Codi version
codi:
  requiredVersion: ">=2.0.0"

# Control which content types are included in generation
layers:
  rules: true       # default: true
  skills: true      # default: true
  agents: true      # default: true
  context: true     # default: true

# Presets to load (applied in order)
presets:
  - balanced

Manifest Fields

Flags (flags.yaml)

Flags control how AI agents behave in your project. Each flag has a mode and a value.

security_scan:
  mode: enforced
  value: true
  locked: true          # Prevents overriding

type_checking:
  mode: conditional
  value: strict
  conditions:
    agent: [claude-code]       # Only apply for this agent
    file_pattern: ["src/**/*.ts"]  # Only apply to these files

All Flags

Flags with a Hook value create pre-commit checks that enforce the flag at commit time.

Flag Modes

Each flag supports 6 modes that control behavior across the inheritance chain:

Conditional Flags

The conditional mode requires a conditions block with at least one key:

require_tests:
  mode: conditional
  value: true
  conditions:
    agent: [claude-code]           # Match by agent
    file_pattern: ["src/**/*.ts"]  # Match by file glob

All specified conditions must match for the flag to apply.

Locking Flags

Flags can be locked at the repo level to prevent overrides:

security_scan:
  mode: enforced
  value: true
  locked: true

Attempting to override a locked flag produces a validation error.

Flag-to-Instruction Mapping

Flags are automatically translated into natural-language instructions in generated files:

Operational flags (drift_detection, progressive_loading, auto_generate_on_change) control Codi’s behavior and do not generate agent instructions.

Configuration Layers

Configuration is resolved from presets and the project’s .codi/ directory:

MCP Configuration

Define MCP servers in .codi/mcp.yaml:

servers:
  github:
    command: npx
    args: ["-y", "@anthropic-ai/mcp-server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"

  memory:
    command: npx
    args: ["-y", "@anthropic-ai/mcp-memory-server"]
    enabled: false   # Disable without removing

MCP Server Fields

Built-in MCP Server Templates

33 server templates available via codi add mcp-server <name>, organized into three categories:

codi add mcp-server github --template github

Output Locations

MCP config is distributed to each agent in its native format:

Hooks (Heartbeat Feedback Loop)

codi generate writes two hook scripts to .codi/hooks/ and registers them automatically in the agent’s settings file. You do not configure hooks manually.

Claude Code — .claude/settings.json

settings.json is always generated. It contains:

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "type": "command",
        "command": ".codi/hooks/codi-skill-tracker.cjs",
        "timeout": 5,
        "async": true
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": ".codi/hooks/codi-skill-observer.cjs",
        "timeout": 15
      }
    ]
  }
}

If you need personal hooks that run alongside Codi’s, add them to .claude/settings.local.json. Claude Code auto-merges that file with settings.json at startup. Never edit settings.json directly — it is overwritten by codi generate.

Codex — .codex/hooks.json

Codex has no InstructionsLoaded event. Only the Stop observer is wired:

{
  "Stop": [
    {
      "type": "command",
      "command": ".codi/hooks/codi-skill-observer.cjs",
      "timeout": 15
    }
  ]
}

What the hooks do

See the self-improvement guide for a full explanation of how the feedback loop works.