# oh-my-ashclaw

**Multi-agent orchestration for Ash-Claw. Zero learning curve.**

_Don't learn Ash-Claw. Just use OMAC._

---

## Quick Start

### 方式一：一键安装脚本（推荐）

**Windows：**
```cmd
cd oh-my-ashclaw
install.bat
```

**Linux/macOS：**
```bash
cd oh-my-ashclaw
chmod +x install.sh
./install.sh
```

### 方式二：手动安装

```bash
# Step 1: 添加到 Marketplace 并安装
ash-claw plugin marketplace add /path/to/oh-my-ashclaw
ash-claw plugin install oh-my-ashclaw

# Step 2: 安装 ripgrep（国内推荐 npm 方式）
npm install -g ripgrep
# 或者直接下载: https://github.com/BurntSushi/ripgrep/releases

# Step 3: 运行初始设置
ash-claw
# 进入会话后输入:
/setup
```

### 方式三：免安装模式

```bash
ash-claw --plugin-dir /path/to/oh-my-ashclaw
```

### Setup

```bash
# Inside an Ash-Claw / OMAC session
/setup
/omac-setup

# From your terminal
omac setup
```

If you run OMAC via `omac --plugin-dir <path>` or `ash-claw --plugin-dir <path>`, add `--plugin-dir-mode` to `omac setup` (or export `OMAC_PLUGIN_ROOT` before running it) so the installer doesn't duplicate skills/agents that the plugin already provides at runtime.

**Step 3: Build something**

```bash
# Inside an Ash-Claw / OMAC session
/autopilot "build a REST API for managing tasks"

# Natural-language in-session shortcut
autopilot: build a REST API for managing tasks
```

That's it. Everything else is automatic.

### CLI Commands vs In-Session Skills

OMAC exposes two different surfaces:

- **Terminal CLI commands**: run `omac ...` from your shell after installing the npm/runtime path or from a local checkout.
- **In-session skills**: run `/...` inside an Ash-Claw session after installing the plugin/setup flow.

| Feature | Terminal CLI | In-session skill | Notes |
| --- | --- | --- | --- |
| Setup | `omac setup` | `/setup` or `/omac-setup` | Both are real entrypoints. `/setup` is the easiest plugin-first path. |
| Team orchestration | `omac team 2:ash-claw "fix all TypeScript errors"` | `/team 3:executor "fix all TypeScript errors"` | Both exist, but they are different runtimes: `omac team` launches tmux CLI workers; `/team` runs the in-session native team workflow. |
| Autopilot / Ralph / Ultrawork / Deep Interview | — | `/autopilot ...`, `/ralph ...`, `/ultrawork ...`, `/deep-interview ...` | These are in-session skills. There is no `omac autopilot` / `omac ralph` / `omac ultrawork` CLI subcommand in this repo. |

### Not Sure Where to Start?

If you're uncertain about requirements, have a vague idea, or want to micromanage the design:

```
/deep-interview "I want to build a task management app"
```

The deep interview uses Socratic questioning to clarify your thinking before any code is written.

## Team Mode (Recommended)

**Team** is the canonical orchestration surface in OMAC.

```bash
/team 3:executor "fix all TypeScript errors"
```

Use `/team ...` when you want Ash-Claw's in-session native team workflow. Use `omac team ...` when you want terminal-launched tmux CLI workers.

Team runs as a staged pipeline:

`team-plan → team-prd → team-exec → team-verify → team-fix (loop)`

Enable Ash-Claw native teams in `~/.ash-claw/settings.json`:

```json
{
  "env": {
    "ASHCLAW_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

> If teams are disabled, OMAC will warn you and fall back to non-team execution where possible.

### tmux CLI Workers

Use the CLI-first Team runtime (`omac team ...`) to spawn tmux worker panes:

```bash
omac team 2:ash-claw "review auth module for security issues"
omac team 3:ash-claw "implement the payment flow"
omac team status auth-review
omac team shutdown auth-review
```

| Surface                      | Workers             | Best For                                     |
| --------------------------- | ------------------ | -------------------------------------------- |
| `omac team N:ash-claw "..."` | N Ash-Claw CLI panes | General tasks via Ash-Claw CLI in tmux       |

Workers spawn on-demand and die when their task completes — no idle resource usage. Requires tmux.

---

## Why oh-my-ashclaw?

- **Zero configuration required** - Works out of the box with intelligent defaults
- **Team-first orchestration** - Team is the canonical multi-agent surface
- **Natural language interface** - No commands to memorize, just describe what you want
- **Automatic parallelization** - Complex tasks distributed across specialized agents
- **Persistent execution** - Won't give up until the job is verified complete
- **Cost optimization** - Smart model routing saves 30-50% on tokens
- **Learn from experience** - Automatically extracts and reuses problem-solving patterns

---

## Features

### Orchestration Modes

| Mode                   | What it is                                                    | Use For                                                |
| ---------------------- | ------------------------------------------------------------- | ------------------------------------------------------ |
| **Team (recommended)** | Canonical staged pipeline                                     | Coordinated agents on a shared task list               |
| **Autopilot**          | Autonomous execution (single lead agent)                     | End-to-end feature work with minimal ceremony          |
| **Ralph**              | Persistent mode with verify/fix loops                          | Tasks that must complete fully (no silent partials)    |
| **Ultrawork**          | Maximum parallelism                                           | Burst parallel fixes/refactors where Team isn't needed  |
| **UltraQA**            | QA cycling                                                    | Test, verify, fix, repeat                              |
| **Deep Interview**     | Socratic requirements clarification                            | Clarify vague ideas before coding                       |

### Smart Skills

- `/plan` - Strategic planning
- `/autopilot` - Full autonomous execution
- `/ralph` - Persistence with verification
- `/team` - Multi-agent coordination
- `/ultraqa` - Test verification loop
- `/verify` - Verify changes actually work
- `/trace` - Evidence-driven causal tracing
- `/deep-dive` - Two-phase research

---

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ASH_CONFIG_DIR` | Configuration directory | `~/.ash-claw` |
| `ASHCLAWCODE` | Session detection (auto-set by ash-claw) | - |
| `OMAC_PLUGIN_ROOT` | Plugin root directory | - |

### Directories

- `~/.ash-claw/` - Main config directory
- `.omac/` - Project-level state directory

---

## Platform & Requirements

- [ash-claw](https://github.com/anthropics/claude-code) CLI installed
- Ash-Claw Max/Pro subscription OR API key

### tmux (for some features)

Some OMAC features require tmux:

| Platform | Install |
| -------- | ------- |
| macOS | `brew install tmux` |
| Ubuntu/Debian | `sudo apt install tmux` |
| Windows | `winget install psmux` |

---

## Updating

```bash
# Update plugin
ash-claw plugin marketplace update omac
/setup
```

---

## Compared to oh-my-claudecode

| Item | oh-my-claudecode | oh-my-ashclaw |
|------|------------------|---------------|
| CLI command | `claude` | `ash-claw` |
| Config directory | `~/.claude` | `~/.ash-claw` |
| Environment var | `CLAUDE_CONFIG_DIR` | `ASH_CONFIG_DIR` |
| Session detection | `CLAUDECODE` | `ASHCLAWCODE` |
| Plugin command | `omc` | `omac` |
| Plugin directory | `.claude-plugin` | `.ash-claw-plugin` |

---

## Credits

Based on [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) by Yeachan Heo.

---

## License

MIT