zcrew

zcrew is a quick-win multi-agent CLI: clone, install, and run Claude, Codex, or Pi agents in zellij panes, each sandboxed via bwrap. A low-ceremony orchestrator for micro-managers like me who want to watch all their little agents at work.

The default sandbox model is intentionally minimal. zcrew does not mount or copy your full host ~/.claude, ~/.codex, ~/.pi, or ~/.local trees into agent panes. Instead, each project gets a clean sandbox-local HOME under .bx/home/, a narrow runtime mount allowlist, copied auth artifacts, and tiny generated config files.

That means your normal Claude/Codex auth keeps working seamlessly inside the sandbox — including subscription-backed logins — without dragging in your full personal agent state, MCP setup, extensions, caches, or history from the host. Sessions and runtime state still persist, but only inside the project sandbox.

What it does

• Spawn named agent panes: zcrew spawn claude claudio, zcrew spawn codex sam, zcrew spawn pi piper
• Send tasks between agents: zcrew send --compact sam "implement TFD-42: add retry logic"
• List the team: zcrew list
• Sync registry with live zellij state (auto-syncs on every command)
• Close / rename panes

Each agent runs inside a bwrap sandbox (bx) with isolated HOME, scrubbed env vars, and project-local tool resolution via mise.

Prerequisites

• Linux (bwrap requires user namespaces)
• zellij terminal multiplexer
• mise for tool version management
• jq for JSON processing
• At least one of: Claude Code, Codex, Pi

Install

# Clone zcrew (once)
git clone https://github.com/DanielLukic/zcrew.git ~/zcrew
cd ~/zcrew

# Install into your project
.zcrew/bin/zcrew install /path/to/your/project
cd /path/to/your/project

This copies .zcrew/bin/zcrew, .zcrew/bin/bx, .zcrew/lib/launchers/, the canonical cross-tool zcrew skill, tool-specific helper skills, root agent docs, sandbox config, and a managed mise floor into your project. Re-run to update. Use --dry-run to preview what an install would do without mutating any files. If you move a project directory, re-run zcrew install . to refresh absolute paths embedded in .mcp.json, .codex/config.toml, .claude/settings.local.json, and .bx/mounts; --dry-run will tell you when stale paths are present. After running zcrew install . in an existing project, restart your claude orchestrator session so it reloads .mcp.json.

Contributing — git hooks

If you're contributing to zcrew itself, wire the AI-provenance commit hooks once:

mise run install-hooks

This sets core.hooksPath = .githooks, enforcing a Co-Authored-By: <agent> <email> trailer on every commit.

Quick start

Launch your orchestrator (Claude, Codex, or Pi) in the project root. The orchestrator reads the zcrew skill and knows how to spawn and manage agents. AGENTS.md is the committed root entrypoint; CLAUDE.md is a symlink to it for Claude-facing compatibility.

You can also spawn agents manually:

zcrew spawn claude claudio      # assistant / researcher
zcrew spawn codex sam           # reviewer
zcrew spawn pi piper            # implementer

The orchestrator handles send, list, close, sync, and --compact automatically. You steer it — tell it what to build, which agents to use, and it dispatches work to the team.

Available CLI commands for manual use: zcrew spawn, send, close, list, sync, rename.

Components

Tool	Purpose
.zcrew/bin/zcrew	Multi-agent orchestration CLI
.zcrew/bin/bx	bwrap sandbox manager (lightweight, no container daemon)
.zcrew/bin/ix	Incus container manager (heavier, full apt, persistent)
.zcrew/lib/launchers/	Per-agent launch scripts (claude.sh, codex.sh, pi.sh)
.agents/skills/	Canonical cross-tool skill location (zcrew)
.claude/skills/	Claude Code slash commands (/zspawn, /zsend, etc.)
.pi/skills/	Pi slash commands plus zcrew symlinked to .agents/skills/zcrew
.codex/skills/	Codex zcrew symlink to .agents/skills/zcrew
AGENTS.md / CLAUDE.md	Root agent docs; CLAUDE.md symlinks to AGENTS.md

Sandbox design

bx (bwrap) creates a per-project sandbox:

• Isolated HOME at .bx/home/ (persistent across sessions)
• Host /etc mounted read-only
• Project dir mounted read-write
• Env vars scrubbed (LD_LIBRARY_PATH, HOMEBREW_, DIRENV_, etc.)
• Project bin/ always first on PATH
• mise shims for tool resolution

MCP support for other agents

zcrew install auto-wires claude, codex, and pi. For other agents, drop the canonical zcrew server entry into your agent's MCP config:

{ "mcpServers": { "zcrew": { "command": "python3", "args": ["/abs/path/to/project/.zcrew/lib/mcp_server.py"] } } }

Use the absolute project path. Do not set BX_INSIDE; this is the orchestrator surface. Setting BX_INSIDE=1 exposes the worker reply surface instead. Most agents use top-level JSON mcpServers; some use TOML (Codex), YAML (Goose, Continue), or a different key such as Amp amp.mcpServers, Kilo mcp, or OpenCode mcp.

Common config paths:

• Gemini CLI: .gemini/settings.json
• Cursor: .cursor/mcp.json
• Droid: .factory/mcp.json
• Amp: .amp/settings.json
• OpenCode: opencode.json
• Qwen: .qwen/settings.json
• Auggie: ~/.augment/settings.json or --mcp-config
• OpenHands: ~/.openhands/mcp.json
• Goose: ~/.config/goose/config.yaml
• Continue: config.yaml
• Cline: ~/.cline/data/settings/cline_mcp_settings.json
• Copilot CLI: .mcp.json (works automatically)
• Kimi: ~/.kimi/mcp.json
• Amazon Q: ~/.aws/amazonq/cli-agents
• Roo: .roo/mcp.json
• Kilo: kilo.json

Refer to your agent's MCP documentation for the exact format.

ix (Incus) — alternative sandbox (DISCLAIMER: Not integrated, yet!)

.zcrew/bin/ix provides a heavier alternative to bx using Incus/LXC containers. Full apt, persistent containers, UID-mapped shared mounts. Useful when agents need to install system packages or run long-lived services. Not part of the default zcrew workflow — bx covers most use cases.

ix prerequisites

• Incus with your user in the incus-admin group
• A ZFS storage pool registered with Incus

ZFS pool setup (example)

# Create a ZFS-backed storage pool (adjust path/size as needed)
sudo truncate -s 50G /path/to/incus-zfs.img
sudo zpool create mypool /path/to/incus-zfs.img

# Register with Incus
incus storage create incus-pool zfs source=mypool

ix usage

ix setup       # create container, UID map, provision
ix run <cmd>   # run command inside container
ix shell       # interactive shell
ix stop        # stop container

Config lives in .ix/config per project (CONTAINER, IMAGE, WORKDIR). Optional provision.sh in .ix/ runs at setup time for extra packages.

Tests

bash tests/test-bx.sh
bash tests/test-ix.sh
bash tests/test-zcrew.sh   # currently 215 tests

License

Unlicense — public domain.