# @pleri/olam-cli

Standalone CLI for [Olam](https://github.com/pleri/olam) — isolated
development worlds with thought-graph capture, autonomous Build, and
an MCP server for Claude Code.

```sh
# Install
curl -fsSL https://olam.bar.dev/install | sh
# (or: npm install -g @pleri/olam-cli)

# Verify
olam --version
```

The installer publishes from npmjs.org. Requires **Node.js ≥ 20** and
`npm`. Track the prerelease tag with `OLAM_CHANNEL=canary`.

## Run modes

Olam ships in two substrate-aware run modes. `olam setup` is the canonical fresh-host wizard; it dispatches to the right backend based on `~/.olam/config.json`'s `host.substrate` value (`bootstrap`, `services`, `upgrade`, and `doctor` are all substrate-aware too).

| Mode | What runs | When to use | Bring up |
|---|---|---|---|
| **K3s** (default) | Full Kubernetes deployment on a local k3d cluster (`host-cp`, `auth-service`, `mcp-auth-service`, `kg-service`, `memory-service`) plus a `monitoring` namespace with kube-prometheus-stack + Loki + Grafana. | Same cluster topology olam runs in cloud/dogfood, ingress routing, observability dashboards, NetworkPolicy isolation. | `olam setup` — on macOS, auto-installs missing brew formulae by default. Guide: [olam.bar.dev/wiki?p=k3s](https://olam.bar.dev/wiki?p=k3s) |
| **Compose** | 3 host containers (`olam-auth`, `olam-mcp-auth`, `olam-kg-service`) brought up via docker compose. | Lighter setup for hosts that can't run a Kubernetes cluster locally, or for CI. | `olam setup --substrate=docker`. Guide: [olam.bar.dev/wiki?p=setup](https://olam.bar.dev/wiki?p=setup) |

K3s mode requires `k3d`, `kubectl`, `helm`, `gh`, and `docker`. `olam setup` prompts to install missing tools on macOS (via brew) and Linux (via upstream install scripts); pass `-y` to skip all prompts. Full prereq list at [olam.bar.dev/wiki?p=k3s](https://olam.bar.dev/wiki?p=k3s).

## Wire the MCP server into Claude Code

Olam ships an MCP server with `olam_create`, `olam_dispatch`,
`olam_destroy`, `olam_list`, `olam_status`, `olam_enter`, `olam_pr`,
`olam_observe`, `olam_lane_*`, and `olam_capture_view`. Three wiring
paths:

### One command (recommended)

```sh
olam mcp install                  # default --scope=user
olam mcp install --scope=project  # writes to project .mcp.json
olam mcp uninstall                # idempotent; symmetric
```

Auto-detects whether `olam` is on PATH. If so, writes
`command: "olam"`. Otherwise falls back to
`command: "npx", args: ["-y", "@pleri/olam-cli", "mcp", "serve"]`.

### Paste-in JSON

Drop into `~/.claude.json` (user scope) or a project's `.mcp.json`:

```json
{
  "mcpServers": {
    "olam": {
      "command": "npx",
      "args": ["-y", "@pleri/olam-cli", "mcp", "serve"]
    }
  }
}
```

If `olam` is already on PATH, `command: "olam", args: ["mcp", "serve"]`
is faster (no `npx` cold-start).

### Marketplace alias

`olam --mcp` is a thin alias for `olam mcp serve`, matching the MCP
marketplace convention where snippets invoke `npx -y <pkg> --mcp`. The
two invocations produce identical stdio output.

### Verify

```sh
claude mcp list | grep olam
```

Restart Claude Code; the `olam_*` tools surface automatically.

## Bootstrap the world stack

```sh
olam bootstrap                  # pull host-cp + auth + devbox; start services; auth login
olam bootstrap --with-smoke     # also create a smoke-test world
olam bootstrap --skip-auth-login
olam bootstrap --registry ghcr.io/pleri
```

What it does (digest-pinned, idempotent, parallel pulls, retries on
transient failure): see
[`docs/architecture/bootstrap.md`](https://github.com/pleri/olam/blob/main/docs/architecture/bootstrap.md).
For the full stack setup, see
[`docs/onboarding/k3s-mode-setup.md`](https://github.com/pleri/olam/blob/main/docs/onboarding/k3s-mode-setup.md).

State lands under `~/.olam/`:

- `~/.olam/auth-secret` — shared secret (`0600`) generated on first
  `auth up`.
- `~/.olam/worlds/<world-id>/` — per-world worktree + thought DB.
- `~/.olam/worlds.db` — world registry.
- `~/.olam/upgrade.log` — JSONL audit log of `olam upgrade`.

## Common commands

```sh
olam create --name <slug> --task "<one-line goal>"
olam list
olam status <world>
olam enter <world>            # cd into the world's host clone
olam dispatch <world> "<msg>"
olam observe <world>          # tail the world's thought stream
olam pr <world>               # open / inspect the world's PR
olam destroy <world>
```

Full surface:

```sh
olam --help
olam <command> --help
```

## Agentic coding — yolo dispatch

`olam yolo` dispatches a parallel Claude Code session (`--dangerously-skip-permissions`)
in a new tmux window backed by an isolated git worktree. Each session gets its
own branch so it can't clobber the operator's main shell.

```sh
# Spawn a yolo on a bounded task
olam yolo my-task --branch feat/my-task --prompt-file /tmp/my-task.txt

# List active yolo windows
olam yolo --list

# Clean up after merge
olam yolo --cleanup my-task
```

Full reference: `olam yolo --help` and [`docs/runbooks/olam-yolo-cli.md`](../../docs/runbooks/olam-yolo-cli.md).

## Multi-account Claude Code (`--claude-home`)

Inspired by [t3code](https://github.com/pingdotgg/t3code) — one operator,
many Claude Code instances, each with its own `HOME` env var pointing at
a separate `~/.claude.instance-N/` directory.

```sh
olam create my-world --claude-home work-account
olam create other-world --claude-home personal-account
```

Each instance gets its own:

- login (`claude login` is per-`HOME`)
- hooks (`settings.json` scoped to the per-world Claude home)
- MCP topology
- 429 rate-limit bucket

One-time setup per home:

```sh
HOME="$HOME/.olam/claude-homes/work-account" claude login
HOME="$HOME/.olam/claude-homes/personal-account" claude login
```

The `--claude-home <id>` value is persisted to the world's metadata, so
`olam enter <world>` and subsequent operations stay bound to the same
account. Absolute paths are accepted verbatim
(`--claude-home /opt/shared-claude`).

Composes with `@olam/auth-client`'s vault — the vault still rotates
credentials **within** a HOME; `--claude-home` isolates **different**
HOMEs from each other so two worlds on the same host genuinely use
different accounts without rotation choreography.

See [ADR 045](../../docs/decisions/045-claude-home-override.md) for the
full rationale + operator workflow.

## Self-upgrade

```sh
olam upgrade -y                 # pull latest digests; restart services
```

JSONL audit log at `~/.olam/upgrade.log`.

## Docs

- [Full README](https://github.com/pleri/olam#readme)
- [MCP wiring deep-dive](https://github.com/pleri/olam/blob/main/docs/architecture/mcp-as-npx-served.md)
- [Architecture index](https://github.com/pleri/olam/tree/main/docs/architecture)

## License

See [LICENSE](https://github.com/pleri/olam/blob/main/LICENSE).
