{
  "id": "page:docs-user-guide-getting-started-installation",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/getting-started/installation.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/getting-started/installation.md",
    "sourceKind": "repo-docs",
    "title": "Installation Guide",
    "displayName": "Installation Guide",
    "slug": "docs/user-guide/getting-started/installation",
    "articlePath": "wiki/docs/user-guide/getting-started/installation.md",
    "article": "\n[Docs](../index.md) › [Getting Started](./README.md) › Installation\n\n# Installation Guide\n\nThis guide walks you through installing Babysitter v6 on your system. By the end, you will have a fully working installation and will have run an Adapter to confirm it works.\n\n**Estimated time:** 5-10 minutes\n\n---\n\n## In Plain English\n\n**v6 has two install tracks. Don't conflate them:**\n\n1. **The host-side `adapters` CLI** — run any supported AI coding harness directly from your shell. Install `@a5c-ai/adapters-cli`, then `adapters run claude \"...\"`.\n2. **The in-session per-harness plugin** — drive a full Babysitter orchestration [run](../reference/glossary.md) from *inside* your harness (Claude Code, Codex, Cursor, and 9 more). Install the core CLI plus your harness's plugin.\n\nMost people want both. Install the core CLI and the Adapters CLI first (this page), then pick your harness and follow its page. Babysitter supports **12 harnesses**; the two fully-worked ones are [Claude Code](../harnesses/claude-code.md) and [Codex](../harnesses/codex.md), and every harness is listed in the [Install Matrix](../harnesses/install-matrix.md).\n\n---\n\n## On this page\n\n- [Prerequisites Check](#prerequisites-check)\n- [Installation Methods](#installation-methods)\n  - [Method 1: Quick Install (Recommended)](#method-1-quick-install-recommended)\n  - [Method 2: Step-by-Step Install](#method-2-step-by-step-install)\n- [Platform-Specific Instructions](#platform-specific-instructions)\n  - [macOS](#macos)\n  - [Linux](#linux)\n  - [Windows](#windows)\n- [Plugin Installation](#plugin-installation)\n- [Other Harnesses](#other-harnesses)\n- [Verification](#verification)\n- [Keeping Updated](#keeping-updated)\n- [Upgrading from a Prior Version](#upgrading-from-a-prior-version)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## Prerequisites Check\n\nBefore installing Babysitter, let's verify your system is ready.\n\n### Required: Node.js 20.0.0+\n\nThe core toolchain runs on **Node.js 20.0.0+** (22.x LTS recommended). The **Adapters CLI requires Node.js >=20.9.0**.\n\n```bash\nnode --version\n```\n\n**Expected output:** `v20.9.x` or higher (or `v22.x.x`)\n\nIf you see a lower version or \"command not found,\" install Node.js:\n\n**Using nvm (recommended):**\n```bash\n# Install nvm if you don't have it\ncurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash\n\n# Restart your terminal, then:\nnvm install 22\nnvm use 22\n```\n\n**Direct download:** Visit [nodejs.org](https://nodejs.org/) and download the LTS version.\n\n### Required: A supported harness (for in-session use)\n\nTo drive Babysitter runs from inside a harness, install at least one supported harness CLI — for example Claude Code:\n\n```bash\nclaude --version\n```\n\n**Expected output:** Claude Code version information\n\nIf Claude Code is not installed, follow the [Claude Code installation guide](https://docs.anthropic.com/en/docs/claude-code). For any other harness, see the [Install Matrix](../harnesses/install-matrix.md).\n\n> If you only want to run harnesses from your shell via the `adapters` CLI, you can skip the in-session plugin entirely.\n\n### Required: jq (JSON processor)\n\nMany Babysitter commands output JSON that is processed with `jq`. Install it for your platform:\n\n```bash\njq --version\n```\n\n**Expected output:** `jq-1.6` or higher\n\n**Installation:**\n\n```bash\n# macOS\nbrew install jq\n\n# Ubuntu/Debian\nsudo apt-get install jq\n\n# Fedora/RHEL\nsudo dnf install jq\n\n# Windows (via Chocolatey)\nchoco install jq\n\n# Windows (via Scoop)\nscoop install jq\n```\n\n### Verification Checkpoint\n\nRun this command to verify all prerequisites:\n\n```bash\necho \"Node: $(node --version)\" && echo \"npm: $(npm --version)\" && echo \"jq: $(jq --version)\"\n```\n\nYou should see version numbers for all three tools. If you plan to use a harness in-session, also confirm it is installed (e.g. `claude --version` for Claude Code). Address any missing requirement before continuing.\n\n---\n\n## Installation Methods\n\n### Method 1: Quick Install (Recommended)\n\nCopy and paste this to install the main CLI, the host-side **Adapters CLI**, and the Claude Code plugin:\n\n```bash\nnpm install -g @a5c-ai/babysitter@latest @a5c-ai/adapters-cli && \\\nclaude plugin marketplace add a5c-ai/babysitter-claude && \\\nclaude plugin install --scope user babysitter@a5c.ai && \\\nclaude plugin enable --scope user babysitter@a5c.ai\n```\n\nTry an Adapter immediately to confirm the host-side track works:\n\n```bash\nadapters version\nadapters doctor\nadapters run claude \"explain this repository in two sentences\"\n```\n\nIf you also want headless runtime commands such as `genty call`, install the optional runtime CLI too:\n\n```bash\nnpm install -g @a5c-ai/genty-platform@latest\n```\n\nThen restart Claude Code and skip to [Verification](#verification).\n\n> Using a harness other than Claude Code? Replace the three `claude plugin ...` lines with `babysitter harness:install-plugin <harness-key>` for your harness — see [Other Harnesses](#other-harnesses).\n\n### Method 2: Step-by-Step Install\n\nIf you prefer to understand each step, follow along below.\n\n#### Step 1: Install the Main CLI\n\n```bash\nnpm install -g @a5c-ai/babysitter@latest\n```\n\n**What this installs:**\n- `@a5c-ai/babysitter` - Recommended user-facing package for the `babysitter` CLI\n- `@a5c-ai/babysitter-sdk` - Installed as the underlying SDK/core CLI implementation\n\n**Expected output:**\n```\nadded 1 packages in 15s\n```\n\n**Verify installation:**\n```bash\nbabysitter --version\n```\n\nIf `babysitter` exists on PATH but fails with `MODULE_NOT_FOUND`, remove the stale global shim and reinstall the SDK-backed CLI:\n\n```bash\nnpm rm -g @a5c-ai/babysitter @a5c-ai/babysitter-sdk\nnpm install -g @a5c-ai/babysitter-sdk@latest\nbabysitter --version\n```\n\n#### Step 2: Install the Adapters CLI (host-side track)\n\nThe **Adapters CLI** (`adapters`) is a host-side binary for running and managing harnesses directly from your shell. It is published separately as `@a5c-ai/adapters-cli` (version **6.0.0**) and needs **Node >=20.9.0**:\n\n```bash\nnpm install -g @a5c-ai/adapters-cli\n```\n\n**Verify and try an Adapter immediately:**\n\n```bash\nadapters version\nadapters doctor\nadapters run claude \"explain this repository in two sentences\"\n```\n\n`adapters doctor` runs an environment health check; `adapters run claude \"...\"` runs the Claude harness with a single prompt. See the [Adapters CLI Reference](../reference/adapters-cli.md) for every command.\n\n#### Step 3: Install the Optional Runtime CLI\n\nInstall this only if you need `genty` commands for headless orchestration, the internal harness, daemon utilities, MCP serving, or the TUI:\n\n```bash\nnpm install -g @a5c-ai/genty-platform@latest\n```\n\n**Verify installation:**\n```bash\ngenty --version\n```\n\n#### Step 4: Install the Claude Code Plugin\n\nThe plugin integrates Babysitter with Claude Code and enables the `/babysitter:*` slash-command surface. For any other harness, see [Other Harnesses](#other-harnesses) and the [Install Matrix](../harnesses/install-matrix.md).\n\n```bash\n# Add the plugin repository\nclaude plugin marketplace add a5c-ai/babysitter-claude\n\n# Install the plugin\nclaude plugin install --scope user babysitter@a5c.ai\n\n# Enable the plugin\nclaude plugin enable --scope user babysitter@a5c.ai\n```\n\n**Expected output:**\n```\nPlugin 'babysitter@a5c.ai' installed successfully\nPlugin 'babysitter@a5c.ai' enabled\n```\n\n#### Step 5: Restart Claude Code\n\n**Important:** You must restart Claude Code for the plugin to load.\n\n- Close all Claude Code windows/sessions\n- Reopen Claude Code\n\n---\n\n## Platform-Specific Instructions\n\n### macOS\n\n**Prerequisites:**\n```bash\n# Install Homebrew if you don't have it\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# Install Node.js via nvm (recommended)\nbrew install nvm\nmkdir ~/.nvm\necho 'export NVM_DIR=\"$HOME/.nvm\"' >> ~/.zshrc\necho '[ -s \"/opt/homebrew/opt/nvm/nvm.sh\" ] && \\. \"/opt/homebrew/opt/nvm/nvm.sh\"' >> ~/.zshrc\nsource ~/.zshrc\n\nnvm install 22\nnvm use 22\n```\n\n**Installation:**\n```bash\nnpm install -g @a5c-ai/babysitter@latest @a5c-ai/adapters-cli\n```\n\n**Permission Issues?**\nIf you see `EACCES` permission errors:\n\n```bash\n# Option 1: Fix npm permissions (recommended)\nmkdir ~/.npm-global\nnpm config set prefix '~/.npm-global'\necho 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc\nsource ~/.zshrc\n\n# Then retry installation\nnpm install -g @a5c-ai/babysitter@latest @a5c-ai/adapters-cli\n```\n\n### Linux\n\n**Ubuntu/Debian:**\n```bash\n# Install Node.js via NodeSource\ncurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -\nsudo apt-get install -y nodejs\n\n# Verify\nnode --version  # Should show v22.x.x\n\n# Install Babysitter + Adapters CLI\nnpm install -g @a5c-ai/babysitter@latest @a5c-ai/adapters-cli\n```\n\n**Fedora/RHEL/CentOS:**\n```bash\n# Install Node.js via NodeSource\ncurl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -\nsudo yum install -y nodejs\n\n# Install Babysitter + Adapters CLI\nnpm install -g @a5c-ai/babysitter@latest @a5c-ai/adapters-cli\n```\n\n**Arch Linux:**\n```bash\nsudo pacman -S nodejs npm\nnpm install -g @a5c-ai/babysitter@latest @a5c-ai/adapters-cli\n```\n\n### Windows\n\n**Recommended: Use WSL2 (Windows Subsystem for Linux)**\n\nWSL2 provides the best experience for Babysitter on Windows:\n\n```powershell\n# In PowerShell (Admin)\nwsl --install\n\n# Restart your computer, then open Ubuntu from Start Menu\n# Follow the Linux (Ubuntu) instructions above\n```\n\n**Native Windows (Git Bash):**\n\n1. Install [Node.js for Windows](https://nodejs.org/en/download/)\n2. Install [Git for Windows](https://git-scm.com/download/win) (includes Git Bash)\n3. Open Git Bash and run:\n\n```bash\nnpm install -g @a5c-ai/babysitter@latest @a5c-ai/adapters-cli\n```\n\n**Note:** Some shell commands in Babysitter may require Git Bash or WSL. PowerShell/CMD support is limited.\n\n---\n\n## Plugin Installation\n\nThe Claude Code plugin provides the `/babysitter:*` command surface that orchestrates Babysitter runs.\n\n### Install the Plugin\n\n```bash\n# Step 1: Add the marketplace repository\nclaude plugin marketplace add a5c-ai/babysitter-claude\n```\n\n**Expected:** `Marketplace 'a5c.ai' added`\n\n```bash\n# Step 2: Install the plugin\nclaude plugin install --scope user babysitter@a5c.ai\n```\n\n**Expected:** `Plugin 'babysitter@a5c.ai' installed`\n\n```bash\n# Step 3: Enable the plugin\nclaude plugin enable --scope user babysitter@a5c.ai\n```\n\n**Expected:** `Plugin 'babysitter@a5c.ai' enabled`\n\n### Verify Plugin Installation\n\nAfter restarting Claude Code, run:\n\n```\n/skills\n```\n\nYou should see **\"babysit\"** in the list of available skills.\n\nIf you don't see it:\n1. Make sure you restarted Claude Code\n2. Try running `claude plugin list` to see installed plugins\n3. Check the [Troubleshooting](#troubleshooting) section\n\n---\n\n## Other Harnesses\n\nClaude Code is the worked example above, but Babysitter v6 supports **12 harnesses**. The two fully-worked harnesses have dedicated pages:\n\n- **[Claude Code](../harnesses/claude-code.md)** — `/babysitter:*` slash-commands and the `babysit` skill\n- **[Codex](../harnesses/codex.md)** — `$babysitter:*` via the mention picker\n\nFor **every** harness (antigravity, cursor, gemini, genty, github-copilot, hermes, omp, openclaw, opencode, pi, plus the two above), the [**Install Matrix**](../harnesses/install-matrix.md) lists the exact install command, the in-session invocation token, and the per-harness hook/continuation model.\n\nThe universal installer works for any harness — the argument is the **harness key**, which may differ from the harness name (e.g. `gemini-cli`, `github-copilot`, `oh-my-pi`, `antigravity-cli`):\n\n```bash\nbabysitter harness:install-plugin <harness-key> [--workspace <path>]\n```\n\nFor example:\n\n```bash\nbabysitter harness:install-plugin codex\nbabysitter harness:install-plugin cursor --workspace /path/to/repo\n```\n\n> Each harness ships its own published plugin and its own version — do not pin a pre-release build. Per-harness continuation models differ: only Claude Code, Codex, and Cursor use a `Stop` hook; antigravity and gemini use `AfterAgent`, openclaw uses a session daemon, opencode uses session-idle, hermes uses ACP, and genty/omp/pi are thin skill-alias surfaces. See each harness's row in the [Install Matrix](../harnesses/install-matrix.md).\n\n---\n\n## Recommended Tools\n\nThe following tools enhance your workflow when using Babysitter. These are optional but highly recommended for a more productive development experience.\n\n### Playwright Skill Plugin\n\n**Browser automation for testing and validation**\n\nThe Playwright Skill Plugin enables Claude to write and execute browser automation tests, take screenshots, fill forms, and validate web applications. This is essential for testing web applications and verifying UI functionality during development.\n\n**Why use it:**\n- Automate browser-based testing directly through Claude\n- Capture screenshots for visual validation\n- Test form submissions and user interactions\n- Verify web application behavior without leaving your terminal\n\n**Installation:**\n\nRun these commands in Claude Code CLI:\n\n```bash\n# Add the plugin from marketplace\n/plugin marketplace add lackeyjb/playwright-skill\n\n# Install the skill\n/plugin install playwright-skill@playwright-skill\n\n# Run setup to configure Playwright browsers\ncd ~/.claude/plugins/marketplaces/playwright-skill/skills/playwright-skill && npm run setup\n```\n\n> **Note:** Restart Claude Code after installation to activate the plugin.\n\n### GitHub CLI (gh)\n\n**Official GitHub command-line interface**\n\nThe GitHub CLI allows Claude to seamlessly manage GitHub issues, pull requests, actions, and releases through natural language. Claude can create PRs, manage issues, check CI status, and debug GitHub Actions failures directly from the terminal.\n\n**Why use it:**\n- Create and manage pull requests without leaving your workflow\n- Track and update issues through natural language commands\n- Monitor CI/CD pipeline status and debug failures\n- Manage releases and repository settings efficiently\n\n**Installation:**\n\n```bash\n# macOS\nbrew install gh\n\n# Linux (Debian/Ubuntu)\nsudo apt install gh\n\n# Linux (Fedora/RHEL)\nsudo dnf install gh\n\n# Windows\nwinget install GitHub.cli\n```\n\n**Post-installation:**\n\nAuthenticate with your GitHub account:\n\n```bash\ngh auth login\n```\n\nFollow the interactive prompts to complete authentication. This grants Claude access to manage your repositories and perform GitHub operations on your behalf.\n\n---\n\n## Verification\n\nLet's confirm everything is working correctly.\n\n### Verification Checklist\n\nRun each command and verify the expected result:\n\n#### 1. Core CLI Installed\n```bash\nbabysitter --version\n```\n**Expected:** The v6 release version (`6.0.0` for this edition)\n\n#### 2. Adapters CLI Installed (host-side track)\n```bash\nadapters version\nadapters doctor\n```\n**Expected:** `adapters version` reports `6.0.0`; `adapters doctor` reports all checks passing.\n\n#### 3. Try an Adapter\n```bash\nadapters run claude \"say hi\"\n```\n**Expected:** The harness responds. (Swap `claude` for any other installed harness.)\n\n#### 4. Optional Runtime CLI Installed\n\nIf you installed `@a5c-ai/genty-platform`:\n\n```bash\ngenty --version\n```\n\n**Expected:** The v6 release version (`6.0.0`)\n\n#### 5. Plugin Active\nIn Claude Code, type:\n```\n/skills\n```\n**Expected:** \"babysit\" appears in the list\n\n#### 6. Full Integration Test\nIn Claude Code:\n```\n/babysitter:call echo hello world\n```\n**Expected:** Babysitter creates a run and executes successfully. (Other harnesses use their own invocation token — see the [Install Matrix](../harnesses/install-matrix.md).)\n\n### Verification Summary\n\n| Check | Command | Expected |\n|-------|---------|----------|\n| jq | `jq --version` | jq-1.6 or higher |\n| Core CLI | `babysitter --version` | `6.0.0` |\n| Adapters CLI | `adapters version` | `6.0.0` |\n| Adapter health | `adapters doctor` | All checks pass |\n| Try an Adapter | `adapters run claude \"say hi\"` | The harness responds |\n| Runtime CLI | `genty --version` | `6.0.0` if installed |\n| Plugin (Claude Code) | `/skills` in Claude Code | \"babysit\" listed |\n\n**All checks passed?** You're ready for the [Quickstart](./quickstart.md)!\n\n---\n\n## Keeping Updated\n\nBabysitter is actively developed. Keep your installation current for the latest features and fixes.\n\n### Update CLI Packages\n\n```bash\nnpm update -g @a5c-ai/babysitter @a5c-ai/adapters-cli @a5c-ai/genty-platform\n```\n\n### Update Claude Code Plugin\n\n```bash\n# Update the marketplace repository\nclaude plugin marketplace update a5c.ai\n\n# Update the plugin\nclaude plugin update babysitter@a5c.ai\n```\n\nFor other harnesses, re-run `babysitter harness:install-plugin <harness-key>` or follow the update note on that harness's row in the [Install Matrix](../harnesses/install-matrix.md).\n\n**Tip:** Run updates regularly, ideally daily or weekly.\n\n### Check Current Versions\n\n```bash\n# Core CLI version\nbabysitter --version\n\n# Adapters CLI version\nadapters version\n\n# Runtime CLI version (if installed)\ngenty --version\n\n# Plugin version\nclaude plugin list | grep babysitter\n```\n\n---\n\n## Upgrading from a Prior Version\n\nComing from the prod `0.0.x` series? v6 is a semver-major jump with breaking changes (package renames, removed flags such as `--plugin-root`, `BABYSITTER_SESSION_ID` → `AGENT_SESSION_ID`, and `plugins/` → `blueprints/`). Follow the **[Migration Guide](./migration.md)** before upgrading.\n\n---\n\n## Troubleshooting\n\n### Installation Issues\n\n#### \"command not found: npm\" or \"command not found: node\"\n\n**Problem:** Node.js is not installed or not in your PATH.\n\n**Solution:**\n1. Install Node.js from [nodejs.org](https://nodejs.org/)\n2. Restart your terminal\n3. Verify: `node --version`\n\n#### \"EACCES: permission denied\" during npm install\n\n**Problem:** npm doesn't have permission to install global packages.\n\n**Solution (macOS/Linux):**\n```bash\n# Create a directory for global packages\nmkdir ~/.npm-global\nnpm config set prefix '~/.npm-global'\n\n# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)\necho 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc\nsource ~/.zshrc\n\n# Retry installation\nnpm install -g @a5c-ai/babysitter@latest @a5c-ai/adapters-cli\n```\n\n#### \"adapters: command not found\"\n\n**Problem:** The Adapters CLI is not installed, or your Node version is below 20.9.0.\n\n**Solution:**\n```bash\nnode --version   # must be >=20.9.0\nnpm install -g @a5c-ai/adapters-cli\nadapters version\n```\n\n#### \"Cannot find module '@a5c-ai/babysitter-sdk'\"\n\n**Problem:** You are importing the SDK in code, but `@a5c-ai/babysitter-sdk` is not installed in that project.\n\n**Solution:**\n```bash\n# Install the SDK as a project dependency when authoring custom processes\nnpm install @a5c-ai/babysitter-sdk\n\n# Verify the main CLI separately\nbabysitter --version\n```\n\n### Plugin Issues\n\n#### Plugin not appearing in /skills\n\n**Problem:** Plugin not installed, not enabled, or Claude Code not restarted.\n\n**Solution:**\n```bash\n# Check if installed\nclaude plugin list\n\n# If not listed, install\nclaude plugin marketplace add a5c-ai/babysitter-claude\nclaude plugin install --scope user babysitter@a5c.ai\nclaude plugin enable --scope user babysitter@a5c.ai\n\n# Restart Claude Code completely\n```\n\n#### \"Plugin not found: babysitter@a5c.ai\"\n\n**Problem:** Plugin repository not added.\n\n**Solution:**\n```bash\n# Add the marketplace first\nclaude plugin marketplace add a5c-ai/babysitter-claude\n\n# Then install\nclaude plugin install --scope user babysitter@a5c.ai\n```\n\nFor harness-specific install problems on any other harness, see that harness's row in the [Install Matrix](../harnesses/install-matrix.md) and the session-binding section of [Troubleshooting](../reference/troubleshooting.md).\n\n### Runtime Issues\n\n#### \"Run encountered an error\"\n\n**Problem:** Journal conflict or corrupted state.\n\n**Solution:**\n```bash\n# Inspect the journal — it is one JSON file per event (not a single .jsonl)\nls .a5c/runs/<runId>/journal/\n\n# Read the first event\ncat .a5c/runs/<runId>/journal/000001.*.json | jq .\n\n# Ask Claude to analyze\nclaude \"Analyze the babysitter run error for <runId> and try to recover\"\n```\n\n### Getting More Help\n\nIf you're still stuck:\n\n1. **Check the logs:** Look for error messages in terminal output\n2. **Search issues:** [GitHub Issues](https://github.com/a5c-ai/babysitter/issues)\n3. **Ask the community:** [GitHub Discussions](https://github.com/a5c-ai/babysitter/discussions)\n4. **Report a bug:** Create a new issue with:\n   - Your OS and version\n   - Node.js version\n   - Claude Code version\n   - Full error message\n   - Steps to reproduce\n\n---\n\n## Quick Reference\n\nCommands you'll use most often:\n\n```bash\n# Run a harness directly from your shell (host-side Adapters track)\nadapters run claude \"<your request>\"\n\n# Start a new in-session run (Claude Code)\n/babysitter:call <your request>\n\n# Resume a run (Claude Code)\n/babysitter:resume\n\n# Install a plugin for another harness\nbabysitter harness:install-plugin <harness-key>\n\n# Update everything\nnpm update -g @a5c-ai/babysitter @a5c-ai/adapters-cli @a5c-ai/genty-platform\nclaude plugin update babysitter@a5c.ai\n```\n\n---\n\n## Next steps\n\n- **Next:** [Quickstart](./quickstart.md) — build your first feature in 10 minutes\n- **Previous:** [Getting Started overview](./README.md)\n- **Related:** [Install Matrix](../harnesses/install-matrix.md) — setup and command token for every supported harness\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide-getting-started",
      "to": "page:docs-user-guide-getting-started-installation",
      "kind": "contains_page"
    }
  ]
}