# Installation

This page covers installing the `ai-cli-dispatch` tool, its prerequisites, and post-install verification.

## Prerequisites

- **Node.js** ≥ 20 (required for `tsx`, `import` attributes, and modern `node:child_process` APIs)
- **npm** (bundled with Node.js)
- **Homebrew** (macOS/Linux) — recommended for installing the underlying AI CLI clients (`codex`, `claude`, `opencode`)
- One or more supported AI CLI clients:
  - [Codex CLI](https://github.com/openai/codex)
  - [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)
  - [OpenCode](https://github.com/opencode-ai/opencode)

## Install the tool

### 1. Clone the repository

```bash
git clone <repository-url> ~/.openclaw/workspace/skills/ai-cli-dispatch
cd ~/.openclaw/workspace/skills/ai-cli-dispatch
```

If you already have the full `stef-openclaw-skills` repo checked out, use the path inside it instead:

```bash
cd ~/.openclaw/workspace/skills/stef-openclaw-skills/tools/ai-cli-dispatch
```

### 2. Install Node dependencies

```bash
npm install
```

This installs:
- `tsx` — TypeScript execution runtime
- `minimist` — argument parsing
- `typescript` — type checking

## PATH configuration

The helper script lives at `scripts/ai-cli-dispatch`. Add it to your shell PATH so OpenClaw (or your terminal) can invoke it without a full path:

```bash
# ~/.zshrc or ~/.bashrc
export PATH="$HOME/.openclaw/workspace/skills/ai-cli-dispatch/scripts:$PATH"
```

Reload your shell:

```bash
source ~/.zshrc   # or ~/.bashrc
```

Verify the script is reachable:

```bash
which ai-cli-dispatch
ai-cli-dispatch --help
```

## Optional configuration file

Create `~/.openclaw/ai-cli-dispatch.json` to customize client paths and set a default client:

```bash
mkdir -p ~/.openclaw
$EDITOR ~/.openclaw/ai-cli-dispatch.json
```

Example configuration:

```json
{
  "paths": {
    "codex": "/opt/homebrew/bin/codex",
    "claude": "/opt/homebrew/bin/claude",
    "opencode": "/opt/homebrew/bin/opencode"
  },
  "defaultClient": "claude"
}
```

### Configuration precedence

When resolving a client binary, the tool checks sources in this order (first match wins):

1. CLI flag: `--codex-path`, `--claude-path`, `--opencode-path`
2. Environment variable: `AI_CLI_CODEX_PATH`, `AI_CLI_CLAUDE_PATH`, `AI_CLI_OPENCODE_PATH`
3. File config: `paths.<client>` in `~/.openclaw/ai-cli-dispatch.json`
4. System `PATH` lookup via `which` / `where`

The `defaultClient` follows the same precedence:

1. CLI flag: `--default-client`
2. Environment variable: `AI_CLI_DEFAULT_CLIENT`
3. File config: `defaultClient` in `~/.openclaw/ai-cli-dispatch.json`

## Install AI CLI clients

### Codex

```bash
npm install -g @openai/codex
```

### Claude Code

```bash
npm install -g @anthropic-ai/claude-code
```

### OpenCode

```bash
npm install -g @opencode-ai/opencode
```

Or via Homebrew where formulas are available:

```bash
brew install codex        # if available in your tap
brew install claude-code  # if available in your tap
```

## Verification

### 1. Check local tool health

```bash
ai-cli-dispatch --help
```

Expected output:

```text
AI CLI Dispatch

Usage:
  ai-cli-dispatch list [--json|--text]
  ai-cli-dispatch run --client <client> --prompt <prompt> [--json|--text]
  ai-cli-dispatch dispatch <prompt> [--client <client>] [--json|--text]
  ai-cli-dispatch --help

Clients: codex, claude, opencode
```

### 2. List discovered clients

```bash
ai-cli-dispatch list --json
```

Example output when two clients are installed:

```json
[
  {
    "name": "codex",
    "path": "/opt/homebrew/bin/codex",
    "version": "1.2.3",
    "found": true
  },
  {
    "name": "claude",
    "path": "/opt/homebrew/bin/claude",
    "version": "0.7.8",
    "found": true
  },
  {
    "name": "opencode",
    "found": false
  }
]
```

### 3. Run a quick dispatch

```bash
ai-cli-dispatch run --client codex --prompt "hello" --json
```

This should return a JSON result with `stdout`, `stderr`, and `exitCode`.

### 4. Test keyword dispatch

```bash
ai-cli-dispatch dispatch "refactor this using claude"
```

The tool inspects the prompt for client keywords (`claude`, `codex`, `opencode`, `open code`) and routes to the matching client.

## Troubleshooting

### `Missing local Node dependencies for ai-cli-dispatch`

Run `npm install` from the skill directory:

```bash
cd ~/.openclaw/workspace/skills/ai-cli-dispatch
npm install
```

### `Client "codex" not found or not installed`

- Ensure the client is installed globally or via Homebrew
- Verify it is on your PATH: `which codex`
- Or override the path in `~/.openclaw/ai-cli-dispatch.json` or with an environment variable

### `Prompt cannot be empty`

The `run` and `dispatch` commands require a non-empty `--prompt` or trailing prompt text.

### Config file is not being read

- Verify the file is at exactly `~/.openclaw/ai-cli-dispatch.json`
- Check for JSON syntax errors (trailing commas are not allowed)
- Use `--debug` for deeper troubleshooting if supported by the calling context