{"id":49026793,"url":"https://github.com/randomittin/superx","last_synced_at":"2026-04-19T07:02:19.573Z","repository":{"id":349523606,"uuid":"1202700430","full_name":"randomittin/superx","owner":"randomittin","description":"One prompt → finished project. Autonomous Claude Code agent with wave-based parallel execution, pixel-art dashboard, and ~75% token savings.","archived":false,"fork":false,"pushed_at":"2026-04-19T06:18:29.000Z","size":5242,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T07:02:14.365Z","etag":null,"topics":["agent-orchestration","ai-agent","ai-coding","ai-orchestration","anthropic","automation","autonomous-agent","claude-agent","claude-ai","claude-code","claude-plugin","claude-skill","cli","coding-assistant","developer-tools","devtools","llm-agent","llm-framework","llm-tools","multi-agent"],"latest_commit_sha":null,"homepage":"https://github.com/randomittin/superx#readme","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/randomittin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T09:57:34.000Z","updated_at":"2026-04-19T06:18:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/randomittin/superx","commit_stats":null,"previous_names":["randomittin/superx"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/randomittin/superx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fsuperx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fsuperx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fsuperx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fsuperx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/randomittin","download_url":"https://codeload.github.com/randomittin/superx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randomittin%2Fsuperx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31997808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","ai-agent","ai-coding","ai-orchestration","anthropic","automation","autonomous-agent","claude-agent","claude-ai","claude-code","claude-plugin","claude-skill","cli","coding-assistant","developer-tools","devtools","llm-agent","llm-framework","llm-tools","multi-agent"],"created_at":"2026-04-19T07:02:14.339Z","updated_at":"2026-04-19T07:02:19.565Z","avatar_url":"https://github.com/randomittin.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# superx\n\n**One prompt → finished project.** Autonomous [Claude Code](https://code.claude.com) agent that plans, executes in parallel, verifies, and ships.\n\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-e056a0?style=flat-square)](https://code.claude.com)\n[![License: MIT](https://img.shields.io/badge/License-MIT-9b59b6?style=flat-square)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0.0-00d4ff?style=flat-square)](CHANGELOG.md)\n[![Install](https://img.shields.io/badge/install-curl-4ecca3?style=flat-square)](#quick-start)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/randomittin/superx/main/install.sh | bash\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat is superx?\u003c/strong\u003e\u003c/summary\u003e\n\nsuperx is an autonomous superskill manager for [Claude Code](https://code.claude.com) by [Anthropic](https://www.anthropic.com). It assesses task complexity, creates structured plans with acceptance criteria, executes in parallel waves with fresh context per wave, verifies everything, and ships — with the judgment of a senior dev / CTO.\n\nA real-time **pixel-art dashboard** ships with the plugin so you can watch the work happen: a live isometric city map of your project, a war room of agents, streaming logs, and a timeline of every decision.\n\n**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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFeatures\u003c/strong\u003e\u003c/summary\u003e\n\n- **One prompt → finished project.** Drop a task in, get a working repo back.\n- **Hybrid planning pipeline.** Complexity-aware: simple tasks execute directly, medium/complex go through planning → parallel execution → verification.\n- **Wave-based parallel execution.** Tasks grouped into dependency waves. Each wave runs in parallel with fresh 200K-token context — no context rot.\n- **Acceptance criteria as blocking gates.** Every task has runnable checks (grep, curl, test commands). Tasks cannot advance until all criteria pass.\n- **Plan verification before execution.** Plans validated up to 3 iterations before code is written.\n- **File-based state in `.planning/`.** Human-readable Markdown committed to git. Survives `/clear`.\n- **Question-mark protocol.** Claude only stops to ask when it actually needs you. Dashboard surfaces the question with quick-pick buttons.\n- **Conversation continuity.** Replies use `claude --resume \u003csession_id\u003e` for full context.\n- **Real-time pixel dashboard.** Isometric city map, war room, streaming logs, day/night theme, history drawer.\n- **Companion plugins auto-installed.** caveman (~75% token savings), superpowers (brainstorming), claude-mem (persistent memory).\n- **Quality gates.** Tests, lint, code review — enforced via hooks before any push.\n- **Atomic commits per task.** Each task = one git commit. Bisectable, revertable.\n- **Auto-checkpointing.** Background git commits + crash recovery.\n- **Maintainer mode.** Autonomous repo maintenance — triage, fix, test, batch release.\n- **Token budgets.** Set a budget, get warned at 80%.\n- **GitHub integration.** One-click commit + push from the dashboard.\n\n\u003c/details\u003e\n\n---\n\n## Quick start\n\n### One-line install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/randomittin/superx/main/install.sh | bash\n```\n\nThis installs Node.js (if missing) → Claude Code → superx → companion plugins (caveman, superpowers, claude-mem). Then:\n\n```bash\nsource ~/.zshrc   # or open a new terminal\ncd /path/to/your/project\nsuperx \"build a real-time dashboard with auth and charts\"\n```\n\n### Or install via Claude Code plugin marketplace\n\n```bash\nclaude plugins marketplace add randomittin/superx-marketplace\nclaude plugins install superx\n```\n\n### Or install manually\n\n```bash\ngit clone https://github.com/randomittin/superx.git ~/.superx\nexport PATH=\"$PATH:$HOME/.superx/bin\"\n```\n\n### Prerequisites\n\n- **Claude Code** 1.0+ with valid auth ([install guide](https://docs.claude.com/en/docs/claude-code/setup))\n- **Python** 3.11+ (for the dashboard; stdlib only, no pip install)\n- **Git**\n\n---\n\n## Usage\n\n```bash\nsuperx \"deploy to vercel\"     # Run a task end-to-end\nsuperx                        # Interactive Claude session with superx powers\nsuperx --dashboard            # Start the pixel dashboard (http://localhost:8080)\nsuperx --update               # Pull latest version from GitHub\nsuperx --setup                # Re-run companion plugin setup\nsuperx --help                 # Show help\n```\n\nsuperx launches Claude Code with:\n- `--dangerously-skip-permissions` — full autonomy\n- `--plugin-dir \u003csuperx\u003e` — all superx agents + skills loaded\n- `--agent superx` — CTO-level orchestrator as main agent\n- **caveman** — token compression (~65-75% savings)\n- **superpowers** — brainstorming, debugging, skill-creator\n- **claude-mem** — persistent memory across sessions\n\n### Dashboard mode\n\n```bash\ncd /path/to/your/project\nsuperx --dashboard\n# open http://localhost:8080\n```\n\nAuto-sets the current directory as the project. Click `+ NEW` to start a fresh project with a native folder picker.\n\n---\n\n## How it works — the hybrid pipeline\n\nsuperx assesses every incoming task and routes it through the right level of planning:\n\n```\nUser prompt\n    ↓\nAssess complexity\n    ├── Simple (single-file fix, config, question)\n    │     → Execute directly. No planning overhead.\n    │\n    ├── Medium (feature addition, 2-5 file bug)\n    │     → Lightweight plan with acceptance criteria → execute → verify\n    │\n    └── Complex (new project, major feature, 6+ files)\n          → Full pipeline ↓\n\nInit .planning/ in project dir\n    ↓\nDiscuss — analyze codebase, surface assumptions → CONTEXT.md\n    ↓\nPlan — planner agent creates PLAN-{phase}.md\n    • Tasks grouped into dependency waves\n    • Each task: read_first, action, acceptance_criteria, verify, done\n    • Self-verification loop (max 3 iterations)\n    ↓\nExecute — wave by wave, parallel within each wave\n    • Wave 1 (no deps) → fresh context, parallel subagents\n    • Wave 2 (depends on 1) → fresh context, parallel subagents\n    • Each task = atomic git commit\n    • Acceptance criteria BLOCK progression\n    ↓\nVerify — verifier checks ALL criteria + requirement coverage\n    • PASS → ship\n    • FAIL → diagnosis + fix plan → re-execute\n```\n\n### Why fresh context per wave?\n\nAfter 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.\n\n### Why acceptance criteria as gates?\n\nA task like \"Create login API\" isn't done when code is written. It's done when:\n```\ngrep \"export const login\" src/api.ts       # function exists\ncurl -s localhost:3000/api/login | jq .    # endpoint responds\nnpm test -- --grep \"auth\"                   # tests pass\n```\n\nThese 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.\n\n---\n\n## `.planning/` state directory\n\nAll planning state lives as human-readable Markdown in your project's `.planning/` directory:\n\n| File | Purpose |\n|---|---|\n| `PROJECT.md` | Vision, constraints, tech stack |\n| `REQUIREMENTS.md` | v1 (must-have), v2 (next), out-of-scope |\n| `STATE.md` | Living memory: current phase, decisions, blockers, metrics. YAML frontmatter derived from body content (rebuilt on every write). |\n| `CONTEXT.md` | Per-phase user preferences + codebase assumptions |\n| `PLAN-{phase}.md` | Task specifications with waves, acceptance criteria, dependencies |\n| `SUMMARY-{phase}.md` | Execution results with commit hashes |\n\nThese files are:\n- **Human-readable** — open them in any editor\n- **Git-committable** — track planning decisions in version history\n- **Session-surviving** — persist across `/clear` and server restarts\n- **Concurrent-safe** — lockfile-based mutual exclusion for parallel agents\n\n---\n\n## Agent roster\n\n| Agent | Role | Model | Effort | When spawned |\n|---|---|---|---|---|\n| `superx` | Main orchestrator | Opus | max | Always (session agent) |\n| `architect` | Decomposition + planning | Opus | high | Complex tasks |\n| `planner` | Wave-grouped plans + acceptance criteria | Opus | high | Medium + complex tasks |\n| `wave-executor` | Execute one wave (up to 10 parallel) | Opus | high | Per wave during execution |\n| `verifier` | Sentinel gate + truth scoring | Opus | high | After each phase |\n| `coder` | Feature implementation | Opus | high | Simple + within waves |\n| `design` | UI/UX design | Opus | high | When UI work detected |\n| `security-auditor` | OWASP, secrets scan, auth review | Opus | max | Complex tasks with auth/API |\n| `database-architect` | Schema, migrations, query optimization | Opus | high | Data layer tasks |\n| `incident-responder` | Triage, diagnose, mitigate, postmortem | Opus | max | Production fires |\n| `reviewer` | Code review before push | Opus | high | Quality gate |\n| `test-runner` | Test writing and execution | Sonnet | default | Quality gate |\n| `docs-writer` | Documentation | Sonnet | default | Post-execution |\n| `lint-quality` | Lint and formatting | Haiku | low | Quality gate |\n\n---\n\n## Architecture\n\n```\nsuperx/\n├── .claude-plugin/plugin.json    # Plugin manifest (v1.0.0)\n├── agents/                       # 14 specialized agent definitions\n│   ├── superx.md                 # Main orchestrator (Opus)\n│   ├── architect.md              # Decomposition + planning (Opus)\n│   ├── planner.md                # Structured plans with acceptance criteria\n│   ├── wave-executor.md          # Per-wave parallel execution\n│   ├── verifier.md               # Post-execution verification\n│   ├── coder.md                  # Implementation (Opus/high)\n│   ├── design.md                 # UI/UX (Opus/high)\n│   ├── security-auditor.md       # OWASP + secrets scan (Opus/max)\n│   ├── database-architect.md     # Schema + migrations (Opus/high)\n│   ├── incident-responder.md     # Production fires (Opus/max)\n│   ├── reviewer.md               # Code review (Opus/high)\n│   ├── test-runner.md            # Tests (Sonnet/default)\n│   ├── docs-writer.md            # Docs (Sonnet/default)\n│   └── lint-quality.md           # Lint (Haiku/low)\n├── skills/superx/                # Main skill + reference docs\n├── commands/                     # Slash commands\n├── hooks/\n│   ├── hooks.json                # Quality gate hooks (4 event types)\n│   └── statusline.sh             # HUD for Claude Code status bar\n├── bin/                          # CLI tools\n│   ├── superx                    # Main launcher (self-bootstrapping)\n│   ├── lib/planning.sh           # .planning/ state management\n│   ├── lib/dispatch.sh           # File-based task dispatch queue\n│   ├── superx-state              # State CRUD\n│   ├── detect-skills             # Skill inventory\n│   ├── conflict-log              # Conflict tracking\n│   └── authenticity-check        # Package verification\n├── ui/                           # Pixel dashboard\n│   ├── server.py                 # Stdlib HTTP + SSE server (auto-updates on startup)\n│   └── static/                   # HTML/CSS/JS + 35 sprite tiles\n├── docs/superpowers/specs/       # Design docs\n├── install.sh                    # One-line installer\n├── settings.json                 # Default settings\n├── CHANGELOG.md\n├── LICENSE                       # MIT\n└── README.md                     # This file\n```\n\n---\n\n## Companion plugins (auto-installed)\n\n| Plugin | What it does | Impact |\n|---|---|---|\n| **[caveman](https://github.com/juliusbrussee/caveman)** | Terse output compression | ~65-75% output token savings |\n| **[superpowers](https://github.com/anthropics/claude-plugins-official)** | Brainstorming, debugging, skill-creator | Better planning + design quality |\n| **[claude-mem](https://github.com/thedotmack/claude-mem)** | Persistent memory across sessions | No repeated context between sessions |\n\nAll three are installed automatically on first run (`superx --setup` to re-run).\n\n---\n\n## Dashboard\n\n### How it works\n\n1. **Set the project directory** — click `+ NEW` or the GitHub icon, browse for a folder or type a path.\n2. **Type a task** in the prompt bar and hit RUN.\n3. Watch the **timeline** (left) and **logs panel** (right) update in real time. The **map tab** renders your project as an isometric city.\n4. If Claude needs input, the **awaiting-input panel** opens with the question, auto-detected option buttons, and a SEND button.\n5. When done, the session is archived to the **history drawer** (clock icon).\n\n### Map controls\n\n| Control | Action |\n|---|---|\n| **+ / −** | Zoom |\n| **Sun/Moon** | Day / dawn / dusk / night theme |\n| **⛶** | Fullscreen |\n| **Drag** | Pan |\n| **Hover** | Building tooltip with package name + file count |\n\n### Status badges\n\n| Badge | Meaning |\n|---|---|\n| `IDLE` | Nothing running |\n| `RUNNING` | Claude subprocess actively streaming |\n| `AWAITING INPUT` | Claude finished with a question, waiting on you |\n| `ERROR` | Subprocess exited non-zero |\n\n---\n\n## Autonomy levels\n\n| Level | Name | Behavior |\n|---|---|---|\n| 1 | Guided | Asks approval on every action |\n| 2 | Checkpoint | Runs autonomously, pauses at milestones (default) |\n| 3 | Full Auto | Runs until complete or blocked |\n\nChange with `/superx:level \u003c1|2|3\u003e` or cycle with `/superx:level +` / `-`.\n\n---\n\n## Slash commands\n\n| Command | Description |\n|---|---|\n| `/superx:level \u003c1\\|2\\|3\\|+\\|-\u003e` | Set or cycle autonomy level |\n| `/superx:status` | Show project state and quality gates |\n| `/superx:maintain [on\\|off\\|status]` | Activate maintainer mode |\n| `/superx:maintain-check [--dry-run]` | Run one maintenance cycle |\n| `/superx:reflect` | Force a conflict reflection pass |\n\n---\n\n## Quality gates\n\nEvery push must pass:\n1. All tests passing\n2. Lint clean (zero warnings)\n3. Conflict reflection done\n4. Code review completed\n5. No dirty (untested) changes\n\nEnforced via `hooks/hooks.json` PreToolUse hook on `git push`.\n\n---\n\n## Maintainer mode\n\n```bash\n/superx:maintain\n```\n\nContinuous repo maintenance: triage → fix → test → review → batch release.\n\n| Severity x Confidence | Action |\n|---|---|\n| Critical x Any | Alert + hotfix + human approval |\n| High x High | Auto-fix + PR + request review |\n| Medium/Low x High | Auto-fix, batch into patch release |\n| Any x Low | Escalate with context |\n\n---\n\n## Requirements\n\n- **Claude Code** 1.0+ ([install guide](https://docs.claude.com/en/docs/claude-code/setup))\n- **Python** 3.11+ (stdlib only)\n- **Git**\n- **`jq`** (for state helpers): `brew install jq`\n- **`gh` CLI** (optional): `brew install gh`\n\n---\n\n## Troubleshooting\n\n| Problem | Fix |\n|---|---|\n| \"Set a project directory first\" | Click `+ NEW` or GitHub icon, enter path |\n| Map shows old project | Click `+ NEW`, set the new path — map auto-refreshes |\n| Awaiting panel never appears | Claude's response must end with `?`. Check system preamble isn't overridden |\n| \"Resuming from checkpoint\" loop | Click STOP. Delete `superx-checkpoint.json` + `superx-session.json`. Restart server |\n| Page won't load | Default port 8080. Override: `SUPERX_PORT=9090 python ui/server.py` |\n| `superx: command not found` | Run `source ~/.zshrc` or add `export PATH=\"$PATH:$HOME/.superx/bin\"` to your shell profile |\n| SSH permission denied on install | The marketplace uses HTTPS. Run `claude plugins marketplace update superx-marketplace` |\n\n---\n\n## Tips and tricks\n\n### Safer alternative to skip-permissions\n\n```bash\nsuperx --auto \"build X\"     # uses --permission-mode auto instead\n```\n\nAuto-mode uses a background safety classifier — blocks prompt injection and risky escalation while still letting superx work autonomously.\n\n### Project memory via CLAUDE.md\n\nsuperx 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.\n\n### Flicker-free rendering\n\nsuperx sets `CLAUDE_CODE_NO_FLICKER=1` automatically for stable alt-screen rendering with mouse support. No configuration needed.\n\n### Recovery from errors\n\n```bash\n# Inside Claude Code:\n/rewind                    # undo recent changes\n# or press Esc Esc\n\n# Outside:\nsuperx --resume            # continue last conversation with full context\n```\n\n### Voice input\n\n```bash\n# Inside a superx session:\n/voice                     # push-to-talk, 20 languages\n```\n\n### Remote control\n\n```bash\n# Inside a superx session:\n/rc                        # continue from phone/tablet/browser\n```\n\n### Parallel sessions with git worktrees\n\nsuperx's wave-executor already uses `isolation: worktree` for parallel tasks. For manual multi-session work:\n\n```bash\n# Terminal 1:\ncd /project \u0026\u0026 superx \"build auth\"\n\n# Terminal 2:\ncd /project \u0026\u0026 superx \"build dashboard\"\n```\n\nEach gets its own git worktree — no conflicts.\n\n### Chrome integration\n\n```bash\nclaude --chrome --plugin-dir ~/.superx   # browser automation\n```\n\nTest web apps, debug console, automate forms, extract data.\n\n### Scheduled background tasks\n\n```bash\n# Inside a superx session:\n/loop \"run tests and report failures\"     # local, recurring\n/schedule \"check for dependency updates\"  # cloud, Anthropic infrastructure\n```\n\n---\n\n## Inspired by\n\n- **[get-shit-done](https://github.com/gsd-build/get-shit-done)** — wave-based execution, acceptance criteria gates, `.planning/` state files, plan verification loops\n- **[caveman](https://github.com/juliusbrussee/caveman)** — token compression via terse communication\n- **[claude-mem](https://github.com/thedotmack/claude-mem)** — persistent cross-session memory\n- **[claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)** — comprehensive tips, tricks, and workflow patterns\n\n---\n\n## Contributing\n\nPRs welcome. See [CHANGELOG.md](CHANGELOG.md) for release history and [docs/superpowers/specs/](docs/superpowers/specs/) for design docs.\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandomittin%2Fsuperx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frandomittin%2Fsuperx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandomittin%2Fsuperx/lists"}