# @antistud/handrails-cli

Power tools for Claude Code — team memory, context sync, and session intelligence powered by [Handrails](https://handrails.dev).

## Install

```bash
npm i -g @antistud/handrails-cli
```

Requires Node.js >= 18.

## Quick Start

```bash
# Authenticate with your Handrails API key
handrails login

# Initialize Handrails in your project
handrails init

# Check setup status
handrails status
```

After `handrails init`, your project gets:
- A local MCP server configured in `.mcp.json` for Claude Code
- Team CLAUDE.md template pulled and merged
- Team slash commands synced
- Session tracking hooks installed

## Commands

### `handrails login`

Authenticate with your Handrails API key.

```bash
handrails login --api-key <key>
```

Get your API key at [handrails.dev/api-keys](https://handrails.dev/api-keys). Supports multi-team authentication — run `login` with different keys to add multiple teams.

### `handrails init`

Initialize Handrails for the current project.

```bash
handrails init [--project-tag <tag>] [--team <teamId>] [--skip-hooks] [--skip-context]
```

| Option | Description |
|---|---|
| `--project-tag <tag>` | Custom project identifier (default: directory name) |
| `--team <teamId>` | Select team (required if multiple teams) |
| `--skip-hooks` | Skip Claude Code hook installation |
| `--skip-context` | Skip pulling team CLAUDE.md template |

### `handrails status`

Display authentication, project configuration, Claude Code integration, and hook status.

### `handrails context`

Manage your project's CLAUDE.md and slash commands.

```bash
handrails context show           # Display current CLAUDE.md
handrails context pull           # Pull team template and merge
handrails context push           # Push local context to team
handrails context sync-commands  # Sync slash commands (--direction pull|push|both)
```

Team-managed sections in CLAUDE.md are preserved separately from your local customizations.

### `handrails sync`

Sync team MCP server configurations to your project.

```bash
handrails sync [--project-dir <dir>] [--dry-run]
```

### `handrails config`

View and update configuration.

```bash
handrails config get [key]       # Show config (or specific key)
handrails config set <key> <value>
```

### `handrails daemon`

Start the bridge daemon for remote tool execution.

```bash
handrails daemon [--api-url <url>] [--api-key <key>]
```

Connects via WebSocket to Handrails for remote file, shell, and git operations. Auto-reconnects with exponential backoff.

### `handrails rig`

Start a stateless executor for autonomous agent tasks.

```bash
handrails rig --rig-key <key> [--rig-type claude-code|opencode|codex] [--project <path>]
```

| Option | Description |
|---|---|
| `--rig-key <key>` | Rig key from dashboard (or `HANDRAILS_RIG_KEY` env) |
| `--rig-type <type>` | Executor type (default: from server) |
| `--project <path>` | Project directory (default: cwd) |
| `--interval <ms>` | Heartbeat interval (default: 10000) |
| `--skip-preflight` | Skip preflight checks |

## MCP Tools

When Claude Code runs with Handrails, these tools are available in your sessions:

| Tool | Description |
|---|---|
| `searchKnowledge` | Search team knowledge base |
| `storeDocument` | Store a document in the knowledge base |
| `pushInsight` | Store a categorized insight (bug-fix, pattern, decision, best-practice, etc.) |
| `readProjectContext` | Read CLAUDE.md split into team/local sections |
| `suggestContextUpdate` | Preview proposed CLAUDE.md changes |
| `getSlashCommands` | List available slash commands |
| `getRecentSessions` | List recent Claude Code sessions |
| `getProjectKnowledge` | Search team knowledge for current project |
| `getTeamActivity` | View recent team activity |

## Environment Variables

| Variable | Description |
|---|---|
| `HANDRAILS_API_KEY` | API key override |
| `HANDRAILS_RIG_KEY` | Rig key override |
| `HANDRAILS_API_URL` | API URL override |
| `HANDRAILS_PROJECT_PATH` | Project path override |

## Configuration

Global config is stored at `~/.handrails/config.json`. Project-level config lives in `.mcp.json`.

## License

MIT