# Getting Started

> Quick start guide: from installation to your first OMC session.

If you're new to Oh My CodeBuddy (OMC), follow the steps below in order.

1. [Installation](#installation) - Install the OMC plugin and run initial setup
2. [First Session](#first-session) - Run your first task with autopilot
3. [Configuration](#configuration) - Customize settings and agent models per project

### What this guide covers

- How to install the OMC plugin
- Running your first autopilot session and understanding the flow
- Configuring per-user and per-project settings

### Prerequisites

- [CodeBuddy Code](https://docs.anthropic.com/claude-code) must be installed
- CodeBuddy subscription or an Anthropic API key is required

---

## Installation

OMC ships two surfaces and they are designed to coexist:

| Surface | What you get | Recommended install |
|---|---|---|
| **CodeBuddy Code plugin** (`oh-my-codebuddy@omc`) | In-session skills, agents, hooks, statusline, MCP servers — the `/autopilot`, `/ralph`, `/ultrawork`, `/team` slash commands | Marketplace plugin install (Step 1–2 below) |
| **Terminal CLI** (`omc` binary, package `oh-my-codebuddy-sisyphus`) | Shell commands: `omcb setup`, `omcb update`, `omcb team`, `omcb ask`, and a hard-deprecated `omcb autoresearch` shim | `npm i -g oh-my-codebuddy-sisyphus@latest` |

Most users want **both**: the plugin for the in-session experience, and the npm CLI for shell-side automation and updates. Running them in parallel is fully supported — `omcb update` and `omcb setup` are idempotent and detect the plugin install to avoid duplicating in-session skills (#2252).

> Older versions of this doc said OMC was "plugin-only". That was incorrect: the `omc` CLI is the canonical entry point for `omcb setup`/`omcb update` and is published on npm as `oh-my-codebuddy-sisyphus`. See the [Quick Start in README.md](../README.md#quick-start) for the same two-path layout.

### Step 1: Add the marketplace source

Run the following command inside CodeBuddy Code:

```bash
/plugin marketplace add https://github.com/cbbfcd/oh-my-codebuddy
```

### Step 2: Install the plugin

After adding the marketplace, install the plugin:

```bash
/plugin install oh-my-codebuddy
```

### Step 2b (optional but recommended): install the terminal CLI

If you want `omcb setup`, `omcb update`, `omcb team`, `omcb ask`, etc. on your shell:

```bash
npm i -g oh-my-codebuddy-sisyphus@latest
```

> **Known npm warning:** npm may print `deprecated prebuild-install@7.1.3` during this CLI install.
> The warning currently comes from the upstream `better-sqlite3` native-addon dependency
> (`better-sqlite3 -> prebuild-install`); `prebuild-install@7.1.3` is still the latest
> published version, so there is no safe repo-side dependency bump or override to remove it
> yet. The warning is tracked in [#2913](https://github.com/cbbfcd/oh-my-codebuddy/issues/2913)
> and does not by itself mean the OMC CLI install failed.

Both can be installed at the same time. The CLI auto-detects the plugin install and will not double-register skills under `~/.codebuddy/skills/` (if you previously hit the duplicate-skill bug, run `omcb update` once on 4.11.2+ — it self-heals leftover standalone skills that the plugin now provides via `prunePluginDuplicateSkills`).

### Step 3: Run initial setup

After installation, enter one of the following in CodeBuddy Code:

```bash
# Option 1: natural language
setup omcb

# Option 2: skill command
/oh-my-codebuddy:omc-setup
```

### Prerequisites summary

| Item | Requirement |
|------|-------------|
| CodeBuddy Code | Must be installed |
| Authentication | Claude Max/Pro subscription or `ANTHROPIC_API_KEY` environment variable |

### Choosing a setup scope

#### Project-scoped setup (recommended)

Applies OMC only to the current project:

```bash
/oh-my-codebuddy:omc-setup --local
```

- Settings are saved to `./.codebuddy/CODEBUDDY.md`
- No effect on other projects
- Existing global `CODEBUDDY.md` is preserved

#### Global setup

Applies OMC to all CodeBuddy Code sessions:

```bash
/oh-my-codebuddy:omc-setup
```

- Settings are saved to `~/.codebuddy/CODEBUDDY.md`
- Applied across all projects

> ⚠️ **Warning:** Global setup now asks explicitly before changing your base `~/.codebuddy/CODEBUDDY.md`. The default choice is still overwrite. If you choose preserve mode instead, plain `claude` stays on your base config and `omcb` force-loads the OMC companion config.

### Verifying the installation

To confirm everything is working, run the diagnostics tool:

```bash
/oh-my-codebuddy:omc-doctor
```

This checks the following:

- Dependency installation status
- Configuration file errors
- Hook installation status
- Agent availability
- Skill registration status

### Running from a local checkout

If you're developing OMC or want to test unreleased features from a specific branch, you can launch CodeBuddy Code with your local checkout as the plugin:

```bash
omcb --plugin-dir /path/to/oh-my-codebuddy setup --plugin-dir-mode
```

This loads agents, skills, and commands directly from your checkout without copying them to `~/.codebuddy/`. For detailed instructions and alternative flows, see [LOCAL_PLUGIN_INSTALL.md](./LOCAL_PLUGIN_INSTALL.md). For a complete decision matrix of plugin-dir flags and modes, see the [Plugin directory flags section in REFERENCE.md](./REFERENCE.md#plugin-directory-flags).

### Platform support

| Platform | Installation | Hook type |
|----------|--------------|-----------|
| macOS | CodeBuddy Code Plugin | Bash (.sh) |
| Linux | CodeBuddy Code Plugin | Bash (.sh) |
| Windows | WSL2 recommended | Node.js (.mjs) |

> ℹ️ **Note:** Native Windows support is experimental. OMC requires tmux, which is not available on native Windows. Use WSL2 instead.

### Updates

OMC automatically checks for updates every 24 hours. To update manually, re-run the plugin install command.

> ⚠️ **Warning:** After a plugin update, run `/oh-my-codebuddy:omc-setup` again to apply the latest CODEBUDDY.md configuration.

### Uninstalling

```bash
/plugin uninstall oh-my-codebuddy@oh-my-codebuddy
```

---

## First Session

Once OMC is installed, run your first task immediately. Open CodeBuddy Code and type:

```bash
autopilot build me a hello world app
```

That single line is enough for OMC to run the full development pipeline automatically.

### What happens

When OMC detects the `autopilot` magic keyword, it starts a 5-stage pipeline:

### Stage 1: Expansion

The `analyst` and `architect` agents analyze the idea, clarify requirements, and produce a technical specification.

### Stage 2: Planning

The `planner` agent creates an execution plan. The `critic` agent reviews the plan and identifies gaps.

### Stage 3: Execution

The `executor` agent writes the code. Multiple agents work in parallel when needed.

### Stage 4: QA

Verifies that the build succeeds and tests pass. Automatically fixes failures and re-verifies.

### Stage 5: Validation

Specialist agents perform a final review of functionality, security, and code quality. Work is complete once all pass.

### HUD status display

While work is in progress, you can monitor the current state in the CodeBuddy Code status bar (HUD):

```
[OMC] autopilot:execution | agents:3 | todos:2/5 | ctx:45%
```

| Field | Meaning |
|-------|---------|
| `autopilot:execution` | Current stage within the autopilot pipeline |
| `agents:3` | Number of currently active agents |
| `todos:2/5` | Completed tasks / total tasks |
| `ctx:45%` | Context window usage percentage |

To configure the HUD display, run:

```bash
/oh-my-codebuddy:hud setup
```

### Starting smaller

If autopilot feels too large, start with a single-task command:

```bash
# Code analysis
analyze why this test is failing

# File search
deepsearch for files that handle authentication

# Simple implementation
ultrawork add a health check endpoint
```

These keywords invoke a single appropriate agent directly, without running the full pipeline.

### Next steps

- [Configuration](#configuration) - Adjust agent models and features for your project
- [Architecture](./ARCHITECTURE.md) - Understand the relationship between agents, skills, and hooks

---

## Configuration

OMC supports two levels of configuration files.

| Scope | File path | Purpose |
|-------|-----------|---------|
| User (global) | `~/.config/codebuddy-omcb/config.jsonc` | Applied to all projects |
| Project | `.codebuddy/omcb.jsonc` | Applied to current project only |

> ⚠️ **Warning:** The configuration file format is JSONC (JSON with comments support). It is not a TypeScript config file (`omc.config.ts`).

### Configuration priority

When settings exist from multiple sources, they are merged in the following order (lower entries take precedence):

```
Defaults → User config (~/.config/codebuddy-omcb/config.jsonc)
         → Project config (.codebuddy/omcb.jsonc)
         → Environment variables
```

### Basic configuration structure

```jsonc
{
  // Per-agent model assignments
  "agents": {
    "explore": { "model": "haiku" },
    "executor": { "model": "sonnet" },
    "architect": { "model": "opus" }
  },

  // Feature toggles
  "features": {
    "parallelExecution": true,
    "lspTools": true,
    "astTools": true
  },

  // Magic keyword customization
  "magicKeywords": {
    "ultrawork": ["ultrawork", "ulw", "uw"],
    "search": ["search", "find", "locate"],
    "analyze": ["analyze", "investigate", "examine"],
    "ultrathink": ["ultrathink", "think", "reason"]
  },

  // Optional prompt-level company context contract
  "companyContext": {
    "tool": "mcp__vendor__get_company_context",
    "onError": "warn"
  }
}
```

### Company context via MCP

If your organization exposes internal guidance through a custom MCP server, configure the selected tool in OMC's standard config files:

```jsonc
{
  "companyContext": {
    "tool": "mcp__vendor__get_company_context",
    "onError": "warn"
  }
}
```

- Register the MCP server itself through the normal Claude/OMC MCP setup flow.
- `tool` is the full MCP tool name.
- `onError` controls prompt-level fallback: `warn` (default), `silent`, or `fail`.

This is an advisory workflow contract, not runtime enforcement. See [company-context-interface.md](./company-context-interface.md) for the full contract.

### Overriding agent models

You can change the AI model used by each agent:

```jsonc
{
  "agents": {
    // Upgrade explore agent to a stronger model
    "explore": { "model": "sonnet" },

    // Upgrade executor to opus for complex projects
    "executor": { "model": "opus" },

    // Cost saving: use haiku for documentation writing
    "writer": { "model": "haiku" }
  }
}
```

#### Default model mapping

| Agent | Default model | Role |
|-------|--------------|------|
| `explore` | haiku | Codebase discovery |
| `writer` | haiku | Documentation writing |
| `executor` | sonnet | Code implementation |
| `debugger` | sonnet | Debugging |
| `designer` | sonnet | UI/UX design |
| `verifier` | sonnet | Verification |
| `tracer` | sonnet | Evidence-driven causal tracing |
| `security-reviewer` | sonnet | Security vulnerabilities and trust boundaries |
| `test-engineer` | sonnet | Test strategy and coverage |
| `qa-tester` | sonnet | Interactive CLI/service runtime validation |
| `scientist` | sonnet | Data and statistical analysis |
| `git-master` | sonnet | Git operations and history management |
| `document-specialist` | sonnet | External documentation and API reference lookup |
| `architect` | opus | System design |
| `planner` | opus | Strategic planning |
| `critic` | opus | Plan review |
| `analyst` | opus | Requirements analysis |
| `code-reviewer` | opus | Comprehensive code review |
| `code-simplifier` | opus | Code clarity and simplification |

### Customizing magic keywords

You can change keywords in four categories via the `magicKeywords` section of `config.jsonc`:

```jsonc
{
  "magicKeywords": {
    // Triggers parallel execution mode
    "ultrawork": ["ultrawork", "ulw", "parallel"],

    // Triggers codebase search mode
    "search": ["search", "find", "locate", "grep"],

    // Triggers analysis mode
    "analyze": ["analyze", "debug", "investigate"],

    // Triggers deep reasoning mode
    "ultrathink": ["ultrathink", "think", "reason"]
  }
}
```

> ℹ️ **Note:** The `magicKeywords` section in `config.jsonc` only allows customizing four categories: `ultrawork`, `search`, `analyze`, and `ultrathink`. Keywords such as `autopilot`, `ralph`, and `ccg` are hardcoded in the keyword-detector hook and cannot be changed via config files.

### Model routing configuration

OMC automatically selects a model tier based on task complexity:

```jsonc
{
  "routing": {
    "enabled": true,
    "defaultTier": "MEDIUM",
    // Force all agents to inherit the parent model
    // (auto-activated when using CC Switch, Bedrock, or Vertex AI)
    "forceInherit": false
  }
}
```

| Tier | Model | Use case |
|------|-------|----------|
| LOW | haiku | Quick lookups, simple tasks |
| MEDIUM | sonnet | Standard implementation, general tasks |
| HIGH | opus | Architecture, deep analysis |

### CODEBUDDY.md configuration

OMC's default behavior is also configured via `CODEBUDDY.md` files. Running `/oh-my-codebuddy:omc-setup` generates this file automatically.

| Scope | File | Description |
|-------|------|-------------|
| Global | `~/.codebuddy/CODEBUDDY.md` | Shared settings across all projects |
| Project | `.codebuddy/CODEBUDDY.md` | Per-project context and overrides |

### When to re-run setup

- After initial installation
- After an OMC update (to apply the latest CODEBUDDY.md configuration)
- When switching to a different machine
- When starting a new project (use the `--local` option)