Crabcode 🦀

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

A lightning-fast tmux-based workspace manager for multi-repo development. 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 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.

Other Commands

crab doctor              # Diagnose issues
crab ports               # Show port usage
crab shared              # Show shared volume info
crab cheat               # Show cheat sheet

Setup Flow

1. Register your project

cd ~/Dev/my-project
crab init

You'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.

2. Scan for ports

crab config scan

This scans your repo for .env and .env.example files, finds port variables, and offers to add them to your config.

3. Customize 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

4. Add more projects

cd ~/Dev/another-project
crab init              # → alias: another
crab projects          # see both projects

Configuration

~/.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 install

See examples/ for more configuration examples.

Requirements

bash
tmux
git
yq (YAML parsing)
zip (for toolkit share)

# macOS
brew install tmux yq zip

# Ubuntu/Debian
apt install tmux yq zip

Installation

One-liner

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

Manual

git 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

Reinstall / Update

# 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

Tmux Layout

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

Tmux Keybindings

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

New Computer Setup

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
```

FAQ

Why Git worktrees instead of branches?

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.

Can I use crabcode with multiple projects?

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 project

How do I clean up old workspaces?

crab ws <N> cleanup    # Reset single workspace to origin/main
crab ws <N> destroy    # Completely remove workspace and worktree

How is Crabcode different from Clawdbot?

Completely 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

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.ralph		.ralph
docs		docs
examples		examples
plugins/promptfoo		plugins/promptfoo
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile.test		Dockerfile.test
Makefile		Makefile
README.md		README.md
install.sh		install.sh

promptfoo/crabcode

Folders and files

Latest commit

History

Repository files navigation

Crabcode 🦀

Quick Start

What It Does

Commands

Workspace Commands (crab ws)

Shortcuts (auto-detect workspace)

WIP Commands (crab wip)

Toolkit Commands (crab tk)

Slack Commands (crab slack)

Multi-Project Commands

Config Commands

Promptfoo Target Discovery (crab pf)

Other Commands

Setup Flow

1. Register your project

2. Scan for ports

3. Customize config

4. Add more projects

Configuration

Requirements

Installation

One-liner

Manual

Reinstall / Update

Tmux Layout

Tmux Keybindings

New Computer Setup

FAQ

Why Git worktrees instead of branches?

Can I use crabcode with multiple projects?

How do I clean up old workspaces?

How is Crabcode different from Clawdbot?

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

Workspace Commands (`crab ws`)

WIP Commands (`crab wip`)

Toolkit Commands (`crab tk`)

Slack Commands (`crab slack`)

Promptfoo Target Discovery (`crab pf`)

Packages