@antistud/handrails-cli

Power tools for Claude Code — team memory, context sync, and session intelligence powered by Handrails.

Install

npm i -g @antistud/handrails-cli

Requires Node.js >= 18.

Quick Start

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

handrails login --api-key <key>

Get your API key at 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.

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.

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.

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

handrails config

View and update configuration.

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

handrails daemon

Start the bridge daemon for remote tool execution.

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.

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