Inspired by the SCUD short-range ballistic missile system—lightweight, flexible, and powerful. Like its namesake, SCUD can be deployed quickly in a variety of contexts, delivering results with minimal overhead.
A fast, AI-powered task management system with both CLI and desktop GUI interfaces. Parse PRDs into tasks, track dependencies, visualize parallel execution waves, and orchestrate AI agents.
SCUD focuses on core task management while providing experimental advanced features for team orchestration and complex workflows.
Fast, lightweight command-line interface for task management and AI orchestration.
Desktop application for visual task management and real-time AI agent control.
For developers who prefer terminal workflows and scripting.
For visual task management and real-time agent control.
# From crates.io (recommended)
cargo install scud-cli
scud init
# From source
git clone https://github.com/pyrex41/scud.git
cd scud/scud-cli
cargo build --release
./target/release/scud init# From crates.io (recommended)
cargo install descartes-gui
# From source
git clone https://github.com/pyrex41/scud.git
cd scud/descartes-gui
cargo build --release
./target/release/descartes-gui# Initialize SCUD project
scud init
# Generate tasks from PRD (full pipeline: parse → expand → validate)
scud generate docs/feature.md --tag my-feature
# Or just parse PRD into initial tasks
scud parse docs/feature.md --tag my-feature
# View tasks and dependencies
scud list --tag my-feature
scud waves --tag my-feature # Show parallel execution plan
# Find and work on next ready task
scud next --tag my-feature
scud set-status 1 in-progress
# When done, mark complete
scud set-status 1 done
# Visualize in browser
scud view# Initialize SCUD first (GUI reads from SCUD data)
scud init
scud generate docs/feature.md --tag my-feature
# Launch GUI
descartes-gui
# In GUI: View waves, start tasks, monitor progressSCUD CLI Quick Reference: docs/reference/QUICK_REFERENCE.md Orchestrator Pattern: docs/orchestrator.md Descartes GUI Details: descartes-gui/README.md
Tasks are stored in SCG (SCUD Graph) format—a token-efficient, human-readable text format that achieves ~75% token reduction compared to JSON. SCG explicitly represents the task dependency graph with sections for nodes, edges, and metadata. Inspired in part by Nikolai Mushegian's JAMS spec (GitHub).
@nodes
auth:1 | Design auth system | X | 13 | H
auth:1.1 | Implement JWT | D | 5 | H
@edges
auth:1.1 -> auth:1
Full spec: docs/reference/SCG_FORMAT_SPEC.md
Tasks become ready when their dependencies complete. No manual phase management required.
Task 1 ──┐
├──> Task 3 ──> Task 5
Task 2 ──┘ │
└──> Task 4
Group related tasks together (e.g., auth-system, payment-flow). Each tag has its own task graph.
SCUD supports two execution strategies for parallel agent orchestration:
Execution Modes:
Wave Mode (default): Batches ready tasks into waves, spawns agents in parallel, waits for completion, validates with backpressure, then proceeds to next wave.
scud swarm --tag my-feature # Default wave mode with tmux
scud swarm --tag my-feature --headless # Wave mode without tmux sessionsBeads Mode: Continuous polling - spawns agents immediately when tasks become ready, without waiting for batch boundaries.
scud swarm --tag my-feature --swarm-mode beadsTerminal Management:
- tmux mode (default): Spawns interactive tmux sessions for each agent with live monitoring
- headless mode: Runs agents in background processes without terminal sessions
- Monitor sessions: Use
scud monitor --session <name>to watch running swarms
All modes include SQLite event logging, backpressure validation, and salvo worktree isolation. See docs/orchestrator.md for details.
The desktop GUI provides a visual interface for task management and AI agent orchestration, complementing the SCUD CLI.
- Interactive waves: Click to start tasks in parallel execution waves
- Dependency awareness: Visual representation of task relationships
- Status tracking: Real-time progress indicators
- One-click execution: Start agents directly from the GUI
- Real-time control: Pause, resume, or cancel running agents
- Live monitoring: Stream agent output and progress
- Visual task board: Drag-and-drop task organization
- Status updates: Mark tasks complete directly in the interface
- Progress tracking: Overall project completion statistics
# Install GUI
cargo install descartes-gui
# Initialize SCUD project first
scud init
scud generate docs/feature.md --tag my-project
# Launch GUI
descartes-guiThe GUI reads from SCUD's .scud/ storage directory and provides a user-friendly interface for the same underlying task management system.
- 50x faster than JavaScript alternatives
- 42x fewer tokens (500 vs 21k)
- Single binary - zero runtime dependencies
- Self-contained - embedded assets, no external files
- Dependency graphs - tasks ready when deps complete
- Parallel waves - visualize concurrent work with
scud waves - Smart scheduling -
scud nextfinds ready tasks
- Visual task board -
scud viewopens browser dashboard - Mermaid diagrams - dependency graph visualization
- Real-time stats - progress tracking
- Wave visualization - Interactive task waves with one-click execution
- Real-time agent control - Pause, resume, cancel running agents
- Live output streaming - Monitor agent progress in real-time
- Visual task management - Drag-and-drop task organization
- DOT and SCG formats - define pipelines as DOT graphs or native SCG files
- Node types - LLM calls, shell tools, human gates, conditionals, parallel fan-out/fan-in
- Format conversion -
import/exportbetween DOT and SCG - Checkpoint/resume - interrupt and resume pipelines from any node
- Retry with backoff - exponential backoff with jitter on failures
- Stylesheets - CSS-like model/provider defaults per node class
- Condition routing - edge expressions for dynamic graph traversal
- See Attractor Mode docs
- Parallel agents - spawn multiple AI agents via tmux or headless execution
- Salvo worktrees - automatic git worktree isolation per tag
- SQLite event storage - queryable event logs, transcript search, session history
- Transcript capture - real-time import of Claude Code conversation logs
- Live monitoring - heartbeat tracking, orphan detection, stale timeouts
- Task locking -
scud claim/releaseprevents conflicts - Session monitoring -
scud whoistracks active work
Getting Started:
- Quick Reference - SCUD CLI command cheat sheet
- SCG Format Spec - Task file format
- Descartes GUI - Desktop interface guide
Swarm & Orchestration:
- Orchestrator Pattern - Swarm modes and multi-agent workflows
- Parallel Features - Task orchestration (includes experimental features)
Attractor Mode:
- Attractor Mode - DOT-based AI workflow pipelines
Development:
- Development Logs - Implementation details & history
scud init # Initialize SCUD in current directory
scud warmup # Quick session orientation (recent commits, active tasks)
scud tags # List/set active phase tagsscud list [--tag <tag>] # List tasks
scud show <id> # Show task details
scud next [--tag <tag>] # Find next ready task
scud set-status <id> <status> # Update task status
scud stats [--tag <tag>] # Show statistics
scud waves [--tag <tag>] # Show parallel execution wavesscud view # Open task viewer in browser
scud mermaid [--tag <tag>] # Generate Mermaid diagramscud generate <file> --tag <tag> # Full pipeline: parse → expand → validate
scud parse <file> --tag <tag> # Parse PRD/doc into initial tasks
scud expand [--task <id>] # Break down complex tasks into subtasks
scud analyze-complexity # Analyze task complexity (AI-powered)
scud check-deps --tag <tag> # Validate task dependencies
scud reanalyze-deps # Suggest cross-tag dependenciesDefault provider: xai, model: xai/grok-code-fast-1. Configure with scud config.
Project guidance files in .scud/guidance/*.md are automatically included in AI prompts.
scud swarm --tag <tag> # Run wave-based parallel execution
scud swarm --swarm-mode tmux # Tmux-based spawning (default - interactive)
scud swarm --swarm-mode headless # Headless mode (no terminals/sessions)
scud swarm --swarm-mode beads # Continuous polling mode (fluid execution)
scud swarm --headless # Shorthand for --swarm-mode headless
scud swarm --round-size 5 # Max tasks per round (default: 5)
scud swarm --harness opencode # AI harness: claude, opencode (default: claude)
scud swarm --dry-run # Show execution plan without spawning
scud swarm --review # Enable code review after each wave
scud swarm --no-validate # Skip backpressure validation
# Swarm monitoring and retrospectives
scud retro [session-id] # View session retrospective/timeline
scud watch --session <session> # Watch running swarm via live eventsExecution Modes:
- tmux (default): Spawns agents in tmux sessions with live monitoring
- headless: Runs agents in background without terminal sessions
- beads: Continuous polling - starts new agents as tasks become ready
These features are under active development and may change significantly.
scud salvo list # List isolated worktrees
scud salvo sync <tag> # Sync worktree back to main
scud salvo remove <tag> # Remove worktree and branchscud transcript search <query> # Search conversation logs
scud transcript stats # Show transcript statistics
scud transcript list # List available transcripts
scud transcript view [--session] # View conversation transcript
scud transcript import # Import project transcriptsscud assign <id> <name> # Assign task to team member
scud who-is [--tag <tag>] # See who's working on what
scud next-batch [--limit 5] # Get multiple tasks at once
scud doctor workflow [--tag <tag>] # Diagnose stuck task states
scud doctor scan-ext # Scan and validate extensionsscud attractor run <file> # Execute a pipeline (.dot or .scg)
scud attractor run <file> --headless # Auto-approve human gates
scud attractor run <file> --simulated # Dry-run with no LLM calls
scud attractor run <file> --model opus # Override model
scud attractor run <file> --provider xai # Override provider/harness
scud attractor run <file> --resume <ckpt> # Resume from checkpoint
scud attractor validate <file> # Validate without executing
scud attractor export <file> --format dot # Convert SCG → DOT (or DOT → SCG)
scud attractor import <file.dot> -o out.scg # Import DOT as SCGPipelines can be DOT digraph files (node shapes determine behavior) or SCG files with mode pipeline (handler types in @pipeline section). Both formats support the same execution semantics. See docs/attractor.md for the full reference.
scud log <id> "message" # Add log entry to task
scud log-show <id> # Show task log entries
scud commit [-m "msg"] # Git commit with task contextscud clean [--tag <tag>] # Archive tasks (default, recoverable)
scud clean --list # List archived phases
scud clean --restore <name> # Restore an archived phase
scud clean --keep tag1,tag2 # Archive all except specified tags
scud clean --delete # Permanently delete (use with caution)Note:
scud cleannow archives by default instead of deleting. Use--deletefor permanent removal.
# 1. Initialize
scud init
# 2. Generate tasks from PRD (parse → expand → validate in one command)
scud generate docs/feature.md --tag auth-system
# 3. View execution plan
scud waves --tag auth-system
# Shows which tasks can run in parallel
# 4. Work on next ready task
scud next --tag auth-system
# Returns: Task 1 is ready
scud set-status 1 in-progress
# ... do the work ...
scud set-status 1 done
# 5. Track progress
scud stats --tag auth-system
# Shows progress: 8/10 complete
# 6. Visualize
scud view
# Opens task viewer in browserSee docs/orchestrator.md for parallel execution patterns.
# Use CLI for project setup and task generation
scud init
scud generate docs/feature.md --tag my-project
scud waves --tag my-project
# Use GUI for visual task management and execution
descartes-gui
# In GUI: View task waves, start agents, monitor progress
# Use CLI for detailed development work
scud next --tag my-project
scud set-status 1 in-progress
# ... implement the feature ...
scud set-status 1 done
scud commit -m "Add JWT authentication system"DAG-Driven:
- Tasks become ready when dependencies complete
- Visualize parallel execution waves
- Smart scheduling finds ready work
Fast & Simple:
- Rust CLI is instant (<50ms)
- SCG format is human-readable and git-friendly
- Works offline (core commands)
- No vendor lock-in
Visual:
- Web dashboard with task board
- Mermaid dependency diagrams
- Real-time progress tracking
Orchestrator-Ready:
- Parallel agent spawning via tmux or headless modes
- SQLite event storage and session history
- Swarm execution with wave-based or continuous modes
- Live monitoring with retrospective analysis
- Experimental: Advanced worktree isolation and transcript management
- Rust toolchain (for building from source)
- xAI API key (for AI features only; core commands work offline)
- Rust toolchain (for building from source)
- System libraries (Linux:
libxkbcommon-dev libwayland-dev)
# For SCUD CLI AI features
export XAI_API_KEY=xai-...
# For Descartes GUI (Claude models)
export ANTHROPIC_API_KEY=sk-ant-...Alternative providers: Anthropic (ANTHROPIC_API_KEY), OpenAI (OPENAI_API_KEY), OpenRouter (OPENROUTER_API_KEY). Configure with scud config.
.scud/
├── scud.db # SQLite database (events, transcripts, sessions)
├── tasks/tasks.scg # All tasks in SCG format
├── config.toml # Provider/model settings
├── active-tag # Currently active tag
├── current-task # Active task ID (for commits)
├── guidance/ # Project guidance for AI prompts
│ └── *.md # Markdown files auto-loaded
├── archive/ # Archived phases (from scud clean)
│ └── <tag>_<timestamp>.scg # Timestamped archive files
├── swarm/ # Swarm execution data
│ ├── sessions/ # Session state and history
│ └── *.lock # Session lock files
├── agents/ # Extension manifests (experimental)
│ └── *.toml # Custom agent definitions
└── logs/ # Task log entries
You can provide project-specific context that will be automatically included in AI prompts. Create markdown files in .scud/guidance/:
# Example: Add coding standards
echo "# Coding Standards
- Use TypeScript strict mode
- All functions must have JSDoc comments
- Maximum function length: 50 lines" > .scud/guidance/coding-standards.md
# Example: Add architecture notes
echo "# Architecture
- Frontend: React with hooks
- Backend: Express.js
- Database: PostgreSQL" > .scud/guidance/architecture.mdAll .md files in this folder are automatically loaded when running scud parse or scud expand. Use --no-guidance to skip loading guidance.
# Clone repository
git clone https://github.com/pyrex41/scud.git
cd scud
# Build SCUD CLI
cd scud-cli
cargo build --release
./target/release/scud install # Optional: install globally
# Build Descartes GUI
cd ../descartes-gui
cargo build --release
# Test both
./target/release/scud init
./target/release/descartes-guimacOS: No additional dependencies required.
Linux:
# For Descartes GUI
sudo apt install libxkbcommon-dev libwayland-devPublishing: See PUBLISHING.md for CI/CD setup and release process.
Issues and PRs welcome at github.com/pyrex41/scud
MIT
- SCUD CLI Quick Reference: docs/reference/QUICK_REFERENCE.md
- SCG Format: docs/reference/SCG_FORMAT_SPEC.md
- Attractor Mode: docs/attractor.md
- Orchestrator Pattern: docs/orchestrator.md
- Parallel Features: docs/features/PARALLEL_FEATURES.md
- Descartes GUI: descartes-gui/README.md
- Changelog: CHANGELOG.md
- Related: github.com/pyrex41/descartes
Happy building!