Crabcode 🦀

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

A lightning-fast tmux-based workspace manager for multi-repo development, built around Codex CLI. Manage multiple projects, start full dev environments in seconds.

Quick Start

# 1. Install dependencies
brew install tmux yq    # macOS
# apt install tmux yq   # Linux

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

# 3. Register your project (3 questions: repo path, alias, workspace dir)
cd ~/Dev/my-project
crab init              # → alias: myproj

# 4. Auto-detect .env files and ports
crab config scan

# 5. Start your first workspace
crab ws 1

What It Does

Run crab ws 1 and get:

• Git worktree created from your main repo
• A dedicated branch (e.g., workspace-1)
• Isolated ports per workspace (auto-detected from .env files)
• Tmux window with terminal, server, and your preferred tools
• Shared volume for local experiments (.local/)

Managing multiple projects? Each gets its own alias:

crab @pf ws 1          # promptfoo-cloud workspace
crab @cb ws 1          # crabcode workspace
crab projects          # list all registered projects

Commands

Use crab (or crabcode) for all commands.

Workspace Commands (crab ws)

crab ws                  # List all workspaces
crab ws new              # Create next available workspace
crab ws <N>              # Open/create workspace N
crab ws <N> restart      # Reset git + restart panes
crab ws <N> cleanup      # Kill window + reset to origin/main
crab ws <N> continue     # Resume with --continue flag
crab ws <N> --separate   # Open in new terminal window

Shortcuts (auto-detect workspace)

crab <N>                 # Shorthand for: crab ws <N>
crab restart             # Restart current workspace
crab cleanup             # Cleanup current workspace
crab continue            # Continue current workspace

WIP Commands (crab wip)

Save and restore work across workspace resets. WIPs are stored globally with rich metadata:

crab wip save            # Save current changes
crab wip save --restart  # Save then restart
crab wip ls              # List all WIPs globally with metadata
crab wip restore         # Interactive restore from all WIPs
crab wip restore <N>     # Restore WIP #N to original workspace
crab wip restore <N> --to <ws>  # Restore to different workspace
crab wip --continue      # Restore most recent WIP (current workspace)
crab wip delete <name>   # Delete a WIP state

The global WIP list shows:

• Summary (AI-generated from your changes)
• Workspace number, branch, file count
• Commits ahead of origin/main
• Timestamp

Toolkit Commands (crab tk)

Share files and folders:

crab tk share <path>                      # Upload → temp URL
crab tk share <path> --to ssh:user@host   # SSH transfer
crab tk share <path> --to slack:#channel  # Slack upload
crab tk share <path> --to email:addr      # Email attachment
crab tk share <path> --serve              # Local HTTP server + QR
crab tk share <path> --zip                # Just create archive

Options: --include-git, --include-deps, --port=8080

Auto-excludes: node_modules, .git, vendor, venv, dist, build...

Slack Commands (crab slack)

Quick messaging from terminal:

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 your sent messages log
crab slack users                 # List workspace users
crab slack users mike            # Search by name

Setup: Add to your project config (~/.crabcode/projects/<alias>.yaml):

slack:
  bot_token: xoxb-your-bot-token
  display_name: "Your Name"  # optional, defaults to git config

Messages appear with 🦀 icon and show [Your Name] message so recipients know who sent it.

Multi-Project Commands

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

crab init                # Register a new project (asks for alias)
crab init -t <template>  # Register with a template
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
crab default             # Show current default

Project configs live in ~/.crabcode/projects/<alias>.yaml. When you run commands from a workspace directory, crabcode auto-detects which project you're in.

Config Commands

crab init                # Register a project (3 questions)
crab config scan         # Auto-detect .env files and ports
crab config              # Show current configuration

Promptfoo Target Discovery (crab pf)

AI-powered agent that analyzes any target and generates working promptfoo configurations.

crab pf install                              # Install the plugin
crab pf --file target.txt                    # Analyze from file
crab pf "curl -X POST http://..."            # Analyze curl command
crab pf --file api.json --output ./config    # Specify output dir
crab pf --file spec.yaml --verbose           # Show detailed output
crab pf --reasoning high                     # Set reasoning effort (low/medium/high)
crab pf uninstall                            # Remove the plugin

Supported formats: curl commands, OpenAPI specs, Postman collections, Burp exports, plain text descriptions

Requirements: Node.js, OPENAI_API_KEY or ANTHROPIC_API_KEY

The agent probes the target, figures out the protocol (HTTP, WebSocket, polling, etc.), generates the config, and verifies it works. Defaults to GPT-5 with reasoning: low.

Slack Integration (crab pf serve)

Let non-technical team members run the discovery agent by DM'ing the Crab bot in Slack. Each user runs their own local daemon with their own API keys.

crab pf serve --setup          # One-time: set Slack username + provider
crab pf serve                  # Start the polling daemon
crab pf serve -v               # Start with verbose output

Users DM the bot with pf: prefix to trigger the agent:

pf: My API is at http://localhost:8080/chat, POST with JSON { "message": "the prompt" }

File attachments (API specs, curl commands) are also supported. Results are posted back to the Slack thread as downloadable files.

Tax Organizer (crab tax)

Tax document organizer and deterministic filing handoff generator for supported 2025 federal + California personal return scenarios.

crab tax install                               # Install the plugin
crab tax ./my-tax-docs                         # Process a folder of tax documents
crab tax ./my-tax-docs --output ./tax-output   # Write outputs to a directory
crab tax ./my-tax-docs --profile ./profile.json
crab tax uninstall                             # Remove the plugin

Supported inputs today: W-2, 1099-INT, 1099-DIV, 1098, 1099-B, 1099-R, 5498, 1099-composite, property-tax-bill

Outputs:

• taxpayer_profile.json
• documents.json
• reconciliation.json
• issues_to_review.json
• federal_return_inputs.json
• ca_return_inputs.json
• estimate_summary.json
• turbotax_handoff.md

See plugins/tax/README.md for plugin-specific details.

Modes:

• Mock extraction via .mock.json sidecars for deterministic fixture testing
• Live OpenAI extraction for supported PDFs/images when OPENAI_API_KEY is set
• Bounded agent research for unknown or unsupported forms using tool calls plus official-source web search

Current scope: single or MFJ, full-year California resident, no dependent-related federal credits, no RSU/ESPP handling, deterministic estimation for supported scenarios only

Excalidraw Whiteboard (crab draw)

Collaborative whiteboarding with real-time collab via Excalidraw.

crab draw install              # Install the plugin
crab draw new "architecture"   # Create a new session
crab draw open "architecture"  # Open an existing session
crab draw ls                   # List active sessions
crab draw delete "architecture" # Delete a session
crab draw uninstall            # Remove the plugin

Sessions support real-time collaboration — share the URL with teammates to draw together.

PR Review Commands (crab review, crab court)

Two modes for reviewing pull requests:

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

# Court review - thorough multi-agent review
crab court 3230                     # Judge + 2 reviewers

Court Review uses the judge pattern:

• Judge (Codex): Orchestrates, verifies findings, delivers verdict
• Reviewer A (teammate pass): Independent code review
• Reviewer B (Codex): Secondary review pass

The judge traces every finding to actual code, resolves disagreements, and produces a verdict with zero false positives.

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

Session Management (crab session)

Track and resume agent conversations across workspaces:

crab session start "feature-x"    # Start a named session
crab session resume "feature-x"   # Resume an existing session
crab session ls                   # List sessions with summaries
crab session delete "feature-x"   # Delete a sessio