# Crabcode 🦀

```
     \___/
    ( •_•)
   /)🦀(\
  <      >
```

> Lightning-fast tmux workspace manager for multi-repo development

Crabcode creates isolated development workspaces using git worktrees and tmux. Each workspace gets its own branch, ports, and tmux layout. Manage multiple projects from a single install. Switch between tasks instantly without losing context.

## Installation

```bash
# Prerequisites
brew install tmux yq zip gh   # macOS
# apt install tmux yq zip gh  # Linux

# Install crabcode
curl -fsSL https://raw.githubusercontent.com/promptfoo/crabcode/main/install.sh | bash
```

## Setup

```bash
cd ~/Dev/my-project
crab init           # 3 questions: repo path, alias, workspace dir
crab config scan    # auto-detect .env files and ports
crab ws 1           # start first workspace
```

## Usage

### Workspaces

```bash
crab ws 1              # Open/create workspace 1
crab ws new            # Create next available workspace
crab ws                # List all workspaces
crab restart           # Reset git + restart panes
crab cleanup           # Full teardown, reset to origin/main
```

### Multi-Project

Manage multiple repos from a single crabcode install. Each project gets an alias.

```bash
crab @pf ws 1            # Open workspace 1 for project "pf"
crab @cb config          # Show config for project "cb"
crab ws 1                # Uses default project (or detects from cwd)
crab projects            # List all registered projects
crab projects rm <alias> # Remove a project registration
crab default pf          # Set default project
```

Project configs live in `~/.crabcode/projects/<alias>.yaml`. Commands auto-detect which project you're in based on cwd.

### Save & Restore Work

```bash
crab wip save          # Save current changes
crab wip save --restart  # Save then restart workspace
crab wip --continue    # Restore most recent saved state
crab wip --resume      # Interactive selection of saved states
crab wip ls            # List all saved states globally
```

### PR Review & Court

Two modes for reviewing pull requests:

```bash
# Quick single-agent review
crab review 3230                    # PR number
crab review promptfoo#456           # Submodule PR
crab review https://github.com/...  # Full URL

# Court review - multi-agent tribunal with judge pattern
crab court 3230                     # Judge + 2 reviewers
```

Court review uses the judge pattern: a Codex-led judge by default orchestrates two independent review passes, verifies every finding against actual code, resolves disagreements, and delivers a verdict with zero false positives.

```bash
crab review ls              # List review sessions
crab review show <PR>       # View saved review output
crab review resume <PR>     # Resume a review
crab review delete <PR>     # Delete a review session
crab review delete --all    # Delete all review sessions
```

### Ticket Integration

Create workspaces from Linear ticket identifiers with automatic context injection:

```bash
crab ticket ENG-123          # Provision workspace from ticket
crab ws 3 ticket ENG-123     # Bind ticket to specific workspace
```

### P2P Messaging

Peer-to-peer messaging via self-hosted relay server:

```bash
crab msg start               # Start relay server
crab msg @user "message"     # Send message to peer
crab msg read                # View inbox
crab msg listen              # Real-time message stream
crab msg say on/off          # Toggle text-to-speech for incoming messages
crab msg history             # View message history
crab msg stop                # Stop relay server
```

### Share Files

```bash
crab tk share <path>                      # Upload → temp URL
crab tk share <path> --to slack:#channel  # Share to Slack
crab tk share <path> --to ssh:user@host   # SSH transfer
crab tk share <path> --to email:addr      # Email attachment
crab tk share <path> --serve              # Local HTTP + QR code
```

### Slack Integration

```bash
crab slack @user "message"    # Send DM
crab slack #channel "message" # Post to channel
crab slack read @user         # View recent messages
crab slack chat @user         # Interactive terminal chat
crab slack sent               # View sent messages log
crab slack users              # List workspace users
```

Requires `slack.bot_token` in project config.

### Command Aliases

Define custom shorthand for frequently-used workflows:

```bash
crab alias set rr restart    # Set alias
crab alias set d "ws 1"      # Multi-word commands
crab alias                   # List all aliases
crab alias rm rr             # Remove alias
```

### Session Management

Track and resume named agent conversations:

```bash
crab session ls              # List sessions
crab session start "name"    # Start named session
crab session resume "name"   # Resume existing session
crab session delete "name"   # Delete a session
```

### Other Commands

```bash
crab config            # Show current configuration
crab config scan       # Auto-detect .env files and ports
crab ports             # Show port usage across workspaces
crab shared            # Show shared volume info
crab doctor            # Diagnose issues
crab cheat             # Show cheat sheet
```

## Configuration

```
~/.crabcode/
  config.yaml              # global prefs (default_project, aliases)
  projects/
    pf.yaml                # per-project config
    cb.yaml                # per-project config
  wip/
    pf/                    # per-project WIP isolation
    cb/
  sessions/
    pf/                    # per-project session storage
```

Per-project config (`~/.crabcode/projects/<alias>.yaml`):

```yaml
session_name: pf
agent: codex
workspace_base: ~/Dev/my-project-workspaces
main_repo: ~/Dev/my-project

workspaces:
  prefix: ws
  branch_pattern: workspace-{N}

# Port isolation (auto-detected by 'crab config scan')
env_sync:
  files:
    - path: server/.env
      ports: [API_PORT, ADMIN_PORT]
    - path: app/.env
      ports: [VITE_PORT]

# Tmux pane layout
layout:
  panes:
    - name: terminal
      command: ""
    - name: server
      command: pnpm dev
    - name: main
      command: ""   # defaults to codex --full-auto

# Persistent storage across workspace resets
shared_volume:
  enabled: true
  path: ~/.crabcode/shared
  link_as: .local

# Slack integration
slack:
  bot_token: xoxb-your-bot-token
  display_name: "Your Name"
```

## Concepts

- **Workspace**: Isolated git worktree with its own branch, ports, and tmux session
- **WIP**: Save/restore your uncommitted changes across workspace resets
- **Shared Volume**: A `.local/` folder that persists across resets for experiments
- **Port Isolation**: Each workspace gets offset ports (ws1: 3001, ws2: 3002, etc.)
- **Court Review**: Multi-agent PR review using the judge pattern (judge + 2 reviewers)
- **P2P Messaging**: Self-hosted relay for developer-to-developer messaging with TTS
- **Command Aliases**: User-defined shorthand stored in global config

## Tmux Layout

```
┌─────────────────────────┬─────────────────────────┐
│      terminal           │                         │
│      (shell)            │        main             │
├─────────────────────────┤   (codex/editor)        │
│      server             │                         │
│      (pnpm dev)         │                         │
└─────────────────────────┴─────────────────────────┘
```

Keybindings (prefix: `Ctrl+a`):
- `Option+1,2,3...` - Switch workspace
- `Ctrl+a n/p` - Next/prev window
- `Ctrl+a z` - Toggle zoom
- `Option+arrows` - Navigate panes

## Requirements

**Core:** bash, tmux, git, [yq](https://github.com/mikefarah/yq), zip

**For PR reviews:** [gh](https://cli.github.com/) (GitHub CLI), [Codex CLI](https://github.com/openai/codex) (`codex` CLI)

## Links

- Website: https://crabcode.dev
- GitHub: https://github.com/promptfoo/crabcode
