@pleri/olam-cli

Standalone CLI for Olam — isolated development worlds with thought-graph capture, autonomous Build, and an MCP server for Claude Code.

# 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.

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)

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:

{
  "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

claude mcp list | grep olam

Restart Claude Code; the olam_* tools surface automatically.

Bootstrap the world stack

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.

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

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:

olam --help
olam <command> --help

Self-upgrade

olam upgrade -y                 # pull latest digests; restart services

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

Docs

• Full README
• MCP wiring deep-dive
• Architecture index

License

See LICENSE.