io.github.chrismcdermut/proletariat-cli

██████╗ ██████╗  ██████╗ ██╗     ███████╗████████╗ █████╗ ██████╗ ██╗ █████╗ ████████╗
██╔══██╗██╔══██╗██╔═══██╗██║     ██╔════╝╚══██╔══╝██╔══██╗██╔══██╗██║██╔══██╗╚══██╔══╝
██████╔╝██████╔╝██║   ██║██║     █████╗     ██║   ███████║██████╔╝██║███████║   ██║
██╔═══╝ ██╔══██╗██║   ██║██║     ██╔══╝     ██║   ██╔══██║██╔══██╗██║██╔══██║   ██║
██║     ██║  ██║╚██████╔╝███████╗███████╗   ██║   ██║  ██║██║  ██║██║██║  ██║   ██║
╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝   ╚═╝

Seize the means of production - Ship 100x.

Agent orchestration platform for AI labor. Spin up workers for all work, on demand.

Themed agents, including billionaires - Finally, they work for us.

⚠️ Beta Software — Under active development. Commands and APIs may change between versions, and bugs are actively being squashed.

Let's get you shipping [Book a call][cal-link] - I'm happy to help you get prlt running or chat feedback, ideas, multi-agent workflows, and the future of work/labor (and economic labor theory..)

---

TLDR

prlt is an agent orchestration platform for AI labor. Spin up workers on demand, coordinate multi-agent development from one CLI. Isolated workspaces, secure containers, persistent state.

brew install chrismcdermut/proletariat/prlt    # macOS (Homebrew)
# or
npm install -g @proletariat/cli        # any platform (npm)

prlt new
prlt ticket create --title "Add OAuth" --category feature
prlt work spawn   # Interactive: select tickets, environment, action

Agent spawns in its own branch, writes code, opens PR. You review and merge.

Why prlt?

• Isolated - Each agent gets its own git branch. No conflicts.
• Secure - Docker containers, sandboxed from your host.
• Durable - Tmux sessions persist. Close window, agent keeps working.
• Trackable - One database, one CLI, all your agents.
• Ephemeral - Spawn agents on demand. They work, they PR, they're done.
• Structured - Tickets provide structured context, not freeform chat.
• Persistent - Tickets accumulate context over time. Hand off between agents.
• Agent-native - --json mode lets AI agents drive the CLI programmatically.

---

Quick Start

brew install chrismcdermut/proletariat/prlt  # Install (Homebrew, recommended)
# or
npm install -g @proletariat/cli              # Install (npm, all platforms)

prlt new                           # Create HQ, add repos, choose theme
prlt ticket create --title "Add OAuth" --category feature
prlt work spawn                    # Interactive: select tickets, environment, action
# Agent creates PR → You review → Merge → Done

Workflow Diagram (click to expand)

sequenceDiagram
    participant You
    participant prlt
    participant Agent
    participant GitHub

    You->>prlt: prlt ticket create
    You->>prlt: prlt work spawn
    prlt->>prlt: Create branch
    prlt->>prlt: Create workspace
    prlt->>Agent: Spawn agent
    Agent->>Agent: Read ticket
    Agent->>Agent: Write code
    Agent->>GitHub: Commit
    Agent->>GitHub: Open PR
    Agent->>prlt: Update status
    prlt->>You: PR ready
    You->>GitHub: Review & approve

Spawn agents to implement, groom, or review—not just write code.

Interactive Menus

prlt work guides you through project and ticket selection:

Choose your operation—start a single agent, batch spawn, or watch a column:

Select tickets to spawn, grouped by priority:

---

Deep Dive

Installation

Homebrew (recommended)

brew install chrismcdermut/proletariat/prlt

Works on both Apple Silicon (arm64) and Intel (x86_64) Macs. No compiler needed.

Upgrade:

brew update
brew upgrade prlt

npm / pnpm (all platforms)

npm install -g @proletariat/cli
# or
pnpm install -g @proletariat/cli

pnpm 10+ note: pnpm 10 blocks native addon build scripts by default. If prlt fails with a native module error after install, run pnpm approve-builds in the global store and reinstall, or use npm / brew instead.

Verify:

prlt --version

MCP Server

prlt includes a built-in MCP server with 100+ tools. Add it to your AI client:

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "prlt": { "command": "prlt", "args": ["mcp-server"] }
  }
}

Cursor / Other clients (via npx):

{
  "mcpServers": {
    "prlt": { "command": "npx", "args": ["-y", "@proletariat/cli", "mcp-server"] }
  }
}

Listed on: MCP Registry | npm

Data Model

Workspace (HQ)
├── Projects
│   ├── Epics → Tickets
│   └── (references a Workflow)
├── Workflows → Phases → Statuses (can be shared across projects)
├── Specs (can span projects)
├── Actions (reusable templates)
├── Agents
│   ├── Staff (persistent, named)
│   └── Temp (ephemeral, per-ticket)
└── Executions (running sessions)
    ├── Docker
    │   ├── Tmux session
    │   ├── Terminal or Background display
    │   └── Safe or YOLO permissions
    └── Host
        ├── Tmux session
        ├── Terminal or Background display
        └── Safe or YOLO permissions

Example Workflow

A workflow defines how tickets move through your process. Projects reference a workflow, and multiple projects can share the same one.

Kanban Workflow
├── Backlog       # New tickets land here
├── In Progress   # Agent working (prlt work spawn)
├── Review        # PR ready (prlt work ready)
└── Done          # Merged (prlt work complete)

Scrum Workflow
├── Backlog
├── Sprint
│   ├── To Do
│   ├── In Progress
│   └── In Review
└── Done

Tickets flow through statuses as work progresses. Agents automatically move tickets when they start work, open PRs, or complete tasks.

Workspace Structure

Each agent gets a copy of all repos (repo scoping coming soon). Work happens on isolated branches.

my-project/
├── .proletariat/
│   └── workspace.db              # Tickets, executions, state
├── repos/
│   ├── frontend/                 # Your repos
│   ├── backend/
│   └── infra/
└── agents/
    ├── staff/
    │   └── alice/                # Named agent with persistent workspace
    │       ├── frontend/
    │       ├── backend/
    │       └── infra/
    └── temp/
        ├── agent-abc123/         # Ephemeral: Working on TKT-042 (OAuth)
        │   ├── frontend/         # All repos on branch: feat/TKT-042-oauth
        │   ├── backend/
        │   └── infra/
        └── agent-def456/         # Ephemeral: Working on TKT-043 (API)
            ├── frontend/         # All repos on branch: feat/TKT-043-api
            ├── backend/
            └── infra/

Agent Naming Themes

Themes control how agents are named. Staff agents use theme names directly (e.g., bezos, camry). Ephemeral agents add an adjective prefix (e.g., bold-bezos, keen-camry). Currently ephemeral names also include a number suffix (bold-bezos-1), but this will be removed soon.

Built-in Themes:

billionaires — Finally, they work for us.

Theme Commands:

prlt agent themes list              # List available themes
prlt agent themes set billionaires  # Set active theme
prlt agent themes create mytheme    # Create custom theme
prlt agent themes add-names mytheme # Add names to custom theme

Themes are selected during prlt new.

Three Ways to Use Commands

1. Interactive (Humans)

Run without flags—get guided prompts:

$ prlt ticket create

? Title: Add password reset
? Description: Email-based password reset flow
? Priority: P1
? Category: feature

✓ Created TKT-043

View ticket details with prlt ticket:

2. JSON Mode (AI Agents)

Add --json for machine-readable output:

$ prlt work start --json

{
  "prompt": {
    "type": "list",
    "message": "Select ticket to work on:",
    "choices": [
      {
        "name": "[P1] TKT-042 - Add user authentication",
        "value": "TKT-042",
        "command": "prlt work start TKT-042 --json"
      }
    ]
  }
}

AI agents parse this, make selections, call the next command.

3. Flags (Scripts/CI)

Pass everything directly:

prlt ticket create \
  --title "Add OAuth" \
  --description "Google and GitHub OAuth" \
  --priority P1 \
  --category feature

Execution Modes

Environment - where the agent runs:

Display - how you see it:

Permissions - agent access level:

All sessions run in tmux under the hood—close the window, agent keeps working.

# Default: Docker + terminal (if devcontainer exists)
prlt work start TKT-042

# Docker + background
prlt work start TKT-042 --display background

# Host + background (fast, no container)
prlt work start TKT-042 --run-on-host --display background

# Docker + YOLO (full autonomy, safely sandboxed)
prlt work start TKT-042 --skip-permissions

Parallel Agents

Work on multiple tickets simultaneously.

Interactive (humans):

$ prlt work spawn

? Spawn mode: Select specific tickets
? Select tickets:
  ◉ [P1] TKT-042 - Add user authentication
  ◉ [P1] TKT-043 - Add API rate limiting
  ◯ [P2] TKT-044 - Add email notifications
? Action: implement
? Environment: docker

Spawning 2 tickets...

JSON mode (AI agents): (multi-select WIP)

$ prlt work spawn --json --many

{
  "prompt": {
    "type": "checkbox",
    "message": "Select tickets to spawn:",
    "choices": [
      {"name": "[P1] TKT-042 - Add user authentication", "value": "TKT-042"},
      {"name": "[P1] TKT-043 - Add API rate limiting", "value": "TKT-043"}
    ]
  }
}

Flags (scripts/CI):

prlt work spawn TKT-042 TKT-043 --action implement --mode docker

Each agent works in its own branch. No conflicts.

Scaling: The main limit is your machine. 50+ concurrent agents is achievable—depends on CPU, RAM, and whether you're running Docker or host mode.

Monitor running agents with prlt execution:

flowchart LR
    subgraph You
        spawn[prlt work spawn]
    end

    subgraph Agents
        A1[Agent 1<br/>TKT-042 OAuth]
        A2[Agent 2<br/>TKT-043 Rate Limit]
        A3[Agent 3<br/>TKT-044 Notifications]
    end

    subgraph GitHub
        PR1[PR #101<br/>feat/TKT-042-oauth]
        PR2[PR #102<br/>feat/TKT-043-rate-limit]
        PR3[PR #103<br/>feat/TKT-044-notifications]
    end

    spawn --> A1
    spawn --> A2
    spawn --> A3

    A1 --> PR1
    A2 --> PR2
    A3 --> PR3

Agent-created PRs ready for review:

Command Reference

Full Command Reference (click to expand)

NamespaceCommandDescription

ticketprlt ticket createCreate new ticket prlt ticket listList all tickets prlt ticket view <id>View ticket details prlt ticket edit <id>Edit ticket prlt ticket move <id> <status>Change status prlt ticket delete <id>Delete ticket prlt ticket complete <id>Mark ticket complete prlt ticket bulkBulk ticket operations prlt ticket link block <id>Link blocking ticket prlt ticket link relates <id>Link related ticket

workprlt work start <id>Spawn agent on ticket prlt work spawnBatch spawn tickets prlt work complete <id>Mark work done prlt work ready <id>Mark ready for review prlt work revise <id>Request revision prlt work watchWatch work progress

executionprlt execution listList running agents prlt execution logs <id>View agent output prlt execution stop <id>Stop an agent

agentprlt agent listList all agents prlt agent status <name>Check agent status prlt agent shell <name>Shell into agent workspace prlt agent visit <name>Navigate to workspace prlt agent login <name>Auth Claude in container prlt agent rebuild <name>Rebuild agent workspace prlt agent restart <name>Restart agent prlt agent staff add <names>Add named agents prlt agent staff listList staff agents prlt agent temp listList ephemeral agents prlt agent temp cleanupRemove ephemeral agents

agent themesprlt agent themes listList available themes prlt agent themes set <name>Set active theme prlt agent themes create <name>Create custom theme prlt agent themes add-namesAdd names to theme

boardprlt boardView kanban board prlt board watchReal-time updates

projectprlt project createCreate project prlt project listList projects prlt project view <id>View project details prlt project archive <id>Archive project prlt project unarchive <id>Unarchive project prlt project delete <id>Delete project

actionprlt action createCreate action template prlt action listList actions prlt action show <id>Show action details prlt action run <id>Run action prlt action update <id>Update action prlt action delete <id>Delete action

branchprlt branch createCreate branch prlt branch listList branches prlt branch validateValidate branch name

prprlt pr createCreate pull request prlt pr status <id>Check PR status prlt pr link <id> <url>Link PR to ticket

ghprlt gh loginLogin to GitHub prlt gh statusCheck auth status prlt gh tokenGet GitHub token

repoprlt repo add <url>Add repository prlt repo listList repositories prlt repo view <name>View repository details prlt repo remove <name>Remove repository

dockerprlt docker listList containers prlt docker statusCheck Docker status prlt docker start <name>Start container prlt docker stop <name>Stop container prlt docker restart <name>Restart container prlt docker logs <name>View container logs prlt docker shell <name>Shell into container prlt docker sync <name>Sync container files prlt docker cleanRemove stopped containers prlt docker pruneRemove unused resources

sessionprlt session listList active tmux sessions prlt session attach <name>Attach to tmux session

workspaceprlt initInitialize machine config prlt newCreate new HQ workspace prlt workspace listList workspaces prlt workspace addAdd workspace prlt workspace use <name>Switch workspace

utilityprlt whoamiShow current context prlt claudeQuick ad-hoc Claude session prlt commitConventional commit prlt autocomplete setupSetup shell autocomplete

Run prlt <command> --help for flags and options.

Use Cases

Parallel Feature Development

# Create tickets for each feature
prlt ticket create --title "Add OAuth" --category feature
prlt ticket create --title "Add API rate limiting" --category feature
prlt ticket create --title "Add email notifications" --category feature

# Spawn all three in parallel (Docker for isolation)
prlt work spawn TKT-001 TKT-002 TKT-003 --mode docker

# Watch the board as they work
prlt board watch

Three agents, three branches, three PRs. You review and merge.

Bug Bash

# Spawn all bugs at once
prlt work spawn --all --column Backlog --category bug

# Or pick specific ones
prlt work spawn TKT-010 TKT-011 TKT-012

Grooming Session

Have an agent refine ticket requirements:

prlt work groom TKT-042

Agent adds acceptance criteria, subtasks, estimates.

---

Environment Variables

Claude Code handles its own authentication via claude login.

---

Requirements

• Node.js 20+ (22 LTS recommended)
• Git
• Claude Code (claude login to authenticate)
• SQLite
• Tmux (session persistence)
• Docker (optional—for isolated execution)

---

Troubleshooting Installation

bun install fails on better-sqlite3

Symptom: bun install -g @proletariat/cli fails with isexe or node-gyp errors during the better-sqlite3 native module build.

Cause: Bun's node-gyp compatibility is limited. The which dependency inside node-gyp uses isexe, which is incompatible with Bun's runtime shims.

Fix: Use npm or Homebrew instead:

# Option 1: Homebrew (macOS, recommended)
brew install chrismcdermut/proletariat/prlt

# Option 2: npm (all platforms)
npm install -g @proletariat/cli

# Option 3: pnpm
pnpm install -g @proletariat/cli

If you must use Bun, ensure Node.js 22 (LTS) is also installed and set better-sqlite3 to use its prebuilt binaries:

npm rebuild better-sqlite3

npm EACCES: permission denied

Symptom: npm install -g @proletariat/cli fails with EACCES: permission denied on /opt/homebrew/lib/node_modules or /usr/local/lib/node_modules.

Fix: Configure npm to use a user-writable directory:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
# Add the export line to your ~/.zshrc or ~/.bashrc
npm install -g @proletariat/cli

Or use Homebrew instead (macOS):

brew install chrismcdermut/proletariat/prlt

Native module errors after install

Symptom: prlt runs but crashes with better_sqlite3.node or ABI mismatch errors.

Fix:

# Rebuild for the current Node version
npm rebuild better-sqlite3

# Verify it works
node -e "require('better-sqlite3')"

# If still failing, reinstall
npm install -g @proletariat/cli --force

See the full troubleshooting guide for more details.

---

Support

• Discord: discord.gg/tmZyjNNSvw
• GitHub Issues: Report bugs or request features
• Setup Help: [Book a call][cal-link] - I'll help you get things running

---

License

Apache 2.0

---

Star on GitHub | Install from NPM | Report Issues

Made with ⚒️ by the proletariat.

[cal-link]: https://cal.com/chrismcdermut