Overview

Crewd Documentation

Crewd is the package manager for prompt-defined AI agents, skills, and teams. It compiles reusable, prompt-based subagents and skills directly into native configurations across Claude Code, Cursor, and Gemini CLI.

Installation

Install the standalone crewd binary via Homebrew or the curl installer:

Option 1: Homebrew (macOS / Linux)

bash

brew install crewdhq/tap/crewd

Option 2: Standalone Shell Installer (macOS / Linux)

bash

curl -fsSL https://crewd.dev/install.sh | sh

Option 3: Go Install

bash

go install github.com/crewdhq/crewd-cli/cmd/crewd@latest

Uninstalling Crewd CLI

Depending on how you installed the CLI, use the matching command below to remove the binary and optional config/cache directories:

1. Homebrew

If you installed using the Homebrew tap:

bash

brew uninstall crewd
brew untap crewdhq/tap  # optional

2. Standalone Shell Installer / Manual Binary

If you installed via curl https://crewd.dev/install.sh | sh, find and delete the binary (typically in /usr/local/bin or ~/.local/bin):

bash

# Check where the crewd binary is located
which crewd

# Remove the binary (use sudo if installed into /usr/local/bin)
sudo rm /usr/local/bin/crewd

# Or if installed to ~/.local/bin:
rm ~/.local/bin/crewd

3. Go Install

If you installed via Go:

bash

rm -f $(go env GOPATH)/bin/crewd

4. Remove Configuration and Cache (Optional)

To completely remove stored authentication tokens, registry configuration, and downloaded package tarballs:

bash

# Remove CLI credentials & preferences (~/.config/crewd)
rm -rf ~/.config/crewd

# Remove downloaded package blobs & extracted cache (~/.cache/crewd)
rm -rf ~/.cache/crewd

3-Minute Quickstart

Hire your first agent into an existing Git repository:

1. Initialize your workspace

bash

crewd init

Detects whether you use Claude Code, Cursor, or Gemini CLI, creates crewd.json, and appends gitignore rules.

2. Hire an agent

bash

crewd hire @alice/reviewer

Downloads the verified package, generates .claude/agents/reviewer.md or Cursor rules, and locks dependencies in crewd.lock.

3. Invoke your new subagent

Start your coding host as usual. In Claude Code, say:

bash

claude "Please review my latest git diff using the reviewer subagent."

CLI Command Reference

Comprehensive syntax, flags, and usage patterns for all CLI commands.

crewd init [--hosts=<list>]

Scans the current repository to auto-detect installed AI tools (.claude/, .cursor/, GEMINI.md) and generates crewd.json.

bash

crewd init --hosts=claude-code,cursor

crewd hire <package[@range]> / crewd hire team <package>

Resolves transitive dependencies, downloads immutable tarballs, validates SHA-256 hashes, and renders compiled adapter files.

bash

# Hire a single agent with pinned range
crewd hire @alice/reviewer@^1.4.0

# Preview resolution without writing any files
crewd hire @alice/reviewer --dry-run

# Hire an entire squad of agents
crewd hire team @acme/backend-squad

crewd fire <package> / crewd fire team <package>

Removes an agent, skill, or team from crewd.json and deletes its generated host adapter files. Note: Memory files in .crewd/memory/ are deliberately preserved so repository learnings are never lost.

bash

crewd fire @alice/reviewer

crewd promote [package[@version]]

Upgrades installed packages to the latest matching release while preserving repository-local taught skills and persistent agent memories.

bash

# Promote all packages in the workspace
crewd promote

# Promote a specific agent to a target version
crewd promote @alice/reviewer@1.5.0

# Preview upgrade diff before writing changes
crewd promote --dry-run

crewd teach <agent> <skill[@range]> / crewd forget <agent> <skill>

Attaches an additional repo-local skill to an installed agent without modifying the upstream package. Taught skills are saved in crewd.json under teach and re-applied on subsequent compiles and upgrades.

bash

# Teach reviewer an extra PR description skill
crewd teach @alice/reviewer @tools/pr-description

# Remove a previously taught skill
crewd forget @alice/reviewer @tools/pr-description

crewd install [--frozen]

Installs all packages strictly from crewd.lock. Use --frozen in CI/CD pipelines to fail with exit code 4 if the lockfile is stale versus crewd.json.

bash

crewd install --frozen

crewd search <query> & crewd interview <package>

Discover and inspect packages before installing: search queries the public registry, while interview fetches the package dossier, displaying its role prompt, host compatibility, dependencies, and README.

bash

# Search for review agents in registry
crewd search reviewer

# Preview package prompt and dependencies before hiring
crewd interview @alice/reviewer

crewd roster [--json] & crewd doctor

Inspect your workspace: roster lists all active agents, squad members, and taught skills. doctor validates lockfile synchronization, detects manual file edits, and verifies host CLI readiness.

bash

# Output roster as JSON for scripting
crewd roster --json

# Run workspace diagnostic checks
crewd doctor

crewd mcp

Starts the local Model Context Protocol (MCP) server over stdio. Allows AI coding agents in Claude Code, Cursor, and Gemini CLI to discover, inspect, plan, and hire agents directly within an active session.

bash

# Start local stdio MCP server from CLI
crewd mcp

# Or run via npx in client configurations
npx @crewdhq/crewd-mcp

crewd completion [bash|zsh|fish|powershell]

Generate auto-completion scripts for your active shell to enable fast tab completion across all commands and flags.

bash

# Zsh completion setup
echo "autoload -U compinit; compinit" >> ~/.zshrc
crewd completion zsh > "${fpath[1]}/_crewd"

# Bash completion setup (macOS Homebrew)
crewd completion bash > $(brew --prefix)/etc/bash_completion.d/crewd

Crewd MCP Server

stdio Transport

The Crewd MCP server enables coding agents (Claude Code, Cursor, Gemini CLI) to discover, inspect, and hire agents, teams, and skills from inside an active coding session without requiring the user to leave and run the terminal CLI. It is shipped as crewd mcp and is also runnable via npx @crewdhq/crewd-mcp.

Client Setup & Configuration

Configure the server in your preferred AI assistant using either npx @crewdhq/crewd-mcp or your local crewd mcp binary:

1. Claude Code

bash

# Add Crewd to Claude Code via npx
claude mcp add crewd -- npx @crewdhq/crewd-mcp

# Or point to the local CLI binary:
claude mcp add crewd -- crewd mcp

2. Cursor (.cursor/mcp.json)

json

{
  "mcpServers": {
    "crewd": {
      "command": "npx",
      "args": ["-y", "@crewdhq/crewd-mcp"]
    }
  }
}

3. Gemini CLI & Antigravity IDE (settings.json)

json

{
  "mcpServers": {
    "crewd": {
      "command": "npx",
      "args": ["-y", "@crewdhq/crewd-mcp"]
    }
  }
}

Exposed MCP Tools

Tool Name	Input Parameters	Description
search_packages	query, kind?, limit?	Search registry for packages, returning version, description, publisher, agent/skill counts, and script tags.
inspect_package	name, version?	Read-only inspection of prompts, role when-conditions, tool permissions, skills, and script previews. Never executes anything.
plan_hire	name, version?, targets?	Dry run. Computes resolved versions, SHA-256 hashes, exact files to create/update, and returns a single-use confirm_token. Writes nothing.
hire	name, version?, targets?, confirm_token	Installs package into the repo using a valid confirm_token after explicit user approval. Installs scripts as files only.
list_installed	{}	Reads crewd.json and crewd.lock to return all active crews, agents, skills, and versions.
check_updates	{}	Compares lockfile against registry to identify available upgrades with summaries of new/removed skills and scripts.

Safety Model & Trust Boundaries

Because calling AI agents can be prompt-injected by untrusted code they read, installing new agents into your repository represents a sensitive trust boundary. Crewd enforces strict defensive safeguards:

Two-Phase Hire with Confirmation Tokens

hire cannot run without a prior plan_hire. Calling agents must show the plan to the human user and obtain explicit approval before submitting the single-use, 5-minute confirm_token.

File-Only Scripts

Executable scripts (.sh, scripts/) are prominently flagged during planning. The MCP server installs them strictly as inert files and never executes package scripts.

Prompt-Injection Protection

All registry content (descriptions, READMEs, prompts) is treated as untrusted data. Long text fields are truncated and sanitized to prevent instruction override attacks on calling agents.

Path Traversal & Hash Verification

Tarball entries are checked against path traversal (.., absolute paths) and strictly restricted to the workspace root. Archives are verified against registry SHA-256 integrity hashes before extraction.

Using Hired Agents in AI Coding Tools

Crewd packages are not background daemons or closed plugins. When you run crewd hire, Crewd natively adapts prompts, tools, skills, and memory into the exact files your AI coding tools already read. Here is how to activate and work with your hired crew in each environment:

Claude CodeSubagent Mode

Crewd renders agents into .claude/agents/<name>.md and skills into .claude/skills/<skill>/SKILL.md. Claude Code automatically recognizes these as specialized subagents with isolated tool permissions.

How to Invoke in Claude Code

markdown

# Option 1: Direct subagent command
/agent code-reviewer "Review all staged changes against main"

# Option 2: Natural conversation prompt
"Please delegate the diff review in src/auth to our code-reviewer agent."

Safe Tool Enforcement: If an agent defines tools.deny: ["edit", "write"], Claude Code blocks the agent from modifying files.
Automatic Skills: Claude loads attached skills (e.g. review-checklist, owasp-top10) on demand.
Memory Persistence: Claude reads and updates .crewd/memory/<agent>.md after completing review cycles.

CursorMDC Rule Mode

Crewd compiles agents to .cursor/rules/crewd-<name>.mdc and skills to .cursor/rules/crewd-skill-<skill>.mdc. Cursor reads these rules automatically based on file globs or explicit user mentions.

How to Invoke in Cursor Chat & Composer

markdown

# In Cursor Chat (Cmd+L) or Composer (Cmd+I):
@crewd-code-reviewer review the current open file for security vulnerabilities and edge cases.

# When generating tests:
@crewd-test-writer write comprehensive unit tests for the functions in src/auth.ts following testing-patterns.

Context-Aware Globs: Cursor automatically injects the rule whenever you open files matching the package's specified paths.
Symbol & Skill Referencing: Use @crewd-skill-owasp-top10 alongside any prompt to enforce strict security checks.

Gemini CLI & Antigravity IDEWorkspace Rules Mode

Crewd cleanly injects agents into GEMINI.md between safe, atomic comment delimiters: ... . Skills are placed in .gemini/skills/<skill>/SKILL.md.

How to Invoke with Gemini

markdown

# Ask Gemini to assume the hired agent role:
"As our code-reviewer, inspect git diff and provide blocking/should-fix feedback."

# Direct task execution:
"Follow the test-writer workflow in GEMINI.md to create table-driven tests for user registration."

Non-Destructive Compilation: Any custom instructions or rules in your AGENTS.md or GEMINI.md outside the crewd markers remain untouched.
Skill Discovery: Gemini loads instructions from .agents/skills/ and .gemini/skills/ whenever relevant procedures are mentioned.

OpenAI Codex CLIAgents Standard Mode

Crewd natively adapts agents for OpenAI Codex CLI by injecting marker-delimited instructions into CODEX.md or AGENTS.md: ... . Skills are compiled into .codex/skills/<skill>/SKILL.md.

How to Invoke with Codex CLI

bash

# Launch Codex CLI session in project directory
codex

# Or ask Codex to assume the hired agent role:
codex "As our code-reviewer agent, review unstaged git changes before commit."

Universal Instruction Standard: Codex reads AGENTS.md and CODEX.md hierarchically at session start.
Skill Integration: Skills registered under .codex/skills/ are loaded on demand whenever matching workflows are prompted.

Durable Agent Memory & LearningLong-Term State

Traditional prompt files are stateless; every new session starts from scratch. Crewd equips each hired agent with an isolated, append-only memory file in.crewd/memory/<agent>.md.

markdown

---
crewd-memory: v1
agent: "@m0agh/code-reviewer"
version: "1.0.0"
updated: 2026-10-12
---

## 2026-10-12
- Initialized memory for @m0agh/code-reviewer.
- Reviewed auth module (src/auth.ts): flagged parameterized queries (OWASP A03) and access control checks on password reset as required repository patterns.

Session Continuity

Before taking actions, agents read their memory file to honor previous decisions, architecture patterns, and bug history.

Upgrade-Safe

When you run crewd promote to pull new agent versions, memory files are never overwritten or deleted.

Multi-Agent Squad WorkflowsTeam Coordination

When you hire a team with crewd hire team <team> (such as @m0agh/pr-review-squad), all squad members are installed together with specialized roles:

markdown

# Example multi-agent collaboration prompt:
"We have the pr-review-squad installed.
1. Run code-reviewer to audit the changes in PR #42 and group findings by severity.
2. If blocking issues are found, have test-writer produce a failing regression test case."

Each agent remains focused on its designated specialty (reviewing vs. writing tests vs. updating docs), preventing prompt dilution and hallucination.

Package Specifications

Crewd packages are declared via YAML manifests and compiled deterministically:

yaml

schema: https://crewd.dev/schema/agent/v1
type: agent
name: "@alice/reviewer"
version: 1.5.0
description: "Comprehensive code & PR reviewer subagent"

role:
  title: "Lead Code Reviewer"
  when: "Use when a diff, commit, or PR requires code review."

hosts:
  - claude-code
  - cursor
  - gemini-cli

tools:
  allow: [read, grep, glob, bash]
  deny: [write, edit]

skills:
  - "@alice/pr-description@^1.0.0"

prompt: prompt.md

Host Integrations

Crewd natively adapts agents and skills to your AI coding environment without vendor lock-in:

Compiled to .claude/agents/<name>.md with frontmatter tools and subagent triggers. Associated skills are placed into .claude/skills/<skill>/SKILL.md.

Injects the Durable Memory instruction linking to .crewd/memory/<name>.md.

Security & Architecture

Content-Addressable Blobs: Packages are distributed as deterministic ustar tarballs with SHA-256 integrity hashes (/blobs/sha256-...). Archives are immutable and cached with zero invalidation risk.

Memory Isolation: Agent memory files in .crewd/memory/ store project-specific learnings and are never overwritten or deleted by fire or promote.

Script Safety Policy: Packages containing lifecycle scripts trigger warnings and require explicit confirmation with --yes to prevent arbitrary code execution in CI environments.