Swux transforms high-level natural language goals into production-ready software systems. It operates as a parallel execution plane, background state tracker, and interactive playground for AI coding agents. Run complex agent loops, parallel build pipelines, or sandboxed assistants in isolated workspaces, keeping your main thread clean and your host machine safe.
Spawn parallel AI coding agents, each in its own git worktree. Agents autonomously fix CI failures, address review comments, and open PRs — you supervise and approve operations from one local dashboard.
| Target Audience | The Specific Pain Point Swux Solves |
|---|---|
| AI App Developers | "Stop letting your LLM loops freeze your main application thread. Offload heavy agent scripts to background environments with strict state tracking." |
| DevOps / CI Engineers | "Ditch messy, un-trackable nohup or & shell background scripts. Run local parallel build pipelines with built-in state checking and notifications." |
| Local Agent Builders | "Give your local coding assistant a safe sandbox execution plane that you can visually intercept, pause, or audit at any second." |
Swux manages fleets of AI coding agents working in parallel on your codebase. Each agent gets its own git worktree, its own branch, and its own PR. When CI fails, the agent fixes it. When reviewers leave comments, the agent addresses them. You only get pulled in when human judgment is needed.
Agent-agnostic (Claude Code, Codex, Aider, OpenCode) · Runtime-agnostic (tmux, ConPTY/process, Docker) · Tracker-agnostic (GitHub, Linear)
graph TD
A[Natural Language Goal] --> B[swux build / swux research]
B --> C[Interactive Discovery & Web Scraping]
C --> D[Architectural Blueprint .swux/blueprint.yaml]
D --> E[swux spawn --goal ID]
E --> F[Parallel Coding Agents in Git Worktrees]
F --> G[Next.js Web Dashboard & PRs]
Run swux build "<your-goal>" to start an interactive design interview. Swux queries you for project details, tech stack preferences, data models, and API endpoints, creating a robust system design.
Before coding, let the AI scrape the web to find APIs, libraries, or concepts. Run:
swux research "claude mobile app skills" --type generalSwux scrapes DuckDuckGo, arXiv, and PubMed in parallel, compiles raw sources, and uses Claude 3.5 or GPT-4o to synthesize a premium, structured markdown research report.
All research and discovery findings are saved as an Architectural Blueprint (.swux/blueprint.yaml). The blueprint explicitly defines your tech stack, database schemas, modules, and API designs.
When you spawn coding agents with --goal <goalId>, Swux mounts isolated git worktrees and injects the blueprint contract directly into the agents' prompts. The coding agents (Claude Code, Aider) implement modules in parallel, adhering exactly to your architectural constraints.
No config. No project setup. Just see it work:
macOS / Linux — paste in your terminal:
curl -fsSL https://raw.githubusercontent.com/shamwuo/swux/main/install.sh | bash && swux demoWindows — paste in PowerShell:
iex (iwr https://raw.githubusercontent.com/shamwuo/swux/main/install.ps1).Content; swux demoswux demo spins up a headless agent session, runs a mock task, and prints the live JSON state — no tmux, no config file, no API keys required.
| Method | Command |
|---|---|
| curl one-liner (macOS / Linux) | curl -fsSL https://raw.githubusercontent.com/shamwuo/swux/main/install.sh | bash |
| PowerShell one-liner (Windows) | iex (iwr https://raw.githubusercontent.com/shamwuo/swux/main/install.ps1).Content |
| Direct binary | Download from Releases → |
| Homebrew (macOS / Linux) | brew tap shamwuo/tap && brew install swux |
| npm (coming soon) | npm install -g @swux/swux |
| Build from source | git clone … && bash scripts/setup.sh |
Prerequisites for
swux start: Node.js 20+, Git 2.25+,ghCLI, and:
- macOS / Linux: tmux — install via
brew install tmuxorsudo apt install tmux. Not required if you just wantswux demo.- Windows: PowerShell 7+ recommended. tmux is not required — swux uses native ConPTY via the
runtime-processplugin. SetSWUX_SHELL=bashif you have Git Bash and prefer it.
Point swux at any local repository:
cd ~/my-project && swux startThe Next.js dashboard will automatically boot at http://localhost:3000.
- Run the interactive discovery to create a Blueprint:
swux build "Build a real-time multiplayer chess game" - Gather technical documentation via scraping:
swux research "Chess WebSockets protocol RFC" --type literature-survey
Spawn parallel worker agents using the generated goal ID:
swux spawn --goal chess-game-1 --prompt "Implement the WebSocket server module"
swux spawn --goal chess-game-1 --prompt "Build the frontend board UI"Each agent executes independently in its own worktree and registers under the unified dashboard.
SWUX supports seven plugin slots, keeping state management and the lifecycle loop in core.
| Slot | Default | Alternatives |
|---|---|---|
| Runtime | tmux (macOS/Linux) / process (Windows) | process, docker |
| Agent | claude-code | codex, aider, cursor, opencode, kimicode |
| Workspace | worktree | clone |
| Tracker | github | linear, gitlab |
| SCM | github | gitlab |
| Notifier | desktop | slack, discord, composio, webhook, openclaw |
| Terminal | iterm2 | web |
All interfaces are defined in packages/core/src/types.ts.
| Doc | What it covers |
|---|---|
| Setup Guide | Detailed installation, configuration, and troubleshooting |
| CLI Reference | All swux commands (mostly used by the Swux session) |
| Examples | Config templates (GitHub, Linear, multi-project, auto-merge) |
| Development Guide | Architecture, conventions, plugin pattern |
| Contributing | How to contribute, build plugins, PR process |
pnpm install && pnpm build # Install and build all packages
pnpm test # Run vitest unit tests
pnpm dev # Start web dashboard dev serverMIT