\___/
( •_•)
/)🦀(\
< >
A lightning-fast tmux-based workspace manager for multi-repo development. Manage multiple projects, start full dev environments in seconds.
# 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 1Run 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 projectsUse crab (or crabcode) for all commands.
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 windowcrab <N> # Shorthand for: crab ws <N>
crab restart # Restart current workspace
crab cleanup # Cleanup current workspace
crab continue # Continue current workspaceSave 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 stateThe global WIP list shows:
- Summary (AI-generated from your changes)
- Workspace number, branch, file count
- Commits ahead of origin/main
- Timestamp
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 archiveOptions: --include-git, --include-deps, --port=8080
Auto-excludes: node_modules, .git, vendor, venv, dist, build...
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 nameSetup: Add to your project config (~/.crabcode/projects/<alias>.yaml):
slack:
bot_token: xoxb-your-bot-token
display_name: "Your Name" # optional, defaults to git configMessages appear with 🦀 icon and show [Your Name] message so recipients know who sent it.
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 defaultProject configs live in ~/.crabcode/projects/<alias>.yaml. When you run commands from a workspace directory, crabcode auto-detects which project you're in.
crab init # Register a project (3 questions)
crab config scan # Auto-detect .env files and ports
crab config # Show current configurationAI-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 uninstall # Remove the pluginSupported 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.
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 reviewersCourt Review uses the judge pattern:
- Judge (Claude): Orchestrates, verifies findings, delivers verdict
- Reviewer A (Claude teammate): Independent code review
- Reviewer B (Codex): Independent code review
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 sessioncrab doctor # Diagnose issues
crab ports # Show port usage
crab shared # Show shared volume info
crab cheat # Show cheat sheetcd ~/Dev/my-project
crab initYou'll be asked 3 questions:
- Main repo path - where your project lives (defaults to current dir)
- Project alias - short name like
pf,cb(defaults to repo dirname) - Workspace directory - where to create worktrees (defaults to
<repo>-workspaces)
This creates ~/.crabcode/projects/<alias>.yaml.
crab config scanThis scans your repo for .env and .env.example files, finds port variables, and offers to add them to your config.
Edit ~/.crabcode/projects/<alias>.yaml to set:
- Layout panes - your dev server command, main tool
- Shared volume - persistent storage across resets
- Submodules - if your project has git submodules
cd ~/Dev/another-project
crab init # → alias: another
crab projects # see both projects~/.crabcode/
config.yaml # global prefs (default_project)
projects/
pf.yaml # per-project config
cb.yaml # per-project config
wip/
pf/ # per-project WIP isolation
cb/
Per-project config (~/.crabcode/projects/<alias>.yaml):
session_name: pf
workspace_base: ~/Dev/my-project-workspaces
main_repo: ~/Dev/my-project
workspaces:
prefix: ws
branch_pattern: workspace-{N}
# Auto-detected by 'crab config scan'
env_sync:
files:
- path: server/.env
ports: [API_PORT, ADMIN_PORT]
- path: app/.env
ports: [VITE_PORT]
layout:
panes:
- name: terminal
command: ""
- name: server
command: pnpm dev
- name: main
command: claude
# Optional: persistent storage across resets
shared_volume:
enabled: true
path: ~/.crabcode/shared
link_as: .local
# Optional: git submodule handling
submodules:
- path: my-submodule
reset_to: origin/main
install_command: pnpm installSee examples/ for more configuration examples.
Core:
- bash
- tmux
- git
- yq (YAML parsing)
- zip (for toolkit share)
For PR reviews (crab review, crab court):
- gh (GitHub CLI)
- Claude Code (
claudeCLI)
Optional (for court review with Codex):
- Codex CLI (
npm install -g @openai/codex)
# macOS
brew install tmux yq zip gh
npm install -g @anthropic-ai/claude-code # Claude Code
# Ubuntu/Debian
apt install tmux yq zip gh
npm install -g @anthropic-ai/claude-codecurl -fsSL https://raw.githubusercontent.com/promptfoo/crabcode/main/install.sh | bashgit clone https://github.com/promptfoo/crabcode.git
cd crabcode
chmod +x src/crabcode
sudo ln -s $(pwd)/src/crabcode /usr/local/bin/crabcode
sudo ln -s $(pwd)/src/crabcode /usr/local/bin/crab# If installed via one-liner, just run it again:
curl -fsSL https://raw.githubusercontent.com/promptfoo/crabcode/main/install.sh | bash
# If installed manually from git:
cd /path/to/crabcode
git pull origin main┌─────────────────────────┬─────────────────────────┐
│ terminal │ │
│ (shell) │ main │
├─────────────────────────┤ (claude/editor) │
│ server │ │
│ (pnpm dev) │ │
└─────────────────────────┴─────────────────────────┘
With prefix Ctrl+a:
| Keys | Action |
|---|---|
Option+1,2,3... |
Switch to workspace |
Ctrl+a n/p |
Next/previous window |
Ctrl+a d |
Detach |
Ctrl+a z |
Toggle zoom |
Option+arrows |
Navigate panes |
-
Install dependencies:
brew install tmux yq zip git # macOS -
Install crabcode:
curl -fsSL https://raw.githubusercontent.com/promptfoo/crabcode/main/install.sh | bash -
Add to PATH (if needed):
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc source ~/.zshrc
-
Clone your project:
git clone --recursive git@github.com:your-org/your-project.git ~/Dev/your-project -
Setup crabcode:
cd ~/Dev/your-project crab init # 3 questions: repo path, alias, workspace dir crab config scan # auto-detect .env files and ports
-
Edit config for your project:
# Set your layout commands in ~/.crabcode/projects/<alias>.yaml # - server pane: your dev server (e.g., pnpm dev) # - main pane: your main tool (e.g., claude)
-
Start working:
crab ws 1
With branches, switching context means stashing changes, checking out, reinstalling deps, and restarting servers. With worktrees, each workspace is a separate directory - switch instantly by changing tmux windows. No stashing, no reinstalling, no waiting.
Yes! Each project gets an alias and its own config at ~/.crabcode/projects/<alias>.yaml. Run crab init in each project directory. Use crab @alias <cmd> to target a specific project, or just run commands from a workspace directory — crabcode auto-detects which project you're in.
crab @pf ws 1 # explicit project
crab ws 1 # uses default or auto-detects from cwd
crab projects # see all registered projects
crab default pf # set default projectcrab ws <N> cleanup # Reset single workspace to origin/main
crab ws <N> destroy # Completely remove workspace and worktreeCompletely unrelated projects with similar names:
| Crabcode | Clawdbot | |
|---|---|---|
| Purpose | Workspace manager | Personal AI assistant |
| Tech | Bash, tmux, Git worktrees | Node.js, WebSockets |
| Use case | Parallel development environments | Messaging integrations |
MIT