c745d11870
- install.sh: Add xattr/codesign fix after cp on macOS - install.sh: Add portable timeout verification using perl - INSTALL.md: Recommend cargo install --path as primary method - INSTALL.md: Document macOS signature issue and fix - blue doctor: Detect com.apple.provenance xattr with fix hint - blue doctor: Verify code signature with codesign --verify - blue doctor: 3-second liveness timeout for hanging binaries Fixes dyld hang at _dyld_start when copied binaries have stale signatures after Homebrew library updates. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
151 lines
3.5 KiB
Markdown
151 lines
3.5 KiB
Markdown
# Installing Blue
|
|
|
|
## Quick Install (Recommended)
|
|
|
|
```bash
|
|
# Build and install Blue (handles code signing correctly)
|
|
cargo install --path apps/blue-cli
|
|
|
|
# Configure for Claude Code
|
|
blue install
|
|
```
|
|
|
|
Restart Claude Code after installation.
|
|
|
|
## Alternative: Build Then Install
|
|
|
|
If you prefer to build separately:
|
|
|
|
```bash
|
|
# Build Blue
|
|
cargo build --release
|
|
|
|
# Install for Claude Code (from build directory)
|
|
./target/release/blue install
|
|
```
|
|
|
|
Note: Running from `target/release/` works but the binary path may change after `cargo clean`. For a persistent installation, use `cargo install` above.
|
|
|
|
## What Gets Installed
|
|
|
|
`blue install` configures everything for Claude Code:
|
|
|
|
| Component | Location | Purpose |
|
|
|-----------|----------|---------|
|
|
| **Hooks** | `.claude/hooks/` | Session lifecycle, write guards |
|
|
| **Settings** | `.claude/settings.json` | Project configuration |
|
|
| **Skills** | `~/.claude/skills/` | Alignment dialogues |
|
|
| **MCP Server** | `~/.claude.json` | Blue tools for Claude |
|
|
|
|
### Hooks
|
|
|
|
- `session-start.sh` — Injects Blue context at session start
|
|
- `guard-write.sh` — Validates file writes (RFC 0038)
|
|
|
|
### Skills
|
|
|
|
- `alignment-play` — Run multi-expert alignment dialogues
|
|
- `alignment-expert` — Marker syntax for expert agents
|
|
|
|
### MCP Tools
|
|
|
|
After restart, Claude has access to Blue tools:
|
|
- `blue_status`, `blue_next` — Project state
|
|
- `blue_rfc_*` — RFC management
|
|
- `blue_worktree_*` — Git worktree coordination
|
|
- `blue_pr_create` — Pull request creation
|
|
- `blue_dialogue_*` — Alignment dialogues
|
|
|
|
## System-Wide Install
|
|
|
|
To make `blue` available everywhere:
|
|
|
|
```bash
|
|
# Recommended: cargo install handles signing correctly
|
|
cargo install --path apps/blue-cli
|
|
|
|
# The binary is installed to ~/.cargo/bin/blue
|
|
# Ensure ~/.cargo/bin is in your PATH
|
|
```
|
|
|
|
### Manual Copy (Not Recommended on macOS)
|
|
|
|
If you must copy the binary manually on macOS, you need to fix the code signature:
|
|
|
|
```bash
|
|
# Build
|
|
cargo build --release
|
|
|
|
# Copy and fix signature
|
|
sudo cp target/release/blue /usr/local/bin/
|
|
sudo xattr -cr /usr/local/bin/blue
|
|
sudo codesign --force --sign - /usr/local/bin/blue
|
|
```
|
|
|
|
Without the signature fix, the binary may hang at startup (see RFC 0060).
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
blue uninstall
|
|
```
|
|
|
|
Or manually:
|
|
|
|
```bash
|
|
# Remove hooks
|
|
rm -rf .claude/hooks/
|
|
|
|
# Remove MCP config
|
|
# Edit ~/.claude.json and remove "blue" entry
|
|
|
|
# Remove skills
|
|
rm ~/.claude/skills/alignment-play
|
|
rm ~/.claude/skills/alignment-expert
|
|
|
|
# Remove binary (if using cargo install)
|
|
cargo uninstall blue
|
|
|
|
# Remove Blue data (optional)
|
|
rm -rf .blue/
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Rust toolchain (cargo)
|
|
- macOS, Linux, or Windows with WSL
|
|
- Claude Code
|
|
|
|
## Verify Installation
|
|
|
|
```bash
|
|
# Check installation health
|
|
blue doctor
|
|
```
|
|
|
|
Or in Claude Code:
|
|
```
|
|
Human: blue status
|
|
Claude: [calls blue_status] Project: blue, Branch: develop...
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**"command not found: blue"**
|
|
- Use `cargo install --path apps/blue-cli` (adds to ~/.cargo/bin)
|
|
- Or run from the project directory: `./target/release/blue install`
|
|
- Ensure `~/.cargo/bin` is in your PATH
|
|
|
|
**Binary hangs on macOS (no output)**
|
|
- This is a code signature issue (RFC 0060)
|
|
- Fix: `xattr -cr $(which blue) && codesign --force --sign - $(which blue)`
|
|
- Or reinstall with: `cargo install --path apps/blue-cli --force`
|
|
|
|
**MCP tools not appearing in Claude**
|
|
- Restart Claude Code after installation
|
|
- Run `blue doctor` to check configuration
|
|
- Verify `blue mcp` runs without errors
|
|
|
|
**Hooks not firing**
|
|
- Check `.claude/hooks/` exists with executable scripts
|
|
- Run `blue install --force` to regenerate hooks
|