Install it fast.
Understand the system.

Installation

For most users, the fastest path is the npm install. Source install is best when you want to work on crewswarm itself.

npm install -g crewswarm
crewswarm

git clone https://github.com/crewswarm/crewswarm.git
cd crewswarm

npm install
bash install.sh

npm run restart-all

Once running, open the dashboard at http://127.0.0.1:4319 and Vibe at http://127.0.0.1:3333.

System Services

Execution Modes

CrewSwarm supports six CLI execution engines, a native executor, and a direct API mode. Coding roles (crew-coder, crew-fixer, crew-coder-front/back) should always run through a CLI engine so they get tool access, file edits, and terminal capabilities. Analysis and planning roles can use Direct API.

Engine selection: crew config set engine <name> or pass --engine per task. Set to auto to let the runtime pick based on role and model.

Git Worktree Isolation

When a PM loop dispatches multiple agents in the same wave, each agent automatically gets its own git worktree — an isolated copy of the repo on its own branch. Parallel agents can't conflict with each other on the filesystem.

Session Management

The CLI persists every conversation as a crash-safe JSONL transcript. Sessions survive unexpected exits and can be resumed at any time.

crew /sessions

# Interactive picker
crew /resume

# Resume a specific session
crew /resume abc123

crew /clear

Transcripts are stored in JSONL format — one JSON object per line — so partial writes from crashes never corrupt the file. Each line records the role, content, timestamp, and token count.

Tool Hooks

Hooks let you intercept tool calls before or after execution. Define them in .crew/hooks.json at your project root.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell|run_cmd",
        "command": "node .crew/validate-shell.js",
        "timeout": 5000
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "command": "node .crew/log-tool.js",
        "timeout": 3000
      }
    ]
  }
}

PreToolUse hooks fire before a tool runs. The tool input is piped as JSON on stdin. Your hook script can:

• Allow — exit 0 with no output to let the call proceed unchanged.
• Deny — exit non-zero to block the tool call entirely.
• Modify — exit 0 and write modified JSON to stdout to change the tool input.

PostToolUse hooks fire after a tool completes. The tool output is piped as JSON on stdin. Use these for logging, auditing, or triggering side effects.

The matcher field is a regex tested against the tool name. The timeout field (in milliseconds) kills the hook process if it exceeds the limit.

Git Worktree Isolation

Agents can work in an isolated Git worktree so your main working directory stays untouched.

crew enter_worktree feature/new-api

crew exit_worktree

crew merge_worktree feature/new-api

This is especially useful for long-running or speculative tasks where you want to inspect results before they affect your working tree.

CLI Environment Variables

These environment variables control CLI behavior. Set them in your shell profile or pass them inline.

# Example: run with streaming disabled and a 50K token budget
CREW_NO_STREAM=true CREW_MAX_SESSION_TOKENS=50000 crew "refactor auth module"

Token-Aware Compaction

Long sessions accumulate context. Instead of blindly truncating old messages, crew-cli adapts compression based on how full the context window is:

• < 50% used — light compression, keeps first 5 + last 8 turns in full detail
• 50–75% used — standard compression, first 3 + last 5 detailed, middle summarized
• > 75% used — aggressive, first 1 + last 3 detailed, everything else compressed

Per-model context window sizes are known (Gemini 1M, GPT-4o 128K, Claude 200K, etc.) so compression is tuned automatically. Token estimation uses a ~3.7 chars/token ratio — no external tokenizer dependency.

Set CREW_MAX_SESSION_TOKENS to control the token budget for session transcripts (default: 100K).

Swarm Chat & @Mentions

Swarm Chat is a shared channel where you and agents communicate. Use @agent-name to dispatch tasks directly to any agent — results flow back into the channel automatically.

# In Dashboard → Swarm Chat:
@crew-coder build a REST API for /users
@crew-qa test the /users endpoint
@crew-copywriter write API docs for the users service

How it works: When you @mention an agent with a work order (verb + specific task), the system classifies the intent and dispatches via the RT bus. The agent executes using its configured engine (Claude Code, Gemini, etc.) and the result is persisted to the shared project message history.

Agent-to-agent: Agents can chain work autonomously. If crew-coder responds with "let me ask @crew-qa to test this", the system auto-dispatches to crew-qa. A hop limit (default 4) prevents infinite loops — send /continue to resume.

Chat vs code routing: Conversational messages ("hi", "what's your status?") go directly to the agent's LLM model. Only coding tasks route through CLI engines. This keeps chat fast and cheap.

Toggle: Autonomous mentions are on by default. Disable in Dashboard → Settings or via crewswarm.json → settings.autonomousMentionsEnabled.

tmux Bridge (Multi-Agent Sessions)

When running multi-wave pipelines, agents can share execution context via tmux panes. The bridge lets the orchestrator label panes with agent IDs, read agent output, and hand off sessions between pipeline waves.

# Enable the bridge (requires tmux installed)
export CREWSWARM_TMUX_BRIDGE=1

# Or toggle in Dashboard → Settings → Engines

How it works: When Agent A finishes wave 1, the session manager transfers the tmux pane to Agent B. Agent B can read Agent A's output and continue in the same working directory. No context is lost between waves.

When to use: PM loop pipelines, multi-step builds where agents chain (coder → QA → fixer). Not needed for single-task dispatch.

The bridge is a built-in bash script (scripts/tmux-bridge) — no external dependencies beyond tmux.

System Infrastructure

curl http://localhost:5020/health

Best Practices

• Update the Brain

  Maintain memory/brain.md in your project. This file is the primary context source for all agents. Use it to store project rules and architectural decisions.

• Leverage the PM Loop

  Don't manage tasks manually. Create a ROADMAP.md and let crew-pm handle the decomposition. This enables autonomous, multi-step progress.

• Task Granularity

  The smaller the task, the higher the success rate. If a task is complex, ask crew-pm to break it down further before dispatching it to crew-coder.

Ready to build?

Clone the repo and start your first crew today.