superx

One prompt → finished project. 14 specialized agents, 10-parallel execution, project-specific skill learning, mechanical checkpointing, ~75% token savings. Beats raw Claude Code usage.

hljs language-bash

curl -fsSL https://raw.githubusercontent.com/randomittin/superx/main/install.sh | bash

What is superx?

superx makes Claude Code dramatically more capable than using it directly:

14 specialized agents (security auditor, database architect, incident responder, etc.) — each with the right model + effort level
10-parallel execution — independent files/projects run simultaneously, not sequentially
Project-specific skill learning — extracts patterns from your codebase into .planning/skills/, applies them on future tasks. Gets better with every run.
Mechanical checkpointing — /superx:checkpoint saves state + project settings. Next session resumes with full context injected into the prompt. Zero context loss between sessions.
Wave-based planning with acceptance gates — tasks grouped by dependency, verified before and after execution, truth-scored 0.0-1.0
~75% token savings via caveman ultra mode + model routing (Haiku for lint, Sonnet for docs, Opus for code)
Pixel-art dashboard — isometric city map, war room, streaming logs, session history
Auto-escalation — task fails on Haiku → retry on Sonnet → retry on Opus. Never waste expensive tokens, never ship bad code.

Keywords: Claude Code plugin, Claude AI agent, Anthropic, autonomous coding agent, multi-agent orchestration, AI pair programmer, LLM agent framework, developer automation, CTO-level AI, parallel agent execution, pixel-art dashboard, wave-based execution, acceptance criteria gates, token compression, caveman mode, cross-session memory, autonomous repo maintenance.

Features

One prompt → finished project. Drop a task in, get a working repo back.
Hybrid planning pipeline. Complexity-aware: simple tasks execute directly, medium/complex go through planning → parallel execution → verification.
Wave-based parallel execution. Tasks grouped into dependency waves. Each wave runs in parallel with fresh 200K-token context — no context rot.
Acceptance criteria as blocking gates. Every task has runnable checks (grep, curl, test commands). Tasks cannot advance until all criteria pass.
Plan verification before execution. Plans validated up to 3 iterations before code is written.
File-based state in .planning/. Human-readable Markdown committed to git. Survives /clear.
Question-mark protocol. Claude only stops to ask when it actually needs you. Dashboard surfaces the question with quick-pick buttons.
Conversation continuity. Replies use claude --resume <session_id> for full context.
Real-time pixel dashboard. Isometric city map, war room, streaming logs, day/night theme, history drawer.
Companion plugins auto-installed. caveman (~75% token savings), superpowers (brainstorming), claude-mem (persistent memory).
Quality gates. Tests, lint, code review — enforced via hooks before any push.
Atomic commits per task. Each task = one git commit. Bisectable, revertable.
Auto-checkpointing. Background git commits + crash recovery.
Maintainer mode. Autonomous repo maintenance — triage, fix, test, batch release.
Token budgets. Set a budget, get warned at 80%.
GitHub integration. One-click commit + push from the dashboard.

Quick start

One-line install

hljs language-bash

curl -fsSL https://raw.githubusercontent.com/randomittin/superx/main/install.sh | bash

This installs Node.js (if missing) → Claude Code → superx → companion plugins (caveman, superpowers, claude-mem). Then:

hljs language-bash

source ~/.zshrc   # or open a new terminal
cd /path/to/your/project
superx "build a real-time dashboard with auth and charts"

Or install via Claude Code plugin marketplace

hljs language-bash

claude plugins marketplace add randomittin/superx-marketplace
claude plugins install superx

Or install manually

hljs language-bash

git clone https://github.com/randomittin/superx.git ~/.superx
export PATH="$PATH:$HOME/.superx/bin"

Prerequisites

Claude Code 1.0+ with valid auth (install guide)
Python 3.11+ (for the dashboard; stdlib only, no pip install)
Git

Usage

hljs language-bash

superx "deploy to vercel"           # Run a task end-to-end
superx                              # Interactive Claude session with superx powers
superx --dashboard                  # Pixel dashboard (http://localhost:8080)
superx --team 5 "build auth"        # 5 parallel Claude workers in tmux
superx --resume                     # Resume last session with full context
superx --auto "build X"             # Auto-mode (safer than skip-permissions)
superx --skip-checkpoint "fresh"    # Start fresh, ignore last checkpoint

Lifecycle commands

hljs language-bash

superx --update                     # Pull latest + show color-coded changelog
superx --reinstall                  # Nuke and re-clone (fixes zombie states)
superx --setup                      # Re-install companion plugins
superx --uninstall                  # Remove superx (with sad goodbye animation)
superx --help                       # Show all flags

In-session commands

hljs language-bash

/superx:save                        # Save checkpoint for next session
/superx:status                      # Show project state + quality gates
/superx:level +                     # Cycle autonomy level (Guided → Checkpoint → Full Auto)
/superx:maintain                    # Activate autonomous repo maintenance

superx launches Claude Code with:

--dangerously-skip-permissions — full autonomy
--plugin-dir <superx> — 14 specialized agents loaded
--agent superx — CTO-level orchestrator
caveman ultra — ~75% token savings
superpowers — brainstorming, debugging, skill-creator
claude-mem — persistent cross-session memory

Dashboard mode

hljs language-bash

cd /path/to/your/project
superx --dashboard
# open http://localhost:8080

Auto-sets the current directory as the project. Click + NEW to start a fresh project with a native folder picker.

How it works — the hybrid pipeline

superx assesses every incoming task and routes it through the right level of planning:

hljs language-sql

User prompt
    ↓
Assess complexity
    ├── Simple (single-file fix, config, question)
    │     → Execute directly. No planning overhead.
    │
    ├── Medium (feature addition, 2-5 file bug)
    │     → Lightweight plan with acceptance criteria → execute → verify
    │
    └── Complex (new project, major feature, 6+ files)
          → Full pipeline ↓

Init .planning/ in project dir
    ↓
Discuss — analyze codebase, surface assumptions → CONTEXT.md
    ↓
Plan — planner agent creates PLAN-{phase}.md
    • Tasks grouped into dependency waves
    • Each task: read_first, action, acceptance_criteria, verify, done
    • Self-verification loop (max 3 iterations)
    ↓
Execute — wave by wave, parallel within each wave
    • Wave 1 (no deps) → fresh context, parallel subagents
    • Wave 2 (depends on 1) → fresh context, parallel subagents
    • Each task = atomic git commit
    • Acceptance criteria BLOCK progression
    ↓
Verify — verifier checks ALL criteria + requirement coverage
    • PASS → ship
    • FAIL → diagnosis + fix plan → re-execute

Why fresh context per wave?

After 4-5 agents complete work and report back, accumulated conversation history can exceed 100K+ tokens. The next wave's agents would be working in degraded context. Instead, each wave gets a clean 200K-token window — just the plan, the context doc, and the source files it needs. No garbage from prior waves.

Why acceptance criteria as gates?

A task like "Create login API" isn't done when code is written. It's done when:

hljs language-bash

grep "export const login" src/api.ts       # function exists
curl -s localhost:3000/api/login | jq .    # endpoint responds
npm test -- --grep "auth"                   # tests pass

These are blocking — the wave-executor won't commit until all pass. If they fail after 2 fix attempts, the task is marked BLOCKED and the orchestrator escalates.

`.planning/` state directory

All planning state lives as human-readable Markdown in your project's .planning/ directory:

File	Purpose
`PROJECT.md`	Vision, constraints, tech stack
`REQUIREMENTS.md`	v1 (must-have), v2 (next), out-of-scope
`STATE.md`	Living memory: current phase, decisions, blockers, metrics. YAML frontmatter derived from body content (rebuilt on every write).
`CONTEXT.md`	Per-phase user preferences + codebase assumptions
`PLAN-{phase}.md`	Task specifications with waves, acceptance criteria, dependencies
`SUMMARY-{phase}.md`	Execution results with commit hashes

These files are:

Human-readable — open them in any editor
Git-committable — track planning decisions in version history
Session-surviving — persist across /clear and server restarts
Concurrent-safe — lockfile-based mutual exclusion for parallel agents

Agent roster

Agent	Role	Model	Effort	When spawned
`superx`	Main orchestrator	Opus	max	Always (session agent)
`architect`	Decomposition + planning	Opus	high	Complex tasks
`planner`	Wave-grouped plans + acceptance criteria	Opus	high	Medium + complex tasks
`wave-executor`	Execute one wave (up to 10 parallel)	Opus	high	Per wave during execution
`verifier`	Sentinel gate + truth scoring	Opus	high	After each phase
`coder`	Feature implementation	Opus	high	Simple + within waves
`design`	UI/UX design	Opus	high	When UI work detected
`security-auditor`	OWASP, secrets scan, auth review	Opus	max	Complex tasks with auth/API
`database-architect`	Schema, migrations, query optimization	Opus	high	Data layer tasks
`incident-responder`	Triage, diagnose, mitigate, postmortem	Opus	max	Production fires
`reviewer`	Code review before push	Opus	high	Quality gate
`test-runner`	Test writing and execution	Sonnet	default	Quality gate
`docs-writer`	Documentation	Sonnet	default	Post-execution
`lint-quality`	Lint and formatting	Haiku	low	Quality gate

Architecture

hljs language-perl

superx/
├── .claude-plugin/plugin.json    # Plugin manifest (v1.0.0)
├── agents/                       # 14 specialized agent definitions
│   ├── superx.md                 # Main orchestrator (Opus)
│   ├── architect.md              # Decomposition + planning (Opus)
│   ├── planner.md                # Structured plans with acceptance criteria
│   ├── wave-executor.md          # Per-wave parallel execution
│   ├── verifier.md               # Post-execution verification
│   ├── coder.md                  # Implementation (Opus/high)
│   ├── design.md                 # UI/UX (Opus/high)
│   ├── security-auditor.md       # OWASP + secrets scan (Opus/max)
│   ├── database-architect.md     # Schema + migrations (Opus/high)
│   ├── incident-responder.md     # Production fires (Opus/max)
│   ├── reviewer.md               # Code review (Opus/high)
│   ├── test-runner.md            # Tests (Sonnet/default)
│   ├── docs-writer.md            # Docs (Sonnet/default)
│   └── lint-quality.md           # Lint (Haiku/low)
├── skills/superx/                # Main skill + reference docs
├── commands/                     # Slash commands
├── hooks/
│   ├── hooks.json                # Quality gate hooks (4 event types)
│   └── statusline.sh             # HUD for Claude Code status bar
├── bin/                          # CLI tools
│   ├── superx                    # Main launcher (self-bootstrapping)
│   ├── lib/planning.sh           # .planning/ state management
│   ├── lib/dispatch.sh           # File-based task dispatch queue
│   ├── superx-state              # State CRUD
│   ├── detect-skills             # Skill inventory
│   ├── conflict-log              # Conflict tracking
│   └── authenticity-check        # Package verification
├── ui/                           # Pixel dashboard
│   ├── server.py                 # Stdlib HTTP + SSE server (auto-updates on startup)
│   └── static/                   # HTML/CSS/JS + 35 sprite tiles
├── docs/superpowers/specs/       # Design docs
├── install.sh                    # One-line installer
├── settings.json                 # Default settings
├── CHANGELOG.md
├── LICENSE                       # MIT
└── README.md                     # This file

Companion plugins (auto-installed)

Plugin	What it does	Impact
caveman	Terse output compression	~65-75% output token savings
superpowers	Brainstorming, debugging, skill-creator	Better planning + design quality
claude-mem	Persistent memory across sessions	No repeated context between sessions

All three are installed automatically on first run (superx --setup to re-run).

Dashboard

How it works

Set the project directory — click + NEW or the GitHub icon, browse for a folder or type a path.
Type a task in the prompt bar and hit RUN.
Watch the timeline (left) and logs panel (right) update in real time. The map tab renders your project as an isometric city.
If Claude needs input, the awaiting-input panel opens with the question, auto-detected option buttons, and a SEND button.
When done, the session is archived to the history drawer (clock icon).

Map controls

Control	Action
+ / −	Zoom
Sun/Moon	Day / dawn / dusk / night theme
⛶	Fullscreen
Drag	Pan
Hover	Building tooltip with package name + file count

Status badges

Badge	Meaning
`IDLE`	Nothing running
`RUNNING`	Claude subprocess actively streaming
`AWAITING INPUT`	Claude finished with a question, waiting on you
`ERROR`	Subprocess exited non-zero

Autonomy levels

Level	Name	Behavior
1	Guided	Asks approval on every action
2	Checkpoint	Runs autonomously, pauses at milestones (default)
3	Full Auto	Runs until complete or blocked

Change with /superx:level <1|2|3> or cycle with /superx:level + / -.

Slash commands

Command	Description
`/superx:level <1\|2\|3\|+\|->`	Set or cycle autonomy level
`/superx:status`	Show project state and quality gates
`/superx:maintain [on\|off\|status]`	Activate maintainer mode
`/superx:maintain-check [--dry-run]`	Run one maintenance cycle
`/superx:reflect`	Force a conflict reflection pass

Quality gates

Every push must pass:

All tests passing
Lint clean (zero warnings)
Conflict reflection done
Code review completed
No dirty (untested) changes

Enforced via hooks/hooks.json PreToolUse hook on git push.

Maintainer mode

hljs language-bash

/superx:maintain

Continuous repo maintenance: triage → fix → test → review → batch release.

Severity x Confidence	Action
Critical x Any	Alert + hotfix + human approval
High x High	Auto-fix + PR + request review
Medium/Low x High	Auto-fix, batch into patch release
Any x Low	Escalate with context

Requirements

Claude Code 1.0+ (install guide)
Python 3.11+ (stdlib only)
Git
jq (for state helpers): brew install jq
gh CLI (optional): brew install gh

Troubleshooting

Problem	Fix
`superx --update` says "Already up to date" but you're behind	Run `superx --reinstall` — nukes `~/.superx` and re-clones fresh from GitHub. Your projects are not affected.
"Set a project directory first"	Click `+ NEW` or GitHub icon, enter path
Map shows old project	Click `+ NEW`, set the new path — map auto-refreshes
Awaiting panel never appears	Claude's response must end with `?`. Check system preamble isn't overridden
"Resuming from checkpoint" loop	Click STOP. Delete `superx-checkpoint.json` + `superx-session.json`. Restart server
Page won't load	Default port 8080. Override: `SUPERX_PORT=9090 python ui/server.py`
`superx: command not found`	Run `source ~/.zshrc` or add `export PATH="$PATH:$HOME/.superx/bin"` to your shell profile
SSH permission denied on install	The marketplace uses HTTPS. Run `claude plugins marketplace update superx-marketplace`

Tips and tricks

Safer alternative to skip-permissions

hljs language-bash

superx --auto "build X"     # uses --permission-mode auto instead

Auto-mode uses a background safety classifier — blocks prompt injection and risky escalation while still letting superx work autonomously.

Project memory via CLAUDE.md

superx auto-generates a CLAUDE.md in your project root on first run. This file survives /clear and session restarts — Claude reads it on every new session for persistent project conventions, architecture notes, and style rules.

Flicker-free rendering

superx sets CLAUDE_CODE_NO_FLICKER=1 automatically for stable alt-screen rendering with mouse support. No configuration needed.

Recovery from errors

hljs language-bash

# Inside Claude Code:
/rewind                    # undo recent changes
# or press Esc Esc

# Outside:
superx --resume            # continue last conversation with full context

Voice input

hljs language-bash

# Inside a superx session:
/voice                     # push-to-talk, 20 languages

Remote control

hljs language-bash

# Inside a superx session:
/rc                        # continue from phone/tablet/browser

Parallel sessions with git worktrees

superx's wave-executor already uses isolation: worktree for parallel tasks. For manual multi-session work:

hljs language-bash

# Terminal 1:
cd /project && superx "build auth"

# Terminal 2:
cd /project && superx "build dashboard"

Each gets its own git worktree — no conflicts.

Chrome integration

hljs language-bash

claude --chrome --plugin-dir ~/.superx   # browser automation

Test web apps, debug console, automate forms, extract data.

Scheduled background tasks

hljs language-bash

# Inside a superx session:
/loop "run tests and report failures"     # local, recurring
/schedule "check for dependency updates"  # cloud, Anthropic infrastructure

Inspired by

get-shit-done — wave-based execution, acceptance criteria gates, .planning/ state files, plan verification loops
caveman — token compression via terse communication
claude-mem — persistent cross-session memory
claude-code-best-practice — comprehensive tips, tricks, and workflow patterns

Contributing

PRs welcome. See CHANGELOG.md for release history and docs/superpowers/specs/ for design docs.

License

MIT

superx

superx

Quick start

One-line install

Or install via Claude Code plugin marketplace

Or install manually

Prerequisites

Usage

Lifecycle commands

In-session commands

Dashboard mode

How it works — the hybrid pipeline

Why fresh context per wave?

Why acceptance criteria as gates?

.planning/ state directory

Agent roster

Architecture

Companion plugins (auto-installed)

Dashboard

How it works

Map controls

Status badges

Autonomy levels

Slash commands

Quality gates

Maintainer mode

Requirements

Troubleshooting

Tips and tricks

Safer alternative to skip-permissions

Project memory via CLAUDE.md

Flicker-free rendering

Recovery from errors

Voice input

Remote control

Parallel sessions with git worktrees

Chrome integration

Scheduled background tasks

Inspired by

Contributing

License

Similar Packages

Repository

Tags

Original Author

Publisher

Repository

`.planning/` state directory