Conflux

Automates the OpenSpec change workflow (list → dependency analysis → apply → archive). Orchestrates openspec and AI coding agents to process changes autonomously.

Features

• 🖥️ Interactive TUI: Default mode with real-time progress dashboard
• 🤖 Automated Workflow: Automatically processes OpenSpec changes from detection to archival
• 🧠 LLM Dependency Analysis: Uses AI agents to intelligently analyze and order changes
• 📊 Real-time Progress: Visual progress bars showing overall and per-change status
• 🔌 Multi-Agent Support: Works with Claude Code, OpenCode, and Codex
• 🪝 Lifecycle Hooks: Configurable hooks for custom actions at each workflow stage
• ⚡ Parallel Execution: Process multiple independent changes simultaneously using Git worktrees
• 🌐 Web Monitoring: Optional HTTP server with REST API and WebSocket for remote monitoring

Architecture

┌─────────────────────────────────────────────┐
│     cflx (Rust CLI)        │
├─────────────────────────────────────────────┤
│  CLI → Orchestrator → State Manager         │
│    ↓        ↓              ↓                │
│  OpenSpec  AI Agent    Progress Display     │
│            (Claude/OpenCode/Codex)          │
└─────────────────────────────────────────────┘

Quick Start

# 1. Install
cargo install --path .

# 2. Initialize configuration (Claude Code agent by default)
cflx init

# 3. Launch the interactive TUI (default entry point)
cflx

# Or run headless (non-interactive)
cflx run

For other templates:

cflx init --template opencode
cflx init --template codex

Usage

Golden Path: Quick Start

# Step 1: Generate configuration for your AI agent (Claude Code by default)
cflx init

# Step 2: Edit the generated .cflx.jsonc to configure your agent
vim .cflx.jsonc

# Step 3a: Launch the interactive TUI to review and process changes
cflx

# Step 3b: Or run in headless (non-interactive) mode
cflx run

Interactive TUI (Primary Interface)

The primary way to use the orchestrator is through the interactive TUI dashboard:

cflx

The TUI provides:

• Real-time change status visualization
• Progress tracking for all pending changes
• Keyboard navigation and controls
• Worktree management view

TUI Change States

Changes have a selection/queue state.

Checkbox Display:

Queue Status (shown in Running mode):

Workflow:

1. Select mode (header shows [Ready]): Use Space to toggle the execution mark (selected)
2. Press F5 to start processing - all execution-marked changes become queued
3. Running mode (header shows [Running N]): queued → applying → (optional accepting) → archiving → archived (parallel mode may also show merge wait/resolving/merged)

Header Status

TUI Key Bindings

Changes View:

Worktrees View:

*QR code is only available when web monitoring is enabled (--web flag). Press any key to close the QR popup.

TUI Worktree View

The TUI includes a dedicated Worktree View for managing git worktrees directly from the interface.

Key Features:

• View Switching: Press Tab to switch between Changes and Worktrees views
• Worktree List: Displays all worktrees with path (basename), branch name, and status
• Conflict Detection: Automatically checks for merge conflicts in parallel (background)
• Branch Merge: Merge worktree branches to base with M key (conflict-free only)
• Worktree Management: Create (+), delete (D), open editor (e), open shell (Enter)

Workflow:

1. Switch to Worktrees View: Press Tab from Changes view

   • Loads worktree list with conflict detection (runs in parallel)
   • Display format: <worktree-path> → <branch-name> [STATUS] [⚠conflicts]

2. Navigate Worktrees: Use ↑/↓ or j/k keys

   • Main worktree shown with [MAIN] indicator (green)
   • Detached HEAD shown with [DETACHED] indicator
   • Conflicts shown with ⚠<count> badge (red)

3. Merge Branch: Press M (only enabled when safe)

   • Validates: not main worktree, not detached HEAD, no conflicts
   • Executes: git merge --no-ff --no-edit <branch> in base repository
   • On success: Shows success log, refreshes worktree list
   • On failure: Shows error popup with details

4. Create Worktree: Press +

   • Generates unique branch name: ws-session-<timestamp>
   • Creates worktree with new branch (not detached HEAD)
   • Requires worktree_command config option

5. Delete Worktree: Press D (only for non-main, non-processing worktrees)

   • Shows confirmation dialog (Y to confirm, N/Esc to cancel)
   • Removes worktree directory and updates list

6. Open Editor/Shell: Press e or Enter

   • e: Opens editor in worktree directory (respects $EDITOR)
   • Enter: Runs worktree_command in worktree (e.g., opens shell)

Conflict Detection:

• Runs automatically when switching to Worktrees view
• Checks each non-main, non-detached worktree in parallel using git merge --no-commit --no-ff
• Detects conflicts without modifying working tree (uses git merge --abort)
• Displays conflict count as ⚠<count> badge in red
• Updates every 5 seconds (auto-refresh) in background
• Disables M key when conflicts detected

Performance:

• Parallel conflict checking: Uses async concurrent execution
• Typical performance: 4 worktrees checked in < 1 second
• Non-blocking: Conflict checks run asynchronously, TUI remains responsive
• Fallback: On check failure, assumes no conflict info (safe default)

Initialize Configuration

Generate a configuration file for your preferred AI agent:

# Default: Claude Code template
cflx init

# OpenCode template
cflx init --template opencode

# Codex template
cflx init --template codex

# Overwrite existing config
cflx init --force

Available templates: claude (default), opencode, codex

Run Orchestration (Non-Interactive)

Process all pending changes in headless mode:

cflx run

Process specific changes (single or multiple):

# Single change
cflx run --change add-feature-x

# Multiple changes (comma-separated)
cflx run --change add-feature-x,fix-bug-y,refactor-z

Custom configuration file:

cflx run --config /path/to/config.jsonc

How It Works

Main Loop

1. List changes via openspec list
   ↓
2. Select next change
   • Priority 1: 100% complete (ready for archive)
   • Priority 2: LLM dependency analysis
   • Priority 3: Highest progress (fallback)
   ↓
3. Process change
   • If complete: openspec archive
   • If incomplete: AI agent applies next task
   ↓
4. Update state and repeat

Dependency Analysis

The orchestrator uses an AI agent to analyze dependencies:

// Prompt sent to LLM
"Select the next change to execute from the following OpenSpec changes.

Changes:
- add-feature-x (2/5 tasks, 40.0%)
- fix-bug-y (5/5 tasks, 100.0%)
- refactor-z (0/3 tasks, 0.0%)

Selection criteria:
1. No dependencies, or dependencies are completed
2. Higher progress (continuity)
3. Consider dependencies inferred from names

Output only the change ID on a single line."

Configuration

Agent Configuration File (JSONC)

The orchestrator supports configurable agent commands via JSONC configuration files. This allows you to use different AI tools (Claude Code, OpenCode, Codex, etc.) without code changes.

Configuration file locations (in order of priority):

1. .cflx.jsonc (project root)
2. ~/.config/cflx/config.jsonc (global)
3. Custom path via --config option

Example configuration (Claude Code):

{
  // Command to analyze dependencies and select next change
  "analyze_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p '{prompt}'",

  // Command to apply a change (supports {change_id} and {prompt} placeholders)
  "apply_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p '/openspec:apply {change_id} {prompt}'",

  // Command to run acceptance tests after apply (supports {change_id} and {prompt} placeholders)
  "acceptance_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p '/openspec:accept {change_id} {prompt}'",

  // Command to archive a completed change (supports {change_id} and {prompt} placeholders)
  "archive_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p '/openspec:archive {change_id} {prompt}'",

  // Command to resolve merge conflicts (supports {prompt} placeholder)
  "resolve_command": "claude --dangerously-skip-permissions --verbose --output-format stream-json -p '{prompt}'",

  // System prompt for apply command (injected into {prompt} placeholder)
  "apply_prompt": "スコープ外タスクは削除せよ。ユーザを待つもしくはユーザによるタスクは削除せよ。",

  // System prompt for acceptance command (injected into {prompt} placeholder)
  "acceptance_prompt": "",

  // Controls how the acceptance {prompt} is constructed
  // - "full": include hardcoded acceptance system prompt + diff/history context (default)
  // - "context_only": only include change metadata + diff/history context
  // Use "context_only" when your acceptance_command uses a command template with fixed instructions
  "acceptance_prompt_mode": "full",

  // Maximum number of acceptance CONTINUE retries before treating as FAIL (default: 10)
  "acceptance_max_continues": 10,

  // System prompt for archive command (injected into {prompt} placeholder)
  "archive_prompt": "",

  // Command to create a proposal worktree from TUI (+ key)
  // Supports {workspace_dir} and {repo_root} placeholders
  "worktree_command": "claude --dangerously-skip-permissions --verbose -p '/openspec:proposal --worktree {workspace_dir}'",

  // Lifecycle hooks (optional)
  "hooks": {
    // "pre_apply": "echo 'Starting {change_id}'",
    // "post_apply": "echo 'Completed {change_id}'"
  }
}

Logging configuration:

{
  "logging": {
    "suppress_repetitive_debug": true,
    "summary_interval_secs": 60
  }
}

• suppress_repetitive_debug: suppress repeated debug logs when state is unchanged (default: true)
• summary_interval_secs: emit summary logs every N seconds, set to 0 to disable (default: 60)

Placeholders:

System Prompts:

Quick start:

# Generate configuration with init command
cflx init

# Or copy the example configuration
cp .cflx.jsonc.example .cflx.jsonc

# Edit to customize settings
vim .cflx.jsonc

# Run with the configuration
cflx

Hooks Configuration

You can configure hooks to run commands at various stages of the orchestration process. Hooks are defined in the hooks section of the configuration file.

{
  "hooks": {
    // Simple string format (uses default settings)
    "on_start": "echo 'Orchestrator started'",

    // Object format (with detailed settings)
    "post_apply": {
      "command": "cargo test",
      "continue_on_failure": false,  // Stop orchestration if command fails
      "timeout": 300                 // Timeout in seconds
    },

    // Run lifecycle hooks
    "on_start": "echo 'Starting orchestration with {total_changes} changes'",
    "on_finish": "echo 'Finished with status: {status}'",
    "on_error": "echo 'Error in {change_id}: {error}' >> errors.log",

    // Change lifecycle hooks
    "on_change_start": "echo 'Starting {change_id}'",
    "pre_apply": "echo 'Applying {change_id} (attempt {apply_count})'",
    "post_apply": "cargo test",
    "on_change_complete": "echo '{change_id} is 100% complete'",
    "pre_archive": "cargo clippy -- -D warnings",
    "post_archive": "echo '{change_id} archived successfully'",
    "on_change_end": "echo 'Finished processing {change_id}'",

    // TUI-only hooks (user interaction)
    "on_queue_add": "echo 'Added {change_id} to queue'",
    "on_queue_remove": "echo 'Removed {change_id} from queue'"
  }
}

Available Hooks:

Run lifecycle hooks:

Change lifecycle hooks:

TUI-only hooks (user interaction):

Placeholders:

Environment Variables:

Hooks receive context via environment variables: OPENSPEC_CHANGE_ID, OPENSPEC_CHANGES_PROCESSED, OPENSPEC_TOTAL_CHANGES, OPENSPEC_REMAINING_CHANGES, OPENSPEC_APPLY_COUNT, OPENSPEC_COMPLETED_TASKS, OPENSPEC_TOTAL_TASKS, OPENSPEC_STATUS, OPENSPEC_ERROR, OPENSPEC_DRY_RUN

Environment Variables

Example:

# Use a custom openspec installation
export OPENSPEC_CMD="/usr/local/bin/openspec"
cflx

# Use a specific version via npx
export OPENSPEC_CMD="npx @fission-ai/openspec@1.2.3"
cflx

Command-line Options

Usage: cflx [OPTIONS] [COMMAND]

Commands:
  run              Run the OpenSpec change orchestration loop (non-interactive)
  tui              Launch the interactive TUI dashboard
  init             Initialize a new configuration file
  check-conflicts  Check for conflicts between spec delta files across changes
  server           Start the multi-project server daemon

Options:
  -c, --config <PATH>          Path to custom configuration file (JSONC format)
  --web                        Enable web monitoring server for remote status viewing
  --web-port <PORT>            Port for web monitoring server (default: 0 = auto-assign by OS)
  --web-bind <ADDR>            Bind address for web monitoring server (default: 127.0.0.1)
  --server <URL>               Connect TUI to a remote Conflux server (e.g., http://host:9876)
  --server-token <TOKEN>       Bearer token for remote server authentication
  --server-token-env <VAR>     Environment variable holding the bearer token
  -h, --help                   Print help
  -V, --version                Print version

Run subcommand options:

Options:
  --change <ID,...>         Process only specified changes (comma-separated)
  -c, --config <PATH>       Custom configuration file path (JSONC)
  --parallel                Enable parallel execution mode
  --max-concurrent <N>      Maximum concurrent workspaces (default: 3)
  --vcs <BACKEND>           VCS backend: auto or git (default: auto)
  --no-resume               Disable workspace resume (always create new workspaces)
  --dry-run                 Preview parallelization groups without executing
  --max-iterations <N>      Maximum number of orchestration loop iterations (0 = no limit)
  --web                     Enable web monitoring server
  --web-port <PORT>         Web server port (default: 0 = auto-assign by OS)
  --web-bind <ADDR>         Web server bind address (default: 127.0.0.1)

TUI options:

The TUI (default mode, cflx or cflx tui) also supports web monitoring options:

# TUI with web monitoring
cflx --web

# Custom port and bind address
cflx --web --web-port 9000 --web-bind 0.0.0.0

Parallel Execution

The orchestrator supports parallel execution of independent changes using Git worktrees.

VCS Backend Selection:

Usage:

# Auto-detect VCS backend (default)
cflx run --parallel

# Force Git worktrees
cflx run --parallel --vcs git

# Preview parallelization groups without executing
cflx run --parallel --dry-run

# Limit concurrent workspaces
cflx run --parallel --max-concurrent 5

Configuration:

You can also set the VCS backend in your configuration file:

{
  // VCS backend for parallel execution: "auto" or "git"
  "vcs_backend": "auto",

  // Maximum concurrent workspaces
  "max_concurrent_workspaces": 3
}

Git Requirements:

When using Git worktrees:

• Working directory must be clean (no uncommitted changes)
• Each change runs in an isolated worktree with its own branch
• Changes are merged back sequentially after completion

Workspace Resume:

By default, the orchestrator automatically detects and reuses existing workspaces from interrupted runs. This allows you to resume work from where you left off without losing progress.

• When a workspace is found for a change ID, it is reused instead of creating a new one
• If multiple workspaces exist for the same change, the newest one is used and older ones are cleaned up
• Use --no-resume to disable this behavior and always create fresh workspaces

# Resume from existing workspaces (default behavior)
cflx run --parallel

# Always create new workspaces (discard any existing work)
cflx run --parallel --no-resume

Workspace State Detection (Idempotent Resume):

The orchestrator detects the current state of each workspace to ensure idempotent execution. When resuming, workspaces are classified into one of five states:

This state detection ensures that:

• Running the orchestrator multiple times on the same workspace is safe and produces the same result (idempotency)
• Manually archived or merged changes are detected and handled correctly
• Interrupted operations resume from the correct step
• No duplicate work is performed

State Detection Examples:

# Interrupted during apply - resumes from where it left off
$ cflx run --parallel
# Workspace state: Applying (iteration 3/5)
# Action: Resume apply from iteration 4

# Manually archived a change - skips apply/archive
$ cflx run --parallel
# Workspace state: Archived
# Action: Skip apply/archive, merge to main only

# Already merged to main - cleanup only
$ cflx run --parallel
# Workspace state: Merged
# Action: Skip all operations, cleanup workspace

Command Execution Queue

The orchestrator includes a command execution queue that prevents resource conflicts and handles transient errors when running multiple AI agent commands in parallel.

Features:

1. Staggered Start: Commands are started with a configurable delay to prevent simultaneous resource access
2. Automatic Retry: Commands that fail due to transient errors (module resolution, network issues, etc.) are automatically retried

Configuration:

{
  // Delay between command executions (milliseconds)
  // Default: 2000 (2 seconds)
  "command_queue_stagger_delay_ms": 2000,

  // Maximum number of retries for failed commands
  // Default: 2
  "command_queue_max_retries": 2,

  // Delay between retries (milliseconds)
  // Default: 5000 (5 seconds)
  "command_queue_retry_delay_ms": 5000,

  // Retry if execution duration is under this threshold (seconds)
  // Short-running failures often indicate environment/startup issues
  // Default: 5
  "command_queue_retry_if_duration_under_secs": 5,

  // Error patterns that trigger automatic retry (regex)
  // Default: module resolution, registry, and lock errors
  "command_queue_retry_patterns": [
    "Cannot find module",
    "ResolveMessage:",
    "ENOTFOUND registry\\.npmjs\\.org",
    "ETIMEDOUT.*registry",
    "EBADF.*lock",
    "Lock acquisition failed"
  ]
}

How It Works:

• Staggered Start: Each command waits for a minimum delay since the last command started, preventing simultaneous access to shared resources (e.g., ~/.cache/opencode/node_modules)
• Retry Logic: Commands are retried if they:
  • Match a configured error pattern (e.g., "Cannot find module"), OR
  • Exit quickly (< 5 seconds by default), indicating a startup/environment issue
• No Retry: Commands that run for a long time (> 5 seconds) and don't match error patterns are not retried, as they likely failed due to logical errors

Example - Preventing Module Resolution Conflicts:

# Without queue: Multiple commands start simultaneously
# → Conflict: All try to update node_modules at once
# → Result: "Cannot find module" errors

# With queue (default): Commands start 2 seconds apart
# → First command updates node_modules
# → Subsequent commands use stable environment
# → Result: No conflicts

Example - Handling Transient Network Errors:

# Error: ETIMEDOUT registry.npmjs.org
# → Matches retry pattern
# → Automatically retried after 5 seconds
# → Usually succeeds on retry

Web Monitoring

The orchestrator supports an optional HTTP server for remote monitoring of orchestration progress via web browser.

Usage:

# Enable web monitoring with TUI (OS auto-assigns an available port)
cflx --web

# Custom port and bind address
cflx --web --web-port 9000 --web-bind 0.0.0.0

# With headless run mode
cflx run --web

When using the default port (0), the OS automatically assigns an available port. The actual bound address is logged when the server starts.

Features:

• Dashboard UI: View progress at http://localhost:8080/
• Real-time updates: WebSocket connection for live progress updates
• REST API: Query state programmatically
• QR Code Popup: Press w in the TUI to display a QR code for quick mobile access to the dashboard

REST API Endpoints:

For complete API specifications, see the OpenAPI documentation.

WebSocket:

Connect to ws://localhost:8080/ws for real-time state updates. Messages are JSON with the following format:

{
  "type": "state_update",
  "timestamp": "2024-01-12T10:30:00Z",
  "changes": [
    {
      "id": "add-feature",
      "completed_tasks": 3,
      "total_tasks": 10,
      "progress_percent": 30.0,
      "status": "in_progress"
    }
  ]
}

Dashboard Overview:

The web dashboard provides a visual overview of orchestration progress:

┌─────────────────────────────────────────────────────────────────┐
│  OpenSpec Orchestrator                           ● Connected    │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
│  │    5    │  │    2    │  │    1    │  │    2    │            │
│  │  Total  │  │Complete │  │Progress │  │ Pending │            │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ add-feature-auth                    [IN_PROGRESS]           │
│  │ ████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  40%    │   │
│  │ 4/10 tasks                                               │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ fix-login-bug                       [COMPLETE]              │
│  │ ████████████████████████████████████████████████  100%  │   │
│  │ 5/5 tasks                                                │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ refactor-api                        [PENDING]               │
│  │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  0%    │   │
│  │ 0/8 tasks                                                │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  Last updated: 2024-01-12 10:30:00                              │
└─────────────────────────────────────────────────────────────────┘

Dashboard Features:

• Stats Bar: Shows total, completed, in-progress, and pending change counts
• Change Cards: Each change displays ID, progress status, and progress bar
• Real-time Updates: Progress updates automatically via WebSocket connection
• Connection Status: Shows current WebSocket connection state (Connected/Disconnected)
• Responsive Design: Works on desktop and mobile browsers

Web Monitoring Troubleshooting:

Init subcommand options:

Options:
  -t, --template <TEMPLATE>  Template to use [default: claude] [possible values: claude, opencode, codex]
  -f, --force                Overwrite existing configuration file

Check-conflicts subcommand options:

Options:
  -j, --json  Output results in JSON format

Priority: CLI argument > Environment variable > Default value

Error Handling

Troubleshooting

"No changes found"

• Run openspec list to verify changes exist
• Check that you're in the correct directory

"Agent command failed"

• Verify your AI agent is installed (e.g., which claude)
• Test manually: claude -p "echo test"
• Check your configuration file: .cflx.jsonc

"All changes failed"

• Check logs for specific errors
• Try processing a single change: --change <id>

Installation

cargo install cflx

This will build and install the orchestrator to your Cargo bin directory (typically ~/.cargo/bin).

Documentation

Internal documentation (parallel execution audit) is available in docs/audit/.

Project Structure

src/
  lib.rs                    # Library crate root
  main.rs                   # Entry point, CLI dispatching
  cli.rs                    # CLI argument parsing (clap)
  error.rs                  # Error types (thiserror)
  openspec.rs               # OpenSpec CLI wrapper
  orchestrator.rs           # Main orchestration loop
  progress.rs               # Progress display (indicatif)
  hooks.rs                  # Lifecycle hook execution
  task_parser.rs            # Native tasks.md parser
  templates.rs              # Configuration templates
  acceptance.rs             # Acceptance test output parsing
  ai_command_runner.rs      # Common AI command runner (unified stagger state)
  analyzer.rs               # Change dependency analyzer
  command_queue.rs          # Command queue with stagger and retry
  events.rs                 # Unified event system
  history.rs                # Apply/archive/resolve history
  error_history.rs          # Error history tracking
  merge_stall_monitor.rs    # Merge stall detection monitor
  parallel_run_service.rs   # Parallel execution service
  permission.rs             # Permission auto-reject detection
  process_manager.rs        # Cross-platform child process management
  serial_run_service.rs     # Serial execution service
  spec_delta.rs             # Spec delta parsing and conflict detection
  spec_test_annotations.rs  # Spec test annotation support
  stall.rs                  # Stall detection utilities
  worktree_ops.rs           # Common worktree operations (TUI and Web)

  bin/
    openapi_gen.rs          # OpenAPI spec generator binary

  agent/                    # AI agent command execution
    mod.rs                  # Agent runner module
    runner.rs               # Agent runner implementation
    output.rs               # Output line types
    prompt.rs               # Prompt building functions
    history_ops.rs          # History management operations
    tests.rs                # Agent module tests

  execution/                # Shared execution logic
    mod.rs                  # Execution module root
    apply.rs                # Apply operation logic
    archive.rs              # Archive operation logic
    state.rs                # Workspace state detection
    types.rs                # Common type definitions

  orchestration/            # Shared orchestration logic
    mod.rs                  # Common CLI/TUI orchestration
    acceptance.rs           # Shared acceptance operations
    apply.rs                # Shared apply operations
    archive.rs              # Shared archive operations
    hooks.rs                # Hook context helpers
    output.rs               # Output handler trait
    selection.rs            # Shared change selection logic
    state.rs                # Shared state management

  config/                   # Configuration
    mod.rs                  # Configuration module root
    defaults.rs             # Default values
    expand.rs               # Environment variable expansion
    jsonc.rs                # JSONC parser

  vcs/                      # Version Control abstraction
    mod.rs                  # VCS module root
    commands.rs             # Common VCS interface
    git/                    # Git backend
      mod.rs                # Git module root
      commands/             # Git command implementations
        mod.rs              # Git commands module root
        basic.rs            # Basic git operations
        commit.rs           # Commit operations
        merge.rs            # Merge operations
        worktree.rs         # Worktree management

  parallel/                 # Parallel execution
    mod.rs                  # Parallel module root
    executor.rs             # Parallel change executor
    events.rs               # Progress reporting events
    conflict.rs             # Conflict detection/resolution
    cleanup.rs              # Workspace cleanup
    dynamic_queue.rs        # Dynamic queue for runtime change additions
    merge.rs                # Merge operations for parallel execution
    output_bridge.rs        # Bridge between OutputHandler and ParallelEvent
    types.rs                # Common types for parallel execution
    workspace.rs            # Workspace creation and management
    tests/                  # Parallel module tests
      mod.rs                # Test module root
      auto_resolve.rs       # Auto-resolve tests
      conflict.rs           # Conflict detection tests
      executor.rs           # Executor tests
      manual_resolve.rs     # Manual resolve tests

  remote/                   # Remote server client (TUI)
    mod.rs                  # HTTP and WebSocket client module
    client.rs               # HTTP client for remote server
    mapper.rs               # Remote type to local type mapping
    types.rs                # Remote communication type definitions
    ws.rs                   # WebSocket client for real-time updates

  server/                   # Server daemon (multi-project management)
    mod.rs                  # Server daemon module
    api.rs                  # REST API handlers
    registry.rs             # Project registry with persistence
    runner.rs               # Server-side project runner

  web/                      # Web monitoring
    mod.rs                  # Web monitoring module
    api.rs                  # REST API handlers
    state.rs                # Web monitoring state management
    url.rs                  # URL conversion utilities
    websocket.rs            # WebSocket handler for real-time updates

  tui/                      # Terminal User Interface
    mod.rs                  # TUI module
    render.rs               # Terminal rendering
    runner.rs               # TUI main loop
    state.rs                # TUI state management
    types.rs                # TUI type definitions
    type_impls.rs           # TUI type implementations
    events.rs               # TUI event handling
    command_handlers.rs     # TuiCommand handlers
    key_handlers.rs         # Key event handlers
    orchestrator.rs         # TUI orchestrator execution logic
    terminal.rs             # Terminal helper functions
    queue.rs                # Dynamic queue for runtime change additions
    worktrees.rs            # Worktree view management
    log_deduplicator.rs     # Log deduplication
    qr.rs                   # QR code generation for Web UI URL
    utils.rs                # TUI utility functions

tests/
  e2e_tests.rs                        # End-to-end tests
  merge_conflict_check_tests.rs       # Merge conflict detection tests
  opencode_command_validation.rs      # OpenCode command validation tests
  process_cleanup_test.rs             # Process cleanup tests

Development

See Development Guide for build instructions, testing, and full project structure.

Git Hooks

This project uses prek for managing Git hooks (a Rust-based alternative to pre-commit).

Migration from pre-commit:

If you were previously using pre-commit, uninstall it first:

pre-commit uninstall

Setup:

# Install prek
brew install prek

# Install hooks
prek install

Usage:

# Run all hooks on all files
prek run --all-files

# Run specific hooks
prek run rustfmt clippy

# List available hooks
prek list

The configuration is defined in .pre-commit-config.yaml (prek is fully compatible with pre-commit configuration format). The prek run --all-files command also auto-runs make openapi and stages docs/openapi.yaml.

Future Enhancements

• State persistence for recovery and resumption
• Parallel execution for independent changes (using Git worktrees)
• Slack/Discord notifications
• Maximum iteration limit (prevent infinite loops)
• Manual priority override
• Enhanced dry-run with execution plan
• Web UI for monitoring

License

MIT

Contributing

Contributions welcome! Please open an issue or pull request.