Agentic Coding Flywheel Setup (ACFS)

🌐 agent-flywheel.com — Interactive setup wizard for beginners

From zero to fully-configured agentic coding VPS in 30 minutes. A complete bootstrapping system that transforms a fresh Ubuntu VPS into a professional AI-powered development environment.

Quick Install

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)" | bash -s -- --yes --mode vibe

The installer is idempotent—if interrupted, simply re-run it. It will automatically resume from the last completed phase without prompts.

Production environments: For stable, reproducible installs, pin to a tagged release or specific commit:

# Preferred: use a tagged release (e.g., v0.5.0)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/v0.5.0/install.sh" | bash -s -- --yes --mode vibe --ref v0.5.0

# Alternative: pin to a specific commit SHA
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/abc1234/install.sh" | bash -s -- --yes --mode vibe --ref abc1234

Tagged releases are tested and stable. Passing --ref ensures all fetched scripts use the same version.

TL;DR

ACFS is a complete system for bootstrapping agentic coding environments:

Why you'd care:

• Zero to Hero: Takes complete beginners from "I have a laptop" to "I have Claude/Codex/Antigravity agents writing code for me on a VPS"
• One-Liner Magic: A single curl | bash command installs 30+ tools, configures everything, and sets up three AI coding agents
• Vibe Mode: Pre-configured for maximum velocity—passwordless sudo, dangerous agent flags enabled, optimized shell environment
• Battle-Tested Stack: Includes the complete Dicklesworthstone stack (10 tools + utilities) for agent orchestration, coordination, and safety

What you get:

• Modern shell (zsh + oh-my-zsh + powerlevel10k)
• All language runtimes (bun, uv/Python, Rust, Go)
• Three AI coding agents (Claude Code, Codex CLI, Antigravity CLI)
• Agent coordination tools (NTM, MCP Agent Mail, SLB)
• Cloud CLIs (Vault, Wrangler, Supabase, Vercel)
• And 20+ more developer tools

The ACFS Experience

graph LR
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%

    subgraph user ["User's Machine"]
        LAPTOP["Laptop"]
        BROWSER["Browser"]
    end

    subgraph wizard ["Wizard Website"]
        STEPS["13-Step Guide"]
    end

    subgraph vps ["Fresh VPS"]
        UBUNTU["Ubuntu 25.10"]
        INSTALLER["install.sh"]
        CONFIGURED["Configured VPS"]
    end

    subgraph agents ["AI Agents"]
        CLAUDE["Claude Code"]
        CODEX["Codex CLI"]
        AGY["Antigravity CLI"]
    end

    LAPTOP --> BROWSER
    BROWSER --> STEPS
    STEPS -->|SSH| UBUNTU
    UBUNTU --> INSTALLER
    INSTALLER --> CONFIGURED
    CONFIGURED --> CLAUDE
    CONFIGURED --> CODEX
    CONFIGURED --> AGY

    classDef user fill:#e3f2fd,stroke:#90caf9,stroke-width:2px
    classDef wizard fill:#fff8e1,stroke:#ffcc80,stroke-width:2px
    classDef vps fill:#f3e5f5,stroke:#ce93d8,stroke-width:2px
    classDef agent fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px

    class LAPTOP,BROWSER user
    class STEPS wizard
    class UBUNTU,INSTALLER,CONFIGURED vps
    class CLAUDE,CODEX,AGY agent

For Beginners

ACFS includes a step-by-step wizard website at agent-flywheel.com that guides complete beginners through:

1. Installing a terminal on their local machine
2. Generating SSH keys (for secure access later)
3. Renting a VPS from providers like OVH or Contabo
4. Connecting via SSH with a password (initial setup)
5. Running the installer (which sets up key-based access)
6. Reconnecting securely with your SSH key
7. Starting to code with AI agents

For Developers

ACFS is a one-liner that transforms any fresh Ubuntu VPS into a fully-configured development environment with modern tooling and three AI coding agents ready to go.

For Teams

ACFS provides a reproducible, idempotent setup that ensures every team member's VPS environment is identical—eliminating "works on my machine" for agentic workflows.

Architecture & Design

ACFS is built around a single source of truth: the manifest file. Everything else—the installer scripts, doctor checks, website content—derives from this central definition. This architecture ensures consistency and makes the system easy to extend.

One-Page System Data Flow

flowchart TB
  %% User and website
  subgraph U["User (local machine)"]
    Browser["Browser"]
    Terminal["Terminal / SSH client"]
  end

  subgraph W["Wizard Website (Next.js 16) — apps/web"]
    Wizard["Wizard UI (/wizard/*)"]
    InstallRoute["GET /install (302 redirect to raw install.sh)"]
    WebState["State: URL params + localStorage"]
  end

  %% Repo sources
  subgraph R["Repo (source)"]
    Manifest["acfs.manifest.yaml<br/>Modules + install + verify + deps"]
    Generator["packages/manifest<br/>Parser (Zod) + generate.ts"]
    Generated["scripts/generated/* (reference)<br/>category installers + doctor_checks.sh"]
    Installer["install.sh (production one-liner)"]
    Lib["scripts/lib/*<br/>security / doctor / update / services-setup"]
    Configs["acfs/*<br/>zshrc + tmux.conf + onboard lessons"]
    Checksums["checksums.yaml<br/>sha256 for upstream installers"]
    Tests["tests/vm/test_install_ubuntu.sh<br/>Docker integration test"]
  end

  %% Target VPS
  subgraph V["Target VPS (Ubuntu 25.10, auto-upgraded)"]
    Run["Run install.sh"]
    Verify["Verified upstream installers<br/>(security.sh + checksums.yaml)"]
    AcfsHome["~/.acfs/<br/>configs + scripts + state.json"]
    Commands["Commands<br/>acfs doctor / acfs update / acfs services-setup / onboard"]
    Tools["Installed tools<br/>bun/uv/rust/go + tmux/rg/gh + vault + ..."]
    Agents["Agent CLIs<br/>claude / codex / agy"]
    Stack["Stack tools<br/>ntm / mcp_agent_mail / ubs / bv / cass / cm / caam / slb / dcg / ru"]
  end

  %% Website guidance flow
  Browser --> Wizard
  Wizard --> WebState
  Wizard --> InstallRoute
  InstallRoute -->|redirects to| Installer

  %% How users fetch/run the installer
  Terminal -->|curl / bash| Installer
  Terminal -->|SSH| Run

  %% Manifest-driven generation (reference today)
  Manifest --> Generator --> Generated
  Generated -.->|planned: install.sh calls generated install_all.sh| Installer

  %% Installer composition
  Lib --> Installer
  Configs --> Installer
  Checksums --> Installer
  Tests -->|validates| Installer

  %% VPS install results
  Installer --> Run
  Run --> Verify
  Verify --> Tools
  Verify --> Agents
  Verify --> Stack
  Run --> AcfsHome --> Commands

┌─────────────────────────────────────────────────────────────────────────────┐
│                            SOURCE OF TRUTH                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  acfs.manifest.yaml                                                  │    │
│  │  Tool Definitions • Install Commands • Verification Logic           │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
┌───────────────────────────────────┐   ┌───────────────────────────────────┐
│        CODE GENERATION            │   │        WIZARD WEBSITE             │
│  ┌─────────────────────────────┐  │   │  ┌─────────────────────────────┐  │
│  │ TypeScript Parser (Zod)     │  │   │  │ apps/web/ (Next.js 16)      │  │
│  │ generate.ts                 │  │   │  │ agent-flywheel.com          │  │
│  └─────────────────────────────┘  │   │  └─────────────────────────────┘  │
└───────────────────────────────────┘   └───────────────────────────────────┘
                    │
                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                     GENERATED OUTPUTS (REFERENCE)                          │
│  ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐   │
│  │ scripts/generated/ │  │ doctor_checks.sh   │  │ install_all.sh     │   │
│  │ 11 Category Scripts│  │ Verification Logic │  │ Master Installer   │   │
│  └────────────────────┘  └────────────────────┘  └────────────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                            INSTALLER                                       │
│  install.sh + scripts/lib/*.sh + checksums.yaml (SHA256 verification)     │
│  (scripts/generated/* are sourced; execution is feature-flagged)            │
└───────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                           TARGET VPS                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ 30+ Tools    │  │ zsh + p10k   │  │ AI Agents    │  │ ~/.acfs/     │   │
│  │ Installed    │  │ Shell Config │  │ Claude/Codex │  │ Configurations│  │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘

Why This Architecture?

Single Source of Truth: The manifest file (acfs.manifest.yaml) defines every tool—its name, description, install commands, and verification logic. When you add or edit a tool in the manifest, the generator automatically updates the generated scripts and manifest-derived checks. The production one-liner installer (install.sh) is still hand-written today, so behavior changes may also require updating install.sh until full migration.

TypeScript + Zod Validation: The manifest parser uses Zod schemas to validate the YAML at parse time. Typos, missing fields, and structural errors are caught immediately during generation—not at runtime on a user's VPS when the installer fails halfway through.

Generated Scripts: Rather than hand-maintaining 11 category installer scripts and keeping them synchronized, the generator produces them from the manifest. This means:

• A consistent, auditable view of manifest-defined install logic (some modules intentionally emit TODOs)
• Consistent error handling and logging across all modules
• A clear path toward future installer integration

Components

The Manifest System

acfs.manifest.yaml is the single source of truth for all tools installed by ACFS. It defines what gets installed, how to install it, and how to verify the installation worked.

Manifest Structure

version: "1.0"
meta:
  name: "ACFS"
  description: "Agentic Coding Flywheel Setup"
  version: "0.1.0"

modules:
  base.system:
    description: "Base packages + sane defaults"
    category: base
    install:
      - sudo apt-get update -y
      - sudo apt-get install -y curl git ca-certificates unzip tar xz-utils jq build-essential
    verify:
      - curl --version
      - git --version
      - jq --version

  agents.claude:
    description: "Claude Code"
    category: agents
    install:
      - "Install claude code via official method"
    verify:
      - claude --version || claude --help

Each module specifies:

• description: Human-readable name
• category: Grouping for installer organization (base, shell, cli, lang, tools, db, cloud, agents, stack, acfs)
• install: Commands to run (or descriptions that become TODOs)
• verify: Commands that must succeed to confirm installation

The Generator Pipeline

The TypeScript generator (packages/manifest/src/generate.ts) reads the manifest and produces:

1. Category Scripts (scripts/generated/install_base.sh, install_agents.sh, etc.)

   • One script per category with individual install functions
   • Consistent logging and error handling
   • Verification checks after each module

2. Doctor Checks (scripts/generated/doctor_checks.sh)

   • All verify commands extracted into a runnable health check
   • Tab-delimited format (to safely handle || in shell commands)
   • Reports pass/fail/skip for each module

3. Master Installer (scripts/generated/install_all.sh)

   • Sources all category scripts
   • Runs them in dependency order
   • Single entry point for running the generated installers

Note: The production one-liner installer (install.sh) defaults to the legacy implementations; generated installers are sourced and can be enabled per-category via feature flags during migration.

To regenerate after manifest changes:

cd packages/manifest
bun run generate        # Generate scripts
bun run generate:dry    # Preview without writing

Why TypeScript for Code Generation?

Shell can parse YAML with yq, but TypeScript + Zod offers:

• Type safety: The parser knows the exact shape of a manifest
• Validation: Zod catches malformed YAML with descriptive errors
• Transformation: Complex logic (sorting by dependencies, escaping) is natural in TypeScript
• Consistency: All generated code follows the same patterns

The generator itself is ~400 lines of TypeScript. The generated output is ~1000 lines of Bash across 13 files. The trade-off is clearly in favor of maintaining the generator.

Security Verification

ACFS downloads and executes installer scripts from the internet. This is inherently risky—a compromised upstream could inject malicious code. The security verification system mitigates this risk.

How It Works

The checksums.yaml file contains SHA256 hashes for all upstream installer scripts:

# checksums.yaml
installers:
  bun:
    url: "https://bun.sh/install"
    sha256: "a1b2c3d4..."

  rust:
    url: "https://sh.rustup.rs"
    sha256: "e5f6a7b8..."

The security library (scripts/lib/security.sh) provides:

1. HTTPS Enforcement: All installer URLs must use HTTPS. Non-HTTPS URLs fail immediately.

2. Checksum Verification: Before executing a downloaded script, the system:

   • Downloads the content to memory
   • Calculates the SHA256 hash
   • Compares against the stored hash
   • Only executes if they match

3. Verification Modes:

   ./scripts/lib/security.sh --print              # List all upstream URLs
   ./scripts/lib/security.sh --verify             # Verify all against saved checksums
   ./scripts/lib/security.sh --update-checksums   # Generate new checksums.yaml
   ./scripts/lib/security.sh --checksum URL       # Calculate SHA256 of any URL
   

When Checksums Fail

A checksum mismatch can mean:

1. Normal update: The upstream maintainer released a new version
2. Potential compromise: Someone modified the script maliciously

The verification report distinguishes these cases:

• If multiple checksums fail simultaneously, investigate before updating
• If a single checksum fails after a known release, update is likely safe

To update after verifying a legitimate upstream change:

./scripts/lib/security.sh --update-checksums > checksums.yaml
git diff checksums.yaml  # Review what changed
git commit -m "chore: update upstream checksums"

Why This Approach?

The curl | bash pattern is controversial but practical. ACFS makes it safer by:

• Verifying content before execution (not just transport via HTTPS)
• Making checksums auditable in version control
• Providing tools to detect and investigate changes
• Failing closed (no execution on mismatch)

This is defense in depth—HTTPS protects transport, checksums protect content.

The Installer

The installer is the heart of ACFS—a modular Bash script that transforms a fresh Ubuntu VPS into a fully-configured development environment.

Usage

Full vibe mode (recommended for throwaway VPS):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)" | bash -s -- --yes --mode vibe

Interactive mode (asks for confirmation):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash

Safe mode (no passwordless sudo, agent confirmations enabled):

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --mode safe

Installer Modes

Installation Phases

graph TD
    %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%

    A["Phase 1: User Normalization<br/><small>Create ubuntu user, migrate SSH keys</small>"]
    B["Phase 2: APT Packages<br/><small>Essential system packages</small>"]
    C["Phase 3: Shell Setup<br/><small>zsh, oh-my-zsh, powerlevel10k</small>"]
    D["Phase 4: CLI Tools<br/><small>ripgrep, fzf, lazygit, etc.</small>"]
    E["Phase 5: Language Runtimes<br/><small>bun, uv, rust, go</small>"]
    F["Phase 6: AI Agents<br/><small>claude, codex, agy</small>"]
    G["Phase 7: Cloud Tools<br/><small>vault, wrangler, supabase, vercel</small>"]
    H["Phase 8: Dicklesworthstone Stack<br/><small>ntm, dcg, ru, ubs, mcp_agent_mail, etc.</small>"]
    I["Phase 9: Configuration<br/><small>Deploy acfs.zshrc, tmux.conf</small>"]
    J["Phase 10: Verification<br/><small>acfs doctor</small>"]

    A --> B --> C --> D --> E --> F --> G --> H --> I --> J

    classDef phase fill:#e8f5e9,stroke:#81c784,stroke-width:2px,color:#2e7d32
    class A,B,C,D,E,F,G,H,I,J phase

Key Properties

Resume Capability

The installer tracks progress in ~/.acfs/state.json. If interrupted:

• Re-run the same command—it resumes from the last completed phase
• No prompts or confirmations needed (with --yes)
• Already-installed tools are detected and skipped

To force a fresh reinstall of all tools:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --yes --mode vibe --force-reinstall

Pre-Flight Check

Before running the full installer, validate your system:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash -s -- --json
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash -s -- --format toon
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/preflight.sh" | bash -s -- --network=skip

This checks:

• OS compatibility (Ubuntu 22.04+; installer upgrades to 25.10)
• Architecture (x86_64 or ARM64)
• Memory and disk space (minimum 4GB RAM, 10GB free disk)
• Network connectivity to required URLs
• Cached checksums.yaml availability for verified upstream installers
• APT lock status
• Potential conflicts (nvm, pyenv, existing ACFS)

Network checks performed:

For checksum-refresh review, compare a generated candidate without changing checksums.yaml:

candidate="/tmp/acfs-checksums.$$.candidate.yaml"
./scripts/lib/security.sh --update-checksums > "$candidate"
./scripts/preflight.sh --checksum-candidate "$candidate"

Common preflight failures:

Console Output

The installer uses semantic colors for progress visibility:

[1/8] Installing essential packages...     # Blue: progress steps
    Installing zsh, git, curl...           # Gray: details
⚠️  May take a few minutes                 # Yellow: warnings
✖ Failed to install package               # Red: errors
✔ Shell setup complete                    # Green: success

Automatic Ubuntu Upgrade

ACFS automatically upgrades Ubuntu to version 25.10 before installation when running on older versions. This ensures compatibility with the latest packages and optimal performance.

How it works:

1. Detects your current Ubuntu version
2. Calculates the upgrade path (e.g., 24.04 → 25.04 → 25.10)
3. Performs sequential do-release-upgrade operations
4. Reboots after each upgrade (handled automatically)
5. Resumes via systemd service after reboot
6. Continues ACFS installation once at target version

Expected timeline:

• Each version hop takes 30-60 minutes
• Full chain from 24.04 → 25.10 takes 1.5-3 hours
• SSH sessions disconnect during reboots (reconnect to monitor)

To skip automatic upgrade:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --yes --mode vibe --skip-ubuntu-upgrade

To specify a different target version:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh" | bash -s -- --yes --mode vibe --target-ubuntu=25.04

Monitoring upgrade progress:

# Check current status
/var/lib/acfs/check_status.sh

# View upgrade logs
journalctl -u acfs-upgrade-resume -f

# View detailed logs
tail -f /var/log/acfs/upgrade_resume.log

Important notes:

• Create a VM snapshot before upgrading (recommended but not required)
• Upgrades cannot be undone without restoring from snapshot
• The system will reboot multiple times automatically
• EOL interim releases (like 24.10) may be skipped automatically if they are no longer offered by do-release-upgrade
• Reconnect via SSH after each reboot to monitor progress

The Update Command

After installation, keeping tools current is handled by acfs-update. It provides a unified interface for updating all installed components.

Usage

acfs-update                  # Update apt, runtimes, shell, agents, cloud CLIs, and stack tools
acfs-update --agents-only    # Only update coding agents
acfs-update --runtime-only   # Only update runtimes (bun, rust, uv, go)
acfs-update --dry-run        # Preview changes without making them
acfs-update --yes --quiet --no-self-update
                             # Automated mode that avoids changing the ACFS tree itself
acfs-update --bootstrap-self-update
                             # Explicitly convert a non-git ACFS install into a git checkout

What Gets Updated

Options

Category Selection:

--apt-only       Only update system packages
--agents-only    Only update coding agents
--cloud-only     Only update cloud CLIs
--shell-only     Only update shell tools (OMZ, P10K, plugins, Atuin, Zoxide)
--runtime-only   Only update runtimes (bun, rust, uv, go)
--stack          Include Dicklesworthstone stack (enabled by default)

Skip Categories:

--no-apt         Skip apt updates
--no-agents      Skip agent updates
--no-cloud       Skip cloud CLI updates
--no-shell       Skip shell tool updates
--no-runtime     Skip runtime updates (bun, rust, uv, go)

Behavior:

--force            Install missing tools (not just update existing)
--dry-run          Preview changes without making them
--yes, -y          Non-interactive mode (skip prompts)
--quiet, -q        Minimal output (only errors and summary)
--verbose, -v      Show detailed command output
--abort-on-failure Stop on first failure (default: continue)

Logs

Update logs are automatically saved to ~/.acfs/logs/updates/ with timestamps:

# View most recent log
cat ~/.acfs/logs/updates/$(ls -1t ~/.acfs/logs/updates | head -1)

# Follow a running update
tail -f ~/.acfs/logs/updates/$(ls -1t ~/.acfs/logs/updates | head -1)

Why Separate from the Installer?

The installer transforms a fresh VPS. The update command maintains an existing installation. Separating them allows:

• Focused updates: Update just agents without touching system packages
• Dry-run previews: See what would change before committing
• Skip flags: Temporarily exclude categories that are working fine
• Stack control: Stack updates are included by default; skip with --no-stack
• Automated updates: Run via cron with --yes --quiet

ACFS CLI Commands

After installation, the acfs command provides a unified interface for managing your environment. Each subcommand is designed to be fast, informative, and scriptable.

Quick Reference

acfs info                    # Lightning-fast system overview
acfs cheatsheet              # Discover installed aliases
acfs dashboard generate      # Generate HTML status page
acfs doctor                  # Health checks
acfs newproj                 # Create a new project (TUI or CLI)
acfs update                  # Update all tools
acfs services-setup          # Configure agent credentials
acfs continue                # View upgrade progress after reboot

acfs newproj — New Project Wizard

Create a new project directory with ACFS defaults (git init, optional br/beads, Claude settings, AGENTS.md). The interactive wizard is recommended for beginners.

Interactive wizard (recommended):

acfs newproj --interactive
acfs newproj -i
acfs newproj -i myapp         # Prefill project name

The wizard guides you through:

• Project naming and location
• Tech stack detection/selection
• Feature selection (br/beads, Claude settings, AGENTS.md, UBS ignore)
• AGENTS.md customization preview

    ╔═══════════════════════════════════════════════════════╗
    ║                                                       ║
    ║      █████╗  ██████╗ ███████╗ ███████╗                ║
    ║     ██╔══██╗██╔════╝ ██╔════╝ ██╔════╝                ║
    ║     ███████║██║      █████╗   ███████╗                ║
    ║     ██╔══██║██║      ██╔══╝   ╚════██║                ║
    ║     ██║  ██║╚██████╗ ██║      ███████║                ║
    ║     ╚═╝  ╚═╝ ╚═════╝ ╚═╝      ╚══════╝                ║
    ║                                                       ║
    ║          Agentic Coding Flywheel Setup                ║
    ║                                                       ║
    ╚═══════════════════════════════════════════════════════╝

This wizard will help you set up a new project with:

  ✓ Project directory structure
  ✓ Git repository initialization
  ✓ AGENTS.md for AI coding assistants
  ✓ Beads issue tracking (optional)
  ✓ Claude Code settings (optional)

──────────────────── Review & Confirm ────────────────────
                                              Step 7 of 9

Please review your selections before creating the project.

Project Summary
──────────────────────────────────────────────────────────
  Name:       myapp
  Location:   /home/user/projects/myapp
  Tech:       Node.js, TypeScript

Features
──────────────────────────────────────────────────────────
  ✓ Beads tracking
  ✓ Claude Code settings
  ✓ AGENTS.md
  ✓ UBS ignore

Files to Create
──────────────────────────────────────────────────────────
myapp/
├── .git/
├── AGENTS.md
├── .beads/
│   └── beads.db
├── .claude/
│   └── settings.local.json
├── .ubsignore
├── README.md
└── .gitignore

Options:
  [Enter/c]   Create project
  [e]         Edit selections (go back)
  [q/Esc]     Cancel

CLI mode (automation):

acfs newproj myapp
acfs newproj myapp /custom/path
acfs newproj myapp --no-br

Notes:

• The TUI uses gum when available (arrow keys, Space to toggle, Enter to confirm). Without gum, it falls back to numbered prompts.
• Minimum terminal size: 60x15.
• CLI mode skips existing AGENTS.md; the wizard overwrites it, so move it aside if you want to keep the old one.

acfs info — System Overview

Displays installation status in under 1 second by reading cached state (no verification).

acfs info                # Terminal output (default)
acfs info --json         # JSON output for scripting
acfs info --html         # Self-contained HTML page
acfs info --minimal      # Just essentials (IP, key commands)

Example output:

╔══════════════════════════════════════════════════════════════╗
║                    ACFS System Info                           ║
╠══════════════════════════════════════════════════════════════╣
║  Host: vps-12345.contabo.net                                  ║
║  IP: 192.168.1.100                                            ║
║  User: ubuntu                                                 ║
║  Uptime: 3 days, 4 hours                                      ║
║                                                               ║
║  Quick Commands:                                              ║
║    cc    → Claude Code (dangerous mode)                       ║
║    cod   → Codex CLI (dangerous mode)                         ║
║    agy   → Antigravity CLI (Gemini 3.1 Pro High)              ║
║    ntm   → Named Tmux Manager                                 ║
╚══════════════════════════════════════════════════════════════╝

Design Philosophy:

• Speed: Must complete in <1 second
• Read-only: Never verifies or tests (that's doctor's job)
• Offline: No network calls required
• Fallback: Graceful degradation if data missing

acfs cheatsheet — Alias Discovery

Parses ~/.acfs/zsh/acfs.zshrc to show all installed aliases and commands.

acfs cheatsheet              # List all aliases
acfs cheatsheet git          # Filter by category or search term
acfs cheatsheet --category Agents
acfs cheatsheet --search docker
acfs cheatsheet --json       # JSON output for tooling

Example output:

╔═══════════════════════════════════════════════════════════════╗
║  ACFS Cheatsheet                                               ║
╠═══════════════════════════════════════════════════════════════╣
║  Agents                                                        ║
║    cc   → claude --dangerously-skip-permissions                ║
║    cod  → codex --dangerously-bypass-approvals-and-sandbox     ║
║    agy  → agy --model 'Gemini 3.1 Pro (High)'                  ║
║                                                                ║
║  Git                                                           ║
║    gs   → git status                                           ║
║    gp   → git push                                             ║
║    gl   → git pull                                             ║
║    gco  → git checkout                                         ║
║                                                                ║
║  Modern CLI                                                    ║
║    ls   → lsd --inode --long --all                             ║
║    cat  → bat                                                  ║
║    grep → rg                                                   ║
║    lg   → lazygit                                              ║
╚═══════════════════════════════════════════════════════════════╝

acfs dashboard — HTML Status Page

Generates a self-contained HTML dashboard and optionally serves it.

acfs dashboard generate              # Generate ~/.acfs/dashboard/index.html
acfs dashboard generate --force      # Force regeneration
acfs dashboard serve                 # Serve on localhost:8080
acfs dashboard serve --port 3000     # Custom port
acfs dashboard serve --public        # Bind to 0.0.0.0

The dashboard provides:

• System health at a glance
• Tool versions and status
• Quick command reference
• Recent activity summary

acfs services-setup — Credential Configuration

Interactive wizard for configuring AI agent credentials and cloud service logins.

acfs services-setup          # Run full setup wizard

Guides you through:

• Claude Code: API key configuration
• Codex CLI: ChatGPT account login
• Antigravity CLI: Google account authentication
• GitHub CLI: gh auth login
• Cloud CLIs: Wrangler, Supabase, Vercel authentication

Also offers to install DCG (Destructive Command Guard), a Claude Code hook that blocks destructive commands like rm -rf /.

acfs continue — Upgrade Progress

After an Ubuntu upgrade reboot, view installation progress:

acfs continue                # Show current upgrade status

Displays:

• Original Ubuntu version
• Target version
• Current upgrade stage
• Next steps after completion

Learning Hub (Web)

In addition to the terminal-based onboarding, ACFS provides a comprehensive web-based Learning Hub at agent-flywheel.com/learn.

Web Lessons

The Learning Hub provides interactive lessons with progress tracking:

Features:

• Progress tracking in localStorage
• Code blocks with copy buttons
• Expandable deep-dive sections
• Practical exercises

Command Reference

The Command Reference documents every installed tool:

Technical Glossary

The Glossary defines 100+ technical terms with:

• One-liner: Quick tooltip definition
• Full explanation: Plain language description
• Analogy: "Think of it like..."
• Why we use it: Problem it solves
• Related terms: For context

Example entry:

RAM (Random Access Memory)
├── Short: Fast temporary storage your computer uses while working
├── Long: RAM is your computer's short-term memory...
├── Analogy: Like your desk space while working
├── Why: More RAM = run more programs simultaneously
└── Related: vCPU, VPS, NVMe

Flywheel Visualization

The Flywheel page visualizes tool interactions:

Plan (Beads) ──> Coordinate (Agent Mail) ──> Execute (NTM + Agents)
      ^                                              │
      │                                              v
      └──── Remember (CASS Memory) <──── Scan (UBS) ┘

Workflow Scenarios:

Tool Status Page

The Tool Status page provides a searchable catalog of all installed tools:

• Search & Filter: Find tools by name, CLI command, features, or tech stack
• Category Browsing: Filter by "Flywheel Stack" (core agentic tools) or "Utilities"
• Tool Details: Each card shows the tool name, CLI command, GitHub stars, features, and tech stack
• Live Data: Content is auto-generated from acfs.manifest.yaml — never manually edited

This page helps users discover tools they may not know about and understand how each fits into the agentic coding workflow.

Interactive Website Components

The wizard website includes specialized components for guiding beginners:

ConnectionCheck Component: A prominent visual that helps users verify they're connected to their VPS before running commands:

• Side-by-side comparison: "Wrong (laptop)" vs "Right (VPS)"
• Terminal prompt examples for Windows, Mac, and Linux
• Clear "STOP!" warning with color-coded styling

CommandCard Component: CLI instruction cards with:

• Syntax-highlighted code blocks
• One-click copy button
• Platform-specific variations (bash/zsh/PowerShell)
• Expandable explanations

Jargon Component (Responsive Technical Terms): A sophisticated tooltip system that adapts to device capabilities:

Desktop behavior:

• Hover reveals floating tooltip with term definition
• Radix UI Tooltip for accessible ARIA-compliant overlays
• Viewport-aware positioning (auto-flips when near edges)
• 200ms hover delay prevents tooltip spam

Mobile behavior:

• Tap opens bottom sheet drawer (Vaul library)
• Full definition visible without tiny tap targets
• Swipe-to-dismiss gesture support
• Snap points for partial/full expansion

Visual features:

• Gradient underline indicates tappable term
• Each term gets unique gradient based on slug hash
• Consistent color scheme with OKLCH tokens

Content structure per term:

{
  term: "VPS",
  short: "Virtual Private Server - a remote computer you rent",
  long: "A VPS is your own slice of a powerful computer...",
  analogy: "Think of it like renting an apartment in a building",
  whyWeUseIt: "You get root access, dedicated resources...",
  relatedTerms: ["SSH", "Ubuntu", "RAM"]
}

Confetti Celebration: On lesson completion:

• Burst of celebratory confetti particles
• Randomized encouraging messages
• Special celebration for completing all lessons
• Respects prefers-reduced-motion setting

Stepper Component: Multi-step progress indicator:

• Visual step-by-step progress
• Clickable navigation
• Completion checkmarks
• Mobile-responsive design

Expanded Lesson Library

The Learning Hub includes specialized lessons for each tool in the Dicklesworthstone stack:

Each lesson includes:

• Conceptual introduction
• Practical commands with examples
• Interactive exercises
• Common pitfalls to avoid
• Links to tool documentation

Interactive Onboarding (TUI)

After installation, users can learn the ACFS workflow through an interactive terminal-based tutorial. The onboarding TUI discovers lesson markdown files dynamically from acfs/onboard/lessons, so the curriculum can grow as new tools and workflows are added without changing the launcher.

Running Onboarding

onboard                # Launch interactive menu
onboard status         # Show completion status
onboard --list         # Alias for status
onboard 3              # Jump to lesson 3
onboard reset          # Reset progress and start fresh
onboard --reset        # Alias for reset

Lessons

Run onboard --help to see the currently discovered lesson list. The curriculum currently spans Linux basics, SSH, tmux, agent login, NTM, the flywheel workflow, updating, Beads, RCH, and other ACFS tools. Because lessons are discovered by filename, adding a new NN_name.md file automatically extends the tutorial.

Progress Tracking

Progress is saved in ~/.acfs/onboard_progress.json:

{
  "completed": [0, 1, 2],
  "current": 3,
  "started_at": "2024-12-20T10:30:00-05:00"
}

The TUI shows completion status for each lesson and suggests the next one to take. Users can jump to any lesson or re-take completed ones.

Enhanced UX with Gum

If Charmbracelet Gum is installed, the onboarding system uses it for enhanced terminal UI—selection menus, styled prompts, and better formatting. Without Gum, it falls back to simple numbered menus that work everywhere.

Tools Installed

ACFS installs a comprehensive suite of 30+ tools organized into categories:

Shell & Terminal UX

Languages & Package Managers

Dev Tools

Networking

Tailscale Integration:

Tailscale provides secure, encrypted networking between your devices without complex firewall configuration:

# Authenticate and join your tailnet
tailscale up

# Check connection status
tailscale status

# Get your Tailscale IP
tailscale ip

# SSH over Tailscale (bypasses firewalls)
ssh ubuntu@your-vps.tailnet-name.ts.net

Benefits for agentic workflows:

• Firewall-free access: Connect even when behind NAT or restrictive firewalls
• MagicDNS: Access your VPS by hostname instead of IP
• SSH keys over Tailscale: Use tailscale ssh for key-free authentication
• ACLs: Fine-grained access control for team environments

AI Coding Agents

Vibe Mode Aliases:

# Claude Code with max memory (background tasks enabled by default)
alias cc='NODE_OPTIONS="--max-old-space-size=32768" claude --dangerously-skip-permissions'

# Codex with bypass and dangerous filesystem access
alias cod='codex --dangerously-bypass-approvals-and-sandbox'

# Antigravity CLI, model/settings/DCG locked by the ACFS launcher
alias agy='$HOME/.local/bin/agy-locked'
alias gmi='$HOME/.local/bin/agy-locked'

Installation & Updates: Claude Code should be installed and updated using its native mechanisms:

• Install: ACFS uses the official native installer (claude.ai/install.sh), checksum-verified via checksums.yaml (installs to ~/.local/bin/claude)
• Update: Use claude update --channel latest (built-in) or run acfs update --agents-only

This ensures proper authentication handling and avoids issues with alternative package manager builds. ACFS updates Codex with Bun global package updates and Antigravity with its native agy update path.

Cloud & Database

Vault is installed by default (skip with --skip-vault). ACFS installs the Vault CLI so you have a real secrets tool available early; it does not automatically configure a Vault server for you.

Supabase networking note: some Supabase projects expose the direct Postgres host over IPv6-only (often on free tiers). If your VPS/network is IPv4-only, use the Supabase pooler connection string instead (or upgrade/configure networking for direct IPv4).

Dicklesworthstone Stack (10 Tools)

The complete suite of tools for professional agentic workflows:

Bundled Utilities

Additional productivity tools installed alongside the stack:

Doctor Command

acfs doctor performs comprehensive health checks on your installation:

$ acfs doctor

╔══════════════════════════════════════════════════════════════╗
║                    ACFS Health Check                          ║
╠══════════════════════════════════════════════════════════════╣
║ Identity                                                      ║
║   ✔ Running as ubuntu user                                    ║
║   ✔ Passwordless sudo enabled                                 ║
║                                                               ║
║ Workspace                                                     ║
║   ✔ /data/projects exists                                     ║
║                                                               ║
║ Shell                                                         ║
║   ✔ zsh installed                                             ║
║   ✔ oh-my-zsh installed                                       ║
║   ✔ powerlevel10k installed                                   ║
║   ✔ acfs.zshrc sourced                                        ║
║                                                               ║
║ Core Tools                                                    ║
║   ✔ bun 1.2.16                                                ║
║   ✔ uv 0.5.14                                                 ║
║   ✔ cargo 1.84.0                                              ║
║   ✔ go 1.23.4                                                 ║
║   ✔ ripgrep 14.1.0                                            ║
║   ✔ ast-grep 0.30.1                                           ║
║                                                               ║
║ Agents                                                        ║
║   ✔ claude 1.0.24                                             ║
║   ✔ codex 0.1.2504252326                                      ║
║   ✔ agy 1.0.12                                                ║
║                                                               ║
║ Cloud                                                         ║
║   ✔ vault 1.18.3                                              ║
║   ✔ wrangler 4.16.0                                           ║
║   ✔ supabase 2.23.4                                           ║
║   ✔ vercel 41.7.6                                             ║
║                                                               ║
║ Dicklesworthstone Stack                                       ║
║   ✔ ntm 0.3.2                                                 ║
║   ✔ slb 0.2.1                                                 ║
║   ✔ ubs 0.1.8                                                 ║
║   ✔ bv 0.9.4                                                  ║
║   ✔ cass 0.4.2                                                ║
║   ✔ cm 0.1.3                                                  ║
║   ✔ caam 0.2.0                                                ║
║   ✔ dcg 0.1.0                                                 ║
║   ✔ ru 1.2.0                                                  ║
║   ⚠ mcp_agent_mail (not running)                              ║
║                                                               ║
║ Utilities                                                     ║
║   ✔ giil 3.0.0                                                ║
║   ✔ csctf 1.0.0                                               ║
╠══════════════════════════════════════════════════════════════╣
║ Overall: 35/36 checks passed                                  ║
╚══════════════════════════════════════════════════════════════╝

Generated Doctor Checks

Doctor checks are generated from the manifest (scripts/generated/doctor_checks.sh) to keep verification logic close to acfs.manifest.yaml. The acfs doctor command automatically sources these generated checks to verify all manifest-defined tools.

How it works:

1. The manifest generator creates doctor_checks.sh with verify commands for each module
2. acfs doctor sources this file and runs each verification check
3. Failed checks display a fix suggestion with the exact command to reinstall

Example output with fix suggestion:

  ✗ tools.lazygit - Lazygit terminal UI not found
    Fix: acfs install --only tools.lazygit

This architecture ensures doctor checks stay in sync with the installer—if a tool is in the manifest, it will be verified.

Options

acfs doctor              # Interactive colorful output
acfs doctor --json       # Machine-readable JSON output
acfs doctor --quiet      # Exit code only (0=healthy, 1=issues)
acfs doctor --deep       # Run functional tests (auth, connections)
acfs doctor --fix        # Apply safe fixes for failed checks
acfs doctor --dry-run    # Preview fixes without applying
acfs doctor --no-cache   # Skip cache, run all checks fresh

Deep Checks (--deep)

The --deep flag runs functional tests beyond binary existence:

Deep checks use 5-second timeouts to avoid hanging on network issues. Results are cached for 5 minutes to speed up repeated runs.

Example output:

Deep Checks
  ✔ Claude auth configured
  ✔ PostgreSQL connection working
  ⚠ Codex not authenticated (run: codex login)
  ✔ GitHub CLI authenticated

8/9 functional tests passed in 3.2s

Auto-Fix Mode (--fix)

The --fix flag automatically applies safe, deterministic fixes for common issues:

acfs doctor --fix             # Apply safe fixes
acfs doctor --fix --dry-run   # Preview fixes without applying

Safe Auto-Fixers

These fixes are applied automatically when --fix is used:

Safety Guarantees

• Never deletes user files — Only creates, modifies, or symlinks
• Backups before modify — SHA256-verified backups of all modified files
• Idempotent — Safe to run multiple times
• Logged — All changes recorded to ~/.local/share/acfs/doctor.log
• Reversible — Every fix has an undo command

Example Dry-Run Output

DRY-RUN: acfs doctor --fix

Would apply the following fixes:

  [fix.path.ordering]
    Action: Prepend PATH directories to ~/.zshrc
    File: ~/.zshrc
    Backup: Yes (SHA256 verified)

  [fix.acfs.sourcing]
    Action: Add ACFS sourcing to .zshrc
    File: ~/.zshrc
    Backup: Yes (SHA256 verified)

Fixes that require manual action:
  [shell.ohmyzsh]
    Status: FAIL
    Suggestion: curl -fsSL https://install.ohmyz.sh/ | bash

Summary: 2 auto-fixes, 0 prompted, 1 manual

Manual-Only Fixes

Some operations are never auto-fixed and instead provide suggestions:

• Package manager operations (apt install ...)
• Anything requiring sudo
• File deletions
• Complex shell configuration changes

Undoing Changes

All changes made by --fix can be undone:

acfs undo --list      # List all changes
acfs undo chg_0001    # Undo specific change
acfs undo --all       # Undo all changes from last session

The Wizard Website

The wizard guides beginners through a 13-step journey from "I have a laptop" to "AI agents are coding for me":

┌─────────────────────────────────────────────────────────────────────────────┐
│  ACFS Wizard                                                   [Step 3/13]  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │  STEP 3: Generate SSH Key                                              │ │
│  │  ──────────────────────────────────────────────────────────────────    │ │
│  │                                                                        │ │
│  │  Run this command in your terminal:                                    │ │
│  │                                                                        │ │
│  │  ┌─────────────────────────────────────────────────────────────────┐  │ │
│  │  │ ssh-keygen -t ed25519 -C "your-email@example.com"         [📋] │  │ │
│  │  └─────────────────────────────────────────────────────────────────┘  │ │
│  │                                                                        │ │
│  │  ☐ I ran this command                                                  │ │
│  │                                                                        │ │
│  │  [← Previous]                                        [Next Step →]     │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
│  Progress: ●●●○○○○○○○○○○                                                   │
└─────────────────────────────────────────────────────────────────────────────┘

Wizard Steps

Key Features

• OS Detection: Auto-detects Mac vs Windows for tailored instructions
• Copy-to-Clipboard: One-click copy for all commands
• Handoff Runbook: Downloadable JSON/Markdown artifact for the installer command and recovery steps
• Progress Tracking: localStorage persistence across browser sessions
• Confirmation Checkboxes: "I ran this command" acknowledgments
• Troubleshooting: Expandable help for common issues

Wizard Handoff Runbook

Step 9 can download a local handoff runbook in JSON or Markdown. The runbook is meant for the user and support loop when an SSH session drops, an install is interrupted, or the user needs to remember the exact command they ran.

Schema: acfs.handoff-runbook.v1

Host addresses are not written into the runbook. The installer command stays exact so a user can paste it back into the VPS session, and the artifact points to support-report.md and manifest.json for support-bundle review.

Technology Stack

Next.js 16 (App Router)
├── React 19
├── Tailwind CSS 4 (OKLCH colors)
├── shadcn/ui components
├── Radix UI primitives
└── Lucide icons

No backend required. All state is stored in:

• URL query parameters
• localStorage (agent-flywheel-user-os, agent-flywheel-vps-ip, agent-flywheel-wizard-completed-steps)

Wizard State Management

The wizard uses TanStack Query for state management with optimistic updates and cross-tab synchronization:

Architecture:

// Query-based state with localStorage persistence
const { data: steps } = useQuery({
  queryKey: ['wizardSteps', 'completed'],
  queryFn: getCompletedSteps,  // Reads from localStorage
  staleTime: 0,                // Always check for updates
  gcTime: Infinity,            // Never garbage collect
});

Optimistic Updates with Rollback:

const mutation = useMutation({
  mutationFn: async (stepId) => {
    const newSteps = addCompletedStep(currentSteps, stepId);
    setCompletedSteps(newSteps);  // Persist to localStorage
    return newSteps;
  },
  onMutate: (stepId) => {
    // Optimistically update cache immediately
    const previousSteps = queryClient.getQueryData(queryKey);
    queryClient.setQueryData(queryKey, addCompletedStep(baseSteps, stepId));
    return { previousSteps };  // For rollback
  },
  onError: (_err, _stepId, context) => {
    // Rollback on failure
    queryClient.setQueryData(queryKey, context.previousSteps);
  },
});

Cross-Tab Synchronization: The wizard maintains sync across browser tabs via two mechanisms:

1. Custom DOM events for same-tab coordination between components
2. Storage events for cross-tab updates when localStorage changes

// Same-tab: custom event dispatch
window.dispatchEvent(new CustomEvent('acfs:wizard:completed-steps-changed', {
  detail: { steps }
}));

// Cross-tab: storage event listener
window.addEventListener('storage', (event) => {
  if (event.key === COMPLETED_STEPS_KEY) {
    queryClient.setQueryData(queryKey, getCompletedSteps());
  }
});

Safe localStorage Utilities: All localStorage access is wrapped in safe utilities that handle SSR, private browsing, and quota exceeded errors:

// Safe read (returns null on any error)
export function safeGetJSON<T>(key: string): T | null;

// Safe write (returns boolean success)
export function safeSetJSON(key: string, value: unknown): boolean;

// URL preservation for state fallback
export function withCurrentSearch(path: string): string;

This architecture ensures the wizard progress survives browser refreshes, works across tabs, and degrades gracefully when localStorage is unavailable.

Configuration Files

ACFS deploys optimized configuration files to ~/.acfs/ on the target VPS.

~/.acfs/zsh/acfs.zshrc

A comprehensive zsh configuration that's sourced by ~/.zshrc:

Oh-My-Zsh Plugins (14 total):

Note: zsh-autosuggestions and zsh-syntax-highlighting are custom plugins installed from GitHub. They must be listed last for optimal performance.

Path Configuration:

export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="$HOME/go/bin:$PATH"
export PATH="$HOME/.bun/bin:$PATH"

Atuin is still installed, but ACFS keeps it behind the guarded ~/.local/bin/atuin shim instead of putting ~/.atuin/bin at the front of interactive shell PATH.

Modern CLI Aliases:

alias ls='lsd --inode --long --all'
alias ll='lsd -l'
alias tree='lsd --tree'
alias cat='bat'
alias grep='rg'
alias vim='nvim'
alias lg='lazygit'

Tool Integrations:

# Zoxide (smarter cd)
eval "$(zoxide init zsh)"

# direnv (directory env vars)
eval "$(direnv hook zsh)"

# fzf (fuzzy finder)
source /usr/share/doc/fzf/examples/key-bindings.zsh

Shell Keybindings (Quality of Life):

Atuin History Bindings: ACFS intentionally does not enable Atuin's zsh preexec/precmd integration by default. Atuin's searchable CLI remains available as atuin search, but the automatic shell hook can record every coding-agent command and grow the Atuin database fast enough to make shells laggy.

~/.acfs/tmux/tmux.conf

A tmux configuration specifically optimized for NTM and multi-agent workflows:

Key Bindings:

Prefix: Ctrl+a (not Ctrl+b - more ergonomic)
Split horizontal: |  (preserves working directory)
Split vertical: -    (preserves working directory)
Navigate panes: h/j/k/l (vim-style)
Resize panes: H/J/K/L (repeatable with -r flag)
Reload config: r
New window: c (preserves working directory)

Copy Mode (vim-style):

Enter copy mode: prefix + [
Begin selection: v
Rectangle selection: r
Copy and exit: y

Agent Workflow Optimizations:

Catppuccin-Inspired Theme:

# Status bar (top position, less intrusive)
status-style: bg=#1e1e2e, fg=#cdd6f4

# Session indicator (blue accent)
status-left: #[fg=#89b4fa,bold] #S

# Active window highlight (pink accent)
window-status-current-format: #[fg=#f5c2e7,bold] #I:#W

# Pane borders
pane-border-style: fg=#313244
pane-active-border-style: fg=#89b4fa  # Blue highlight

Local Overrides: The config sources ~/.tmux.conf.local if it exists, allowing personal customizations without modifying ACFS defaults.

Library Modules

The installer is organized into modular Bash libraries in scripts/lib/:

logging.sh

Colored console output utilities:

log_step "1/8" "Installing packages..."  # Blue step indicator
log_detail "Installing zsh..."           # Gray indented detail
log_success "Complete"                    # Green checkmark
log_warn "May take a while"              # Yellow warning
log_error "Failed"                        # Red error
log_fatal "Cannot continue"              # Red error + exit 1

security.sh

HTTPS enforcement and checksum verification:

enforce_https "$url"                     # Fail if not HTTPS
verify_checksum "$url" "$sha256" "$name" # Verify before execute
fetch_and_run "$url" "$sha256" "$name"   # Verify + execute in one

os_detect.sh

OS detection and validation:

detect_os()      # Sets OS_ID, OS_VERSION, OS_CODENAME
validate_os()    # Checks for Ubuntu 25.10 (or upgrade path)
is_fresh_vps()   # Heuristic detection of fresh VPS
get_arch()       # Returns amd64/arm64
is_wsl()         # Detects WSL
is_docker()      # Detects Docker container

user.sh

User account normalization:

ensure_user()              # Creates ubuntu user if missing
enable_passwordless_sudo() # Adds NOPASSWD to sudoers
migrate_ssh_keys()         # Copies keys from root to ubuntu
normalize_user()           # Full normalization sequence

update.sh

Component update logic with version tracking and logging:

update_apt()       # apt update/upgrade with lock detection
update_bun()       # bun upgrade with version tracking
update_agents()    # Claude, Codex, Antigravity (version before/after)
update_cloud()     # Wrangler, Supabase, Vercel (Supabase uses verified release tarball)
update_rust()      # rustup update stable
update_uv()        # uv self update
update_go()        # Go toolchain update
update_shell()     # OMZ, P10K, plugins, Atuin, Zoxide
update_stack()     # Dicklesworthstone stack tools

# Features:
# - Automatic logging to ~/.acfs/logs/updates/
# - Version tracking (before/after for each tool)
# - APT lock detection and warning
# - Reboot-required detection for kernel updates
# - Dry-run mode with --dry-run flag

gum_ui.sh

Enhanced terminal UI using Charmbracelet Gum:

print_banner()           # ASCII art ACFS banner
gum_step/gum_detail      # Styled output
gum_success/warn/error   # Colored messages
gum_spin                 # Spinner for long operations
gum_confirm              # Yes/No prompt
gum_choose               # Selection menu

Falls back to basic echo if Gum is not installed.

error_tracking.sh

Sophisticated error collection and reporting:

track_error "phase" "step" "error_message"
track_warning "phase" "step" "warning_message"
get_error_report                    # Generate structured error report
get_error_count                     # Count of tracked errors
has_errors                          # Boolean check for any errors

Features:

• Collects errors without aborting execution
• Associates errors with phase and step context
• Generates end-of-run summary reports
• Distinguishes warnings from errors

state.sh

State machine management for installation progress (v3 schema):

state_init                          # Initialize state file
state_get_phase                     # Current phase
state_set_phase "phase_name"        # Set current phase
state_mark_complete "phase_name"    # Mark phase complete
state_has_completed "phase_name"    # Check if phase done
state_save                          # Persist to disk (atomic)
state_load                          # Load from disk

The state file (~/.acfs/state.json) uses atomic writes to prevent corruption.

contract.sh

Runtime contract validation for generated scripts:

acfs_require_contract "module_id"   # Assert environment is ready
acfs_check_contract                 # Non-fatal contract check

Validates that required environment variables and functions exist before execution:

• TARGET_USER, TARGET_HOME, MODE
• ACFS_BOOTSTRAP_DIR, ACFS_LIB_DIR
• Logging functions: log_detail, log_success, etc.

smoke_test.sh

Post-install verification that runs automatically after installation:

run_smoke_test                      # Execute all smoke tests

Critical Checks (must pass):

• Running as ubuntu user
• Passwordless sudo enabled
• Zsh is default shell
• Core tools accessible (bun, uv, cargo)

Non-Critical Checks (warnings only):

• Agent authentication configured
• Cloud CLIs authenticated
• Optional tools installed

Example output:

[Smoke Test]
  ✅ Running as ubuntu user
  ✅ Passwordless sudo enabled
  ✅ Zsh is default shell
  ✅ bun --version works
  ⚠️  Codex not authenticated (run: codex login)
  ✅ 8/9 checks passed

session.sh

Agent session export functionality for sharing and replay:

session_export "claude-code" "session_id" "/output/path"
session_list                        # List exportable sessions
session_validate "/export/file.json"

Implements the Session Export Schema for cross-agent sharing:

interface SessionExport {
  schema_version: 1;
  exported_at: string;              // ISO8601
  session_id: string;
  agent: "claude-code" | "codex" | "agy";
  model: string;
  summary: string;
  duration_minutes: number;
  stats: {
    turns: number;
    files_created: number;
    files_modified: number;
    commands_run: number;
  };
  outcomes: Array<{
    type: "file_created" | "file_modified" | "command_run";
    path?: string;
    description: string;
  }>;
  key_prompts: string[];            // Notable prompts for learning
  sanitized_transcript: Array<{
    role: "user" | "assistant";
    content: string;
    timestamp: string;
  }>;
}

tailscale.sh

Zero-config VPN setup for secure remote access:

install_tailscale                   # Install via official APT repo
verify_tailscale                    # Check installation
tailscale_status                    # Get connection status

Tailscale provides:

• Secure mesh networking between your devices
• SSH over Tailscale for firewall-free access
• MagicDNS for hostname-based addressing
• ACL-based access control

After installation, run tailscale up to authenticate and join your tailnet.

ubuntu_upgrade.sh

Multi-reboot Ubuntu version upgrade automation:

start_ubuntu_upgrade                # Begin upgrade chain
check_upgrade_status                # Current upgrade state
resume_upgrade_after_reboot         # Continue after reboot

Handles the complex multi-step Ubuntu upgrade process:

1. Detects current version
2. Calculates upgrade path (e.g., 24.04 → 25.04 → 25.10)
3. Performs sequential do-release-upgrade operations
4. Installs systemd service for post-reboot resume
5. Continues ACFS installation after reaching target

MCP Agent Mail Integration

ACFS includes integration with MCP Agent Mail for multi-agent coordination:

What Agent Mail Provides

• Identities: Each agent registers with a unique name
• Inbox/Outbox: Message-based communication between agents
• File Reservations: Advisory leases to prevent agents from clobbering each other's work
• Searchable Threads: Full-text search across all messages
• Git Persistence: All artifacts stored in git for human auditability

Core Patterns

1. Register Identity:

# In your agent, call:
mcp.ensure_project(project_key="/data/projects/my-project")
mcp.register_agent(project_key=..., program="claude-code", model="opus-4.5")

2. Reserve Files Before Editing:

mcp.file_reservation_paths(
    project_key=...,
    agent_name="BlueLake",
    paths=["src/**"],
    ttl_seconds=3600,
    exclusive=true
)

3. Communicate:

mcp.send_message(
    project_key=...,
    sender_name="BlueLake",
    to=["GreenCastle"],
    subject="Review needed",
    body_md="Please review the auth changes..."
)

Macros for Speed

When speed matters more than fine-grained control:

mcp.macro_start_session(...)      # Ensure project + register + fetch inbox
mcp.macro_prepare_thread(...)     # Align with existing thread
mcp.macro_file_reservation_cycle(...)  # Reserve + work + release
mcp.macro_contact_handshake(...)  # Request contact permissions

Destructive Command Guard (dcg)

dcg is a high-performance Claude Code hook that blocks dangerous git and filesystem commands before they execute. Built in Rust for sub-millisecond latency, it provides mechanical enforcement of safety rules that instructions alone cannot guarantee.

Why dcg Exists

On December 17, 2025, an AI agent ran git checkout -- on files containing hours of uncommitted work from a parallel coding session. The files were recovered via git fsck --lost-found, but the incident made one thing clear: instructions in AGENTS.md don't prevent execution. dcg provides mechanical enforcement.

What Gets Blocked

What Gets Allowed

Safe variants are allowlisted:

• git checkout -b <branch> — Creates branch, doesn't touch files
• git restore --staged — Only unstages, doesn't discard
• git clean -n — Dry-run preview
• Temp directory cleanup still requires explicit human approval when an agent would delete files

Installation

acfs update --stack-only

Claude Code Configuration

Add to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "dcg"}]
      }
    ]
  }
}

Modular Pack System

dcg uses a modular pack system for extensibility. Enable additional packs in ~/.config/dcg/config.toml:

[packs]
enabled = [
    "database.postgresql",
    "containers.docker",
    "kubernetes",
]

Available packs: database.*, containers.*, kubernetes.*, cloud.*, infrastructure.*, system.*, package_managers.

Repo Updater (ru)

ru is a production-grade CLI tool for synchronizing collections of GitHub repositories and automating commit workflows across dirty repos with AI assistance.

Core Features

• Multi-repo sync: Clone missing repos, pull updates, detect conflicts
• Agent sweep: AI-driven commit automation across repositories with uncommitted changes
• AI code review: Orchestrate Claude Code review sessions for open issues/PRs
• Work-stealing queue: Parallel execution with load-balanced workers
• NTM integration: Session management via Named Tmux Manager

Quick Start

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh?ru_cb=$(date +%s)" | bash

Initialize configuration:

# Initialize configuration
ru init --example

# Sync all repositories
ru sync

# Check status without changes
ru status

Agent Sweep Workflow

The agent-sweep command automates commits across dirty repositories:

# Preview repos to process
ru agent-sweep --dry-run

# Full automation with AI
ru agent-sweep --parallel 4

# Include release automation
ru agent-sweep --with-release

Three-Phase Workflow:

1. Planning: Claude Code analyzes changes, generates commit message
2. Commit: Validates plan, stages files, runs quality gates
3. Release: (Optional) Creates version tag and GitHub release

Configuration

# ~/.config/ru/config
PROJECTS_DIR=/data/projects
LAYOUT=flat                   # flat|owner-repo|full
UPDATE_STRATEGY=ff-only       # ff-only|rebase|merge
PARALLEL=4

Repo list format (~/.config/ru/repos.d/public.txt):

owner/repo
owner/repo@develop            # Pin to branch
owner/repo as custom-name     # Custom directory name

Get Image from Internet Link (giil)

giil downloads full-resolution images from cloud photo shares to your terminal. Essential for remote debugging workflows where you need to analyze screenshots in SSH sessions.

Supported Platforms

Usage

# Basic download
giil "https://share.icloud.com/photos/02cD9okNHvVd-uuDnPCH3ZEEA"
# Output: /current/dir/icloud_20240115_143245.jpg

# Download to specific directory
giil "..." --output ~/Downloads

# Get JSON metadata
giil "..." --json

# Download all photos from album
giil "..." --all --output ~/album

Installation

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/giil/main/install.sh?v=3.0.0" | bash

Visual Debugging Workflow

1. Screenshot UI bug on iPhone
2. Wait for iCloud sync to Mac
3. Share via Photos.app → Copy iCloud Link
4. Paste link into remote terminal running Claude Code
5. giil fetches the image locally
6. AI assistant analyzes the screenshot

Chat Shared Conversation to File (csctf)

csctf converts public AI conversation share links into clean, searchable Markdown and HTML transcripts. Perfect for archiving AI conversations, building knowledge bases, and sharing with teams.

Supported Providers

Usage

# Basic conversion
csctf https://chatgpt.com/share/69343092-91ac-800b-996c-7552461b9b70
# Creates: <slug>.md and <slug>.html

# Markdown only
csctf "..." --md-only

# Publish to GitHub Pages
csctf "..." --publish-to-gh-pages --yes

# JSON metadata output
csctf "..." --json

Installation

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/chat_shared_conversation_to_file/main/install.sh | bash

Output Features

• Markdown: Clean formatting with preserved code blocks and language hints
• HTML: Zero-JavaScript static page with syntax highlighting
• Deterministic filenames: <slug>_YYYYMMDD.md for reliable archival
• Collision handling: Auto-increments suffix to avoid overwrites

CI/CD

ACFS uses GitHub Actions for continuous integration:

Installer Testing (installer.yml)

# Runs on every push and PR
jobs:
  shellcheck:
    - Lints all bash scripts with ShellCheck

  integration:
    - Matrix tests across Ubuntu 24.04, 25.04, 25.10
    - Runs full installation in Docker
    - Verifies all tools installed correctly
    - Runs acfs doctor to confirm health

  factory-e2e:
    - Runs the literal public curl|bash installer on QEMU/KVM or a fresh real Ubuntu host
    - Requires systemd, SSH, and a disposable factory VM/VPS semantics
    - Verifies ubuntu user creation, SSH key merge, user services, tool health, and idempotency

Docker catches shell and package regressions early. The factory E2E is the authoritative release gate for the real beginner VPS path because it exercises systemd, SSH, login/user-service behavior, and provider image defaults that containers cannot model. A Docker pass is not sufficient release proof by itself.

Local Release Doctor (scripts/release-doctor.sh)

Run the local release gate before tagging or publishing a release candidate:

bash scripts/release-doctor.sh --full --network=check
bash scripts/release-doctor.sh --json --full --network=check > release-doctor.json

For a fast local readiness check while developing:

bash scripts/release-doctor.sh --json

The release doctor composes the maintainer checks that are easy to forget:

• branch policy and clean worktree status
• shellcheck install.sh scripts/**/*.sh
• manifest/generated/checksum drift via scripts/check-manifest-drift.sh --json --quiet
• verified-installer checksum candidate review with --network=check
• website type-check, lint, and production build when apps/web changed or --full is set

The checksum candidate check uses the canonical updater output. If the generated body differs from checksums.yaml, review the diff before release; if only the timestamp header differs, leave checksums.yaml unchanged. The default --network=skip keeps routine runs offline, and --web=auto runs website checks only when web files changed unless --full or --web=always is provided.

Stack Provenance Report (scripts/stack-provenance-report.sh)

Use the stack provenance report when reviewing Dicklesworthstone stack tool freshness before release:

bash scripts/stack-provenance-report.sh --json
bash scripts/stack-provenance-report.sh --network=check --json

Offline mode reports local manifest/checksum consistency for stack tools. Network mode also checks GitHub latest release metadata and generates a checksum candidate without writing checksums.yaml. Changed stack installer hashes fail the report, unrelated checksum diffs are called out separately, and rch release changes are flagged as mandatory checksum-refresh review items.

Agent Readiness Audit (scripts/agent-readiness-audit.sh)

Run the local agent readiness audit before launching a swarm on a freshly installed VPS:

bash scripts/agent-readiness-audit.sh
bash scripts/agent-readiness-audit.sh --json

The audit checks Claude Code, Codex CLI, Antigravity CLI, and caam without printing token values or auth file contents. It reports CLI presence, version availability, parseable auth/config files, CAAM default profile consistency, and stale CAAM defaults that point at missing profiles.

Useful options:

bash scripts/agent-readiness-audit.sh --no-version  # Skip CLI --version probes
bash scripts/agent-readiness-audit.sh --home /home/ubuntu --path "$PATH"

Treat failures as launch blockers. Warnings usually mean the CLI is installed but needs a user sign-in or CAAM default profile selection.

Website Deployment (website.yml)

# Builds and deploys the Next.js wizard
jobs:
  build:
    - Type-check TypeScript
    - Run ESLint
    - Build production bundle

  deploy:
    - Deploy to Vercel (production)

Automated Checksum + Drift Repair (checksum-monitor.yml)

ACFS automatically monitors upstream installers for changes, and also repairs generated artifact checksum drift:

# Runs every 15 minutes + on upstream changes
schedule: "*/15 * * * *"
triggers:
  - Schedule (every 15 minutes)
  - Webhook from upstream repos (repository_dispatch)
  - Pushes touching installer/checksum/generator files

How It Works:

1. Verify Generated Artifact Drift: Runs scripts/check-manifest-drift.sh --json to detect:
   • ACFS_MANIFEST_SHA256 mismatches
   • internal script checksum drift (scripts/generated/internal_checksums.sh)
   • generated installer and web metadata drift via bun run generate:diff
   • semantic manifest contract drift across scripts/generated/doctor_checks.sh, apps/web/lib/generated, acfs/onboard/lessons, README snippets, and checksums.yaml
2. Auto-Repair Drift: If drift is detected, runs --fix (regenerate + commit + push)
3. Verify Current Upstream Checksums: Downloads all upstream installers, calculates SHA256
4. Detect Upstream Changes: Compares against checksums.yaml
5. Categorize Tools: Separates "trusted" tools (can auto-update) from others
6. Auto-Update Upstream Checksums: Commits updated checksums.yaml when safe
7. Alert: For non-trusted tool changes, creates GitHub issue for manual review

The monitor fails closed when verification returns fetch errors or skipped entries; it will not emit partial/placeholder checksum updates.

Trusted Tools (Auto-Update Enabled):

• Dicklesworthstone stack tools (ntm, cass, cm, ubs, slb, dcg, caam, bv, agent-mail, ru)
• These are maintained by the same author, so upstream changes are implicitly trusted

Non-Trusted Tools (Manual Review Required):

• Third-party installers (bun, uv, rust, oh-my-zsh, atuin, zoxide, nvm)
• Changes trigger a GitHub issue with diff details for human review

This ensures:

• Security: Third-party changes are reviewed before deployment
• Velocity: Internal tool updates are deployed automatically
• Auditability: All changes tracked via git commits

Upstream Repo Dispatch (Fast Path):

• ACFS-owned tool repos emit a repository_dispatch event (upstream-changed) when their install.sh changes or a release is published.
• Requires a PAT secret named ACFS_REPO_DISPATCH_TOKEN in each tool repo (repo scope for this org/user).
• If dispatch fails, the 15-minute scheduled monitor still catches drift (but slower).

Production Smoke Tests (production-smoke.yml)

Validates deployments on real environments:

# Runs after deployment
jobs:
  smoke:
    - Fetches install.sh from production URL
    - Verifies checksum matches repository
    - Validates shell syntax
    - Confirms no uncommitted drift

Installer Canary (Docker) (installer-canary.yml)

Runs the installer inside fresh Ubuntu containers on a daily schedule. This is a fast regression canary, not the final proof of the factory VPS path.

schedule: "30 7 * * *" # daily
jobs:
  canary:
    - Run tests/vm/test_install_ubuntu.sh (vibe mode)
    - Defaults to Ubuntu 25.10; --all covers 24.04, 25.04, and 25.10
    - Uses ACFS_CHECKSUMS_REF=main for freshest hashes

Factory Installer E2E (installer-factory-e2e.yml)

Runs the literal public installer through the authoritative factory harness. The QEMU/KVM backend uses the official Ubuntu cloud image and requires a runner with /dev/kvm; set the repository variable ACFS_FACTORY_RUNNER, the manual runner input, or client_payload.runner to a KVM-capable larger/self-hosted runner. The real-host backend runs against a disposable Ubuntu VPS over SSH and is intended for provider-specific sentinel runs.

schedule: "0 8 * * 0" # weekly QEMU/KVM factory canary when ACFS_FACTORY_RUNNER has /dev/kvm
workflow_dispatch:
  inputs:
    backend: qemu|real-host
    runner: "" # optional override; blank uses ACFS_FACTORY_RUNNER or ubuntu-latest
    ref: main
    mode: vibe
    expect_ubuntu: "25.10"
    expect_final_ubuntu: "25.10"
repository_dispatch:
  types: [acfs-factory-host-ready]
real-host secrets:
  ACFS_FACTORY_SSH_PRIVATE_KEY: private key for real-host backend
  ACFS_FACTORY_SSH_TARGET: optional fallback root@fresh-host for real-host backend

Standard GitHub-hosted runners do not provide a contractual nested-virtualization environment. If the QEMU backend runs without /dev/kvm, the workflow fails at the KVM preflight with an environment-specific error before invoking the installer.

Reusable workflow callers may use the QEMU backend without passing SSH secrets. The real-host backend still needs a private key plus either client_payload.ssh_target for dispatch runs or ACFS_FACTORY_SSH_TARGET as a fallback.

If backend=real-host is requested without those SSH credentials, the workflow fails during configuration resolution. It must never report a green canary when no disposable host was tested.

Workflow artifact directories and uploads include only the current GitHub run id and attempt. That keeps repeated scheduled/manual runs from reusing or uploading old QEMU overlay disks on KVM-capable self-hosted runners with persistent workspaces. The QEMU backend writes its generated private SSH key outside the repository checkout, so upload-artifact and future Git commits never package guest login credentials. Factory diagnostics are redacted before local upload, including installer logs and the remote diagnostic archive.

The target host must be freshly provisioned. By default the harness fails if the ubuntu user already exists before install, because the real beginner path must prove ACFS creates that user automatically. The harness also requires acfs doctor --json to report zero failures and zero warnings, then separately verifies Agent Mail liveness/systemd service state and the ACFS nightly user timer.

For the slower upgrade/resume gate, provision a fresh Ubuntu 24.04 host and run the same workflow or script with --expect-ubuntu 24.04 --expect-final-ubuntu 25.10 --allow-install-reboot.

For provider-specific real VPS sentinels, use an external provisioning job to create a disposable server, wait for root SSH, dispatch acfs-factory-host-ready, and destroy the server after artifact collection. The dispatch payload should include the fresh host address so the repository does not store a stale long-lived VPS as ACFS_FACTORY_SSH_TARGET:

{
  "event_type": "acfs-factory-host-ready",
  "client_payload": {
    "backend": "real-host",
    "ssh_target": "root@203.0.113.10",
    "ref": "main",
    "mode": "vibe",
    "expect_ubuntu": "25.10",
    "expect_final_ubuntu": "25.10"
  }
}

Local QEMU Factory E2E (test_factory_install_qemu.sh)

Runs the same factory-host harness inside a real local VM instead of a Docker container. The wrapper downloads and verifies the official Ubuntu cloud image, boots it with QEMU/KVM and cloud-init, exposes root SSH on a local forwarded port, then delegates to tests/vm/test_factory_install_ubuntu.sh. Generated private SSH keys are kept outside the repository checkout; use --key-dir with a path under /tmp or another non-repo directory when you need a specific local key location for debugging.

sudo apt-get install -y qemu-system-x86 qemu-utils cloud-image-utils openssh-client
./tests/vm/test_factory_install_qemu.sh

Use this when Docker passes but you need local proof for systemd, sshd, cloud-init, kernel, filesystem, and login behavior before spending time on a disposable provider VPS.

Playwright E2E Tests (playwright.yml)

Full browser testing of the wizard website:

# Runs on PR to main
browsers:
  - Chromium
  - Firefox
  - WebKit
  - Mobile Chrome
  - Mobile Safari

tests:
  - Wizard flow completion
  - Step navigation
  - Copy button functionality
  - Responsive design

VPS Providers

ACFS works on any Ubuntu VPS with SSH access and either root password login or a provider console that lets you become root for the first install. Here are recommended providers optimized for multi-agent workloads.

Why 48-64GB RAM? Each AI coding agent uses ~2GB RAM. To run 10-20+ agents simultaneously, you need 48GB+ RAM. Don't bottleneck a $400+/month AI investment to save $20 on hosting.

After installation, run acfs capacity --profile 25-agents --recommend-ntm on the VPS for a local RAM/CPU/disk sizing report with recommended agent counts and copyable NTM launch profiles.

Contabo (Best Value — Top Pick)

• Best specs-to-price ratio on the market
• Month-to-month pricing, no commitment required
• US datacenter pricing includes ~$10/month premium

OVH (Great Alternative)

• Anti-DDoS included
• Month-to-month, 5-15% discount for longer commitments
• Typically faster activation than Contabo

Requirements

Other Providers

Any provider with an Ubuntu VPS, SSH access, and a first-login root password or root console works. The wizard at agent-flywheel.com has step-by-step guides.

Provider Setup Guides

ACFS includes detailed step-by-step guides for each supported provider in scripts/providers/:

Each guide includes:

• Screenshots for every step (in scripts/providers/screenshots/)
• Pricing breakdowns with recommendations
• Region selection guidance (latency, privacy)
• Password-first login guidance and post-install SSH key recovery specific to that provider
• Troubleshooting for common provisioning issues

Provider Comparison:

Recommendation Flow:

1. Budget: Contabo (best specs per dollar)
2. Speed: Hetzner (instant provisioning)
3. Support: OVH (phone support available)
4. Privacy: Any EU provider (GDPR compliance)

Project Structure

agentic_coding_flywheel_setup/
├── README.md                     # This file
├── AGENTS.md                     # Development guidelines
├── VERSION                       # Current version (0.7.0)
├── install.sh                    # Main installer entry point
├── acfs.manifest.yaml            # Canonical tool manifest (510 lines)
├── checksums.yaml                # SHA256 hashes for upstream scripts
├── package.json                  # Root monorepo config
│
├── apps/
│   └── web/                      # Next.js 16 wizard website
│       ├── app/                  # App Router pages
│       │   ├── layout.tsx        # Root layout
│       │   ├── page.tsx          # Landing page
│       │   └── wizard/           # Wizard step pages
│       ├── components/           # UI components
│       └── lib/                  # Utilities
│
├── packages/
│   ├── manifest/                 # Manifest parser + generator
│   │   └── src/
│   │       ├── parser.ts         # YAML parsing
│   │       ├── schema.ts         # Zod validation schemas
│   │       ├── types.ts          # TypeScript types
│   │       ├── utils.ts          # Helper functions
│   │       └── generate.ts       # Script generator
│   └── onboard/                  # Onboard TUI source
│
├── acfs/                         # Files deployed to ~/.acfs/
│   ├── zsh/
│   │   └── acfs.zshrc            # Shell configuration
│   ├── tmux/
│   │   └── tmux.conf             # Tmux configuration
│   └── onboard/
│       ├── onboard.sh            # Onboarding TUI script
│       └── lessons/              # Tutorial markdown (11 files)
│
├── scripts/
│   ├── lib/                      # Installer bash libraries
│   │   ├── logging.sh            # Console output
│   │   ├── security.sh           # HTTPS + checksum verification
│   │   ├── os_detect.sh          # OS detection
│   │   ├── user.sh               # User management
│   │   ├── zsh.sh                # Shell setup
│   │   ├── update.sh             # Update command logic
│   │   ├── gum_ui.sh             # Enhanced UI
│   │   ├── cli_tools.sh          # Tool installation
│   │   └── doctor.sh             # Health checks
│   ├── generated/                # Auto-generated from manifest
│   │   ├── install_base.sh       # Base packages
│   │   ├── install_shell.sh      # Shell tools
│   │   ├── install_cli.sh        # CLI tools
│   │   ├── install_lang.sh       # Language runtimes
│   │   ├── install_agents.sh     # AI coding agents
│   │   ├── install_cloud.sh      # Cloud CLIs
│   │   ├── install_stack.sh      # Dicklesworthstone stack
│   │   ├── install_all.sh        # Top-level installer
│   │   └── doctor_checks.sh      # Verification checks
│   ├── providers/                # VPS provider guides
│   │   ├── ovh.md
│   │   ├── contabo.md
│   │   └── hetzner.md
│   └── sync/
│       └── sync_ntm_palette.sh   # Sync NTM command palette
│
├── .github/
│   └── workflows/
│       ├── installer.yml         # ShellCheck + Ubuntu matrix tests
│       └── website.yml           # Next.js build + deploy
│
└── tests/
    └── vm/
        ├── test_install_ubuntu.sh # Docker integration test
        ├── test_factory_install_ubuntu.sh # Real VM/VPS factory install test
        └── test_factory_install_qemu.sh # Local QEMU/KVM factory install test

Development

Website Development

cd apps/web
bun install           # Install dependencies
bun run dev           # Dev server at http://localhost:3000
bun run build         # Production build
bun run lint          # Lint check
bun run type-check    # TypeScript check

Manifest Development

cd packages/manifest
bun install           # Install dependencies
bun run generate      # Generate installer scripts
bun run generate:dry  # Preview without writing files

Installer Testing

# Local lint
shellcheck install.sh scripts/lib/*.sh

# Full installer integration test (Docker, same as CI)
./tests/vm/test_install_ubuntu.sh

# Authoritative factory-host E2E (requires a disposable fresh Ubuntu 25.10 VM/VPS)
./tests/vm/test_factory_install_ubuntu.sh --ssh-target root@203.0.113.10

# Local authoritative VM E2E (QEMU/KVM + official Ubuntu cloud image)
./tests/vm/test_factory_install_qemu.sh

# Slow real-host upgrade/resume gate from Ubuntu 24.04 to 25.10
./tests/vm/test_factory_install_ubuntu.sh --ssh-target root@203.0.113.10 --expect-ubuntu 24.04 --expect-final-ubuntu 25.10 --allow-install-reboot

Security Verification

# Print all upstream URLs
./scripts/lib/security.sh --print

# Verify all checksums
./scripts/lib/security.sh --verify

# Update checksums after reviewing upstream changes
./scripts/lib/security.sh --update-checksums > checksums.yaml

Manifest Validation

The manifest parser includes comprehensive validation beyond basic schema checking:

Validation Error Codes:

Running Validation:

cd packages/manifest
bun run validate              # Full validation
bun run validate --verbose    # Show all checks

Cycle Detection Algorithm:

Tarjan's strongly connected components (SCC):
1. DFS with discovery/low-link tracking
2. Identify SCCs with size > 1 as cycles
3. Report cycle path for human debugging

Test Harness

ACFS includes a comprehensive test harness (tests/vm/lib/test_harness.sh) for integration testing:

# Source the harness
source tests/vm/lib/test_harness.sh

# Initialize test suite
harness_init "ACFS Installation Tests"

# Create test sections
harness_section "Phase 1: Base Packages"

# Run commands with automatic logging
harness_run "Installing curl" apt install -y curl

# Assert results
harness_pass "curl installed successfully"
harness_fail "curl installation failed"
harness_skip "Skipping optional test"

# Generate summary
harness_summary  # Outputs: 15 passed, 0 failed, 2 skipped

Test Files:

Running Tests:

# Full Docker integration test
./tests/vm/test_install_ubuntu.sh

# Full Docker integration matrix
./tests/vm/test_install_ubuntu.sh --all

# Real factory-host integration test
./tests/vm/test_factory_install_ubuntu.sh --ssh-target root@203.0.113.10

# Local QEMU/KVM factory-host integration test
./tests/vm/test_factory_install_qemu.sh

# Real upgrade/resume integration test
./tests/vm/test_factory_install_ubuntu.sh --ssh-target root@203.0.113.10 --expect-ubuntu 24.04 --expect-final-ubuntu 25.10 --allow-install-reboot

# Selection logic tests
./tests/vm/selection_checks.sh

# Web E2E tests
./tests/web/run_e2e.sh

Sync Scripts

Sync scripts keep ACFS documentation aligned with upstream projects:

# Sync NTM command palette from upstream
./scripts/sync/sync_ntm_palette.sh

# Check if update available (without downloading)
./scripts/sync/sync_ntm_palette.sh --check

Current Sync Sources:

All sync scripts use the security library for HTTPS enforcement and content hashing.

Website Design System

The website uses a comprehensive design system (apps/web/lib/design-tokens.ts):

Color Tokens (OKLCH Color Space):

// Perceptually uniform colors
colors: {
  cyan:    "oklch(0.75 0.18 195)",   // Primary accent
  pink:    "oklch(0.7 0.2 330)",     // Secondary accent
  purple:  "oklch(0.65 0.18 290)",   // Tertiary
  success: "oklch(0.72 0.19 145)",   // Green
  warning: "oklch(0.78 0.16 75)",    // Yellow
  error:   "oklch(0.65 0.22 25)",    // Red
}

Shadow Tokens:

shadows: {
  cardHover: "0 20px 40px -12px oklch(0.75 0.18 195 / 0.15)",
  cardLifted: "0 25px 50px -12px oklch(0.75 0.18 195 / 0.2)",
  primaryGlow: "0 0 40px -8px oklch(0.75 0.18 195 / 0.3)",
}

Animation Presets:

animations: {
  hover: { scale: 1.02, transition: { duration: 0.2 } },
  tap: { scale: 0.98 },
  fadeIn: { opacity: [0, 1], transition: { duration: 0.3 } },
}

Accessibility:

• Reduced motion support via useReducedMotion hook
• Semantic HTML structure
• ARIA labels on interactive elements
• Keyboard navigation support

Requirements

• Runtime: Bun (not npm/yarn/pnpm)
• Node: Latest
• Shell: Bash 5+

FAQ

Why "Vibe Mode"?

Vibe mode is designed for throwaway VPS environments where velocity matters more than safety:

• Passwordless sudo eliminates friction
• Agent dangerous flags skip confirmation dialogs
• Pre-configured aliases for maximum speed

Never use vibe mode on production or shared systems.

Can I use this on my local machine?

ACFS is designed for fresh Ubuntu VPS instances. While you could run it locally:

• It may conflict with existing configurations
• It assumes root/sudo access
• It's not designed for macOS or Windows

For local development, use the individual tools directly.

What if the installer fails?

The installer is checkpointed. Simply re-run it:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh?$(date +%s)" | bash -s -- --yes --mode vibe

It will skip already-completed phases and resume where it left off.

How do I update tools?

Use the built-in update command:

acfs update                  # Update all standard components
acfs update --stack          # Include Dicklesworthstone stack
acfs update --agents-only    # Just update AI agents

How do I uninstall?

There's no uninstall script. To reset:

1. Delete the VPS instance
2. Create a new one
3. Run the installer fresh

This is intentional—ACFS is designed for ephemeral VPS environments.

Can I customize which tools are installed?

Currently, ACFS installs the full suite. Future versions will support:

• Manifest-based tool selection
• Interactive mode for choosing components
• Modular installation scripts

Why ACFS Exists

The Problem: The Agentic Coding Barrier

The rise of AI coding agents (Claude Code, Codex CLI, Antigravity CLI) has created a new paradigm in software development. These agents can write code, debug issues, and even architect solutions—but only if they have the right environment.

The barrier isn't the agents themselves. It's the hours of setup required to create an environment where agents can actually be productive:

┌────────────────────────────────────────────────────────────────────────────┐
│  TIME INVESTMENT WITHOUT ACFS                                               │
│                                                                              │
│  VPS Setup ..................... 30-60 min                                   │
│  Shell Configuration ........... 20-30 min                                   │
│  Language Runtimes ............. 30-45 min                                   │
│  Dev Tools ..................... 20-30 min                                   │
│  Agent Installation ............ 15-30 min                                   │
│  Agent Configuration ........... 20-40 min                                   │
│  Coordination Tools ............ 30-60 min                                   │
│  Troubleshooting ............... 30-120 min                                  │
│  ─────────────────────────────────────────                                   │
│  TOTAL: 3-7 hours (and that's if everything works)                          │
│                                                                              │
│  TIME INVESTMENT WITH ACFS                                                   │
│                                                                              │
│  Run one command ............... 25-30 min                                   │
│  ─────────────────────────────────────────                                   │
│  TOTAL: 30 minutes                                                           │
└────────────────────────────────────────────────────────────────────────────┘

ACFS eliminates this barrier entirely. One command, 30 minutes, fully configured.

The Deeper Problem: Beginners Can't Start

For experienced developers, the setup is tedious but doable. For beginners—the people who would benefit most from AI coding assistance—it's an insurmountable wall:

• What's SSH? How do I generate keys?
• What's a VPS? How do I rent one?
• What's a terminal? Which one should I use?
• How do I connect to a remote server?
• What are all these tools and why do I need them?

The wizard website at agent-flywheel.com solves this by providing:

1. Absolute beginner guidance — Explains every concept in plain English
2. OS-specific instructions — Detects Mac vs Windows, shows the right commands
3. Visual confirmations — Checkboxes for each step, copy buttons for commands
4. Troubleshooting help — Expandable sections for common problems
5. Progress persistence — Resume where you left off across browser sessions

The 10x Multiplier Effect

ACFS isn't just a collection of tools—it's a carefully curated system where each component amplifies the others. The value isn't additive; it's multiplicative.

Tool Synergy Model

                              ┌─────────────────┐
                              │   PRODUCTIVITY  │
                              │   MULTIPLIER    │
                              └────────┬────────┘
                                       │
         ┌─────────────────────────────┼─────────────────────────────┐
         │                             │                             │
         ▼                             ▼                             ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  ENVIRONMENT    │         │    AGENTS       │         │  COORDINATION   │
│  LAYER          │         │    LAYER        │         │  LAYER          │
├─────────────────┤         ├─────────────────┤         ├─────────────────┤
│ • zsh + p10k    │────────▶│ • Claude Code   │────────▶│ • Agent Mail    │
│ • tmux          │         │ • Codex CLI     │         │ • NTM           │
│ • Modern CLI    │         │ • Antigravity   │         │ • SLB + DCG     │
│ • Language VMs  │         │                 │         │ • Beads Viewer  │
└─────────────────┘         └─────────────────┘         └─────────────────┘
         │                             │                             │
         │    Each layer enables       │    Agents become more      │
         │    the next layer           │    powerful together       │
         └─────────────────────────────┴─────────────────────────────┘

Why These Specific Tools?

Every tool in ACFS earns its place through concrete productivity gains:

The Compounding Effect

A single agent with basic tooling is useful. Three agents with:

• A shared project structure
• Coordination via Agent Mail
• Orchestration via NTM
• Safety guardrails via SLB
• DCG guard hook (blocks destructive commands before execution)
• Task visibility via Beads

...can accomplish in one day what would take a solo developer a week.

Tip: run acfs services-setup to configure logins, and enable DCG for destructive-command protection.

This is the flywheel effect in action. Better tools → more capable agents → more code shipped → better understanding of what tools are needed → better tools.

Design Algorithms & Decisions

ACFS implements several algorithmic patterns that ensure reliability and maintainability.

Idempotency Algorithm

Every installation function follows the check-before-install pattern:

install_tool() {
    if command_exists "tool"; then
        log_success "tool already installed"
        return 0
    fi

    # ... installation logic ...

    if command_exists "tool"; then
        log_success "tool installed successfully"
        return 0
    else
        log_error "tool installation failed"
        return 1
    fi
}

This guarantees:

1. Safe re-runs — Running the installer twice doesn't break anything
2. Resume capability — Failures don't require starting over
3. Declarative intent — The end state is defined, not the transition

Checksum Verification Algorithm

The security system uses content-addressable verification:

┌─────────────────────────────────────────────────────────────────────────┐
│  VERIFICATION FLOW                                                       │
│                                                                          │
│  1. Download script to memory (not disk)                                 │
│  2. Calculate SHA256 of downloaded content                               │
│  3. Compare against stored hash in checksums.yaml                        │
│  4. If match → execute                                                   │
│  5. If mismatch → refuse execution, report discrepancy                   │
│                                                                          │
│  Key insight: We verify CONTENT, not just transport                      │
│  (HTTPS only protects the channel, not the content at source)            │
└─────────────────────────────────────────────────────────────────────────┘

Manifest-Driven Generation

The generator uses a template expansion pattern:

1. Parse — Read YAML manifest, validate with Zod schemas
2. Transform — Convert manifest entries to installation functions
3. Group — Organize by category (base, shell, cli, lang, agents, etc.)
4. Generate — Emit Bash scripts with consistent structure
5. Verify — Generate doctor checks from verification commands

This ensures the manifest is the single source of truth—no drift between documentation, installer, and verification.

Code Generator Architecture

The manifest generator (packages/manifest/src/generate.ts) is a sophisticated TypeScript program that transforms YAML into bash:

Input Processing:

// 1. Parse YAML with validation
const manifest = parseManifestFile(MANIFEST_PATH);  // Zod-validated

// 2. Load checksums for verified installers
const checksums = parseYaml(readFileSync(CHECKSUMS_PATH));

// 3. Topological sort for dependency order
const sorted = sortModulesByInstallOrder(manifest.modules);

Security-First Code Generation:

// Shell-safe quoting (prevents command injection)
function shellQuote(s: string): string {
  return `'${s.replace(/'/g, "'\\''")}'`;
}

// Allowlisted runners only (belt-and-suspenders)
const ALLOWED_RUNNERS = ['bash', 'sh'] as const;

// Verified installer pipe construction
function buildVerifiedInstallerPipe(module: Module, checksums: Checksums): string {
  // Generates: curl -fsSL "$URL" | verify_checksum "$SHA256" | bash
}

Output Structure:

scripts/generated/
├── install_base.sh        # Base system packages (apt)
├── install_users.sh       # User normalization (ubuntu user)
├── install_filesystem.sh  # Directory structure (/data/projects)
├── install_shell.sh       # zsh + oh-my-zsh + p10k
├── install_cli.sh         # ripgrep, tmux, fzf, lazygit, etc.
├── install_network.sh     # Tailscale
├── install_lang.sh        # bun, uv, rust, go
├── install_tools.sh       # ast-grep, atuin, zoxide
├── install_agents.sh      # claude, codex, agy
├── install_db.sh          # PostgreSQL 18, Vault
├── install_cloud.sh       # wrangler, supabase, vercel
├── install_stack.sh       # Dicklesworthstone 10-tool stack + utilities
├── install_acfs.sh        # ACFS config deployment
├── install_all.sh         # Orchestration helper
├── doctor_checks.sh       # Health verification
└── manifest_index.sh      # Module metadata arrays

Generated Script Structure:

#!/usr/bin/env bash
# AUTO-GENERATED FROM acfs.manifest.yaml - DO NOT EDIT

install_module_id() {
    acfs_require_contract "module.id"  # Validate environment

    if run_installed_check "module.id"; then
        log_step "module.id already installed"
        return 0
    fi

    set_phase "Installing module..."
    run_as_target_shell <<'HEREDOC'
        # Installation commands from manifest
    HEREDOC

    verify_module "module.id"  # Post-install checks
}

Regeneration:

cd packages/manifest
bun run generate           # Full regeneration
bun run generate:dry       # Preview without writing

Generated Manifest Index

The generator produces manifest_index.sh, a comprehensive bash metadata file that provides programmatic access to manifest data at runtime:

Associative Arrays:

# Module metadata lookup
declare -gA ACFS_MODULE_DESC
ACFS_MODULE_DESC["lang.bun"]="Bun JavaScript/TypeScript runtime"
ACFS_MODULE_DESC["agents.claude"]="Claude Code CLI agent"

# Phase mapping (determines install order)
declare -gA ACFS_MODULE_PHASE
ACFS_MODULE_PHASE["base.system"]="1"
ACFS_MODULE_PHASE["lang.bun"]="6"
ACFS_MODULE_PHASE["agents.claude"]="7"

# Dependency relationships (comma-separated)
declare -gA ACFS_MODULE_DEPS
ACFS_MODULE_DEPS["agents.codex"]="lang.bun"
ACFS_MODULE_DEPS["stack.mcp_agent_mail"]="lang.bun,lang.uv"

# Generated function name mapping
declare -gA ACFS_MODULE_FUNC
ACFS_MODULE_FUNC["lang.bun"]="install_lang_bun"

# Category grouping
declare -gA ACFS_MODULE_CATEGORY
ACFS_MODULE_CATEGORY["lang.bun"]="lang"

# Default inclusion in install
declare -gA ACFS_MODULE_DEFAULT
ACFS_MODULE_DEFAULT["lang.bun"]="1"
ACFS_MODULE_DEFAULT["db.postgres18"]="1"

Runtime Access Pattern:

# Iterate modules in deterministic install order
for module in "${ACFS_MODULES_IN_ORDER[@]}"; do
  [[ "${ACFS_MODULE_CATEGORY[$module]}" == "agents" ]] || continue
  printf '%s\n' "$module"
done

# Check if module is default-installed
[[ "${ACFS_MODULE_DEFAULT[tools.vault]:-1}" == "1" ]]

# Get installation phase
printf '%s\n' "${ACFS_MODULE_PHASE[stack.ntm]}"  # 9

Use Cases:

• acfs doctor queries module metadata for health checks
• install.sh --list-modules displays available modules
• --skip <module> validates module existence before skipping
• --only-phase <n|name> uses phase mapping for selective installs

The manifest index bridges the TypeScript generator with bash runtime, enabling sophisticated module selection logic while keeping the bash scripts simple.

Progressive Disclosure in the Wizard

The wizard website implements progressive disclosure for complexity management:

Level 1: Core instructions (visible by default)
├── Copy this command
├── Paste in terminal
└── Press Enter

Level 2: Troubleshooting (expandable)
├── "Permission denied" → fix instructions
├── "Command not found" → prerequisites
└── "Connection refused" → diagnostics

Level 3: Deep explanations (collapsible "Beginner Guide")
├── What is SSH?
├── What is a VPS?
├── Why these specific steps?
└── What happens under the hood?

This allows beginners to get deep context when needed, while experts can skip straight to the commands.

Multi-Agent Orchestration Model

ACFS is designed for multi-agent workflows where several AI coding agents work on the same project simultaneously.

The Coordination Problem

Without coordination, multiple agents cause chaos:

• File conflicts — Two agents edit the same file
• Duplicated work — Agents solve the same problem independently
• Communication gaps — No visibility into what others are doing
• Safety risks — Dangerous operations without oversight

The ACFS Solution Stack

┌───────────────────────────────────────────────────────────────────────────┐
│                         AGENT COORDINATION LAYER                           │
│                                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐       │
│  │ Agent Mail  │  │    NTM      │  │  SLB + DCG  │  │   Beads     │       │
│  │ (Messaging) │  │ (Sessions)  │  │ (Safety)    │  │ (Tasks)     │       │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘       │
│         │                │                │                │               │
│         │   ┌────────────┴────────────────┴────────────────┘               │
│         │   │                                                              │
│         ▼   ▼                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐ │
│  │                      FILE RESERVATION SYSTEM                          │ │
│  │                                                                        │ │
│  │  Agent A reserves: src/auth/**                                         │ │
│  │  Agent B reserves: src/api/**                                          │ │
│  │  Agent C reserves: tests/**                                            │ │
│  │                                                                        │ │
│  │  → No conflicts, parallel progress                                     │ │
│  └──────────────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────┘

Agent Communication Patterns

1. Direct Messaging (Agent Mail)

Agent A → Agent B: "I finished the auth module, ready for API integration"
Agent B → Agent A: "ACK, starting API integration with auth dependency"

2. Broadcast Updates (Thread Summaries)

Thread: "Sprint 23 Tasks"
├── Agent A: "Claimed user-registration feature"
├── Agent B: "Claimed api-endpoints feature"
├── Agent C: "Claimed test-coverage task"
└── All agents see project state

3. File Reservations (Conflict Prevention)

Agent A: reserve_paths(["src/auth/*"], exclusive=true, ttl=3600)
Agent B: reserve_paths(["src/auth/*"]) → CONFLICT: held by Agent A
Agent B: reserve_paths(["src/api/*"]) → GRANTED

The NTM Orchestration Pattern

Named Tmux Manager (NTM) enables the one-command swarm spawn:

# Spawn 10 agents, each in a named tmux window
ntm spawn \
  --count 10 \
  --prefix "agent-" \
  --command "claude --dangerously-skip-permissions"

Result:

tmux session: acfs-swarm
├── agent-1: Claude working on auth
├── agent-2: Claude working on api
├── agent-3: Claude working on tests
├── agent-4: Codex reviewing PRs
├── agent-5: Antigravity writing docs
└── ...

Dry-Run Swarm Simulation

Before launching any real swarm, ask ACFS for a queue-aware plan:

acfs swarm plan --agents 25 --profile balanced --workload standard

The planner reads the local swarm status and capacity model, incorporates RCH queue pressure, active tmux/NTM sessions, Beads in-progress counts, and host resource headroom, then prints a pass/warn/fail recommendation. It is advisory only: it does not launch agents, mutate Beads, send Agent Mail, force-release reservations, or run build commands. JSON output is available with --json, and fixture replay is available with --status-file.

For multi-host planning, keep a local redacted inventory at ~/.acfs/swarm/hosts.inventory.json:

acfs swarm inventory report
acfs swarm inventory validate --json
acfs swarm inventory export --format json --output inventory.redacted.json
acfs swarm inventory import --input inventory.redacted.json

The inventory commands are local and advisory. They read or write JSON files, preserve unknown fields for future versions, reject sensitive field names such as hostnames, IPs, keys, tokens, passwords, and home paths, and never SSH, launch NTM, run RU, send Agent Mail, mutate Beads, or change RCH config.

For each agent you plan to launch, generate a bounded startup packet from the selected Bead plus current repo instructions and bounded CM/CASS context:

acfs swarm packet --bead bd-1234 --agent-name BlueLake --role implementation
acfs swarm packet --json --bead bd-1234 --agent-name BlueLake

The packet is designed for NTM prompt injection. It prioritizes live AGENTS.md, README.md, Beads, and Agent Mail state over memory-derived hints, includes drift checks, and preserves exact bv --robot-*, br, Agent Mail MCP, rch exec --, and UBS workflow guidance. It is read-only: it does not claim work, reserve files, send messages, start agents, run builds, or edit generated files.

Before launching a large real swarm, ACFS can run an offline simulation of the control plane:

acfs swarm simulate

The default simulation runs 10, 25, and 50 logical-agent scenarios without launching tmux sessions, model CLIs, Beads mutations, Agent Mail writes, or local CPU-heavy builds. It writes artifacts for each scenario: generated launch plan, telemetry JSON, capacity/resource sample, timing, and pass/fail summary. Treat this as a local readiness harness, not a substitute for provider factory tests on real VPS hosts.

After one or more simulation runs, calibrate the static capacity assumptions against those local artifacts:

acfs swarm calibration --artifact-dir ~/.acfs/logs/swarm-simulations
acfs swarm calibration --json --artifact-dir ./swarm-artifacts --rch-file ./rch-timing.json

The calibration report is read-only. It classifies the local evidence as conservative, aligned, or too aggressive, handles missing or partial artifacts with warnings, and never changes capacity defaults, RCH state, NTM sessions, Beads, or Agent Mail.

Philosophy

The Flywheel

The "Agentic Coding Flywheel" is a virtuous cycle:

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│    Better Environment → More Agent Productivity →               │
│    More Code Written → Better Understanding →                   │
│    Better Prompts → Better Environment                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

ACFS kicks off this flywheel by providing the best possible starting environment for agentic coding.

Design Principles

1. Beginner-Friendly, Expert-Fast: The wizard guides beginners; the one-liner serves experts.

2. Vibe-First: Optimize for velocity in throwaway environments. Safety features exist in safe mode.

3. Idempotent: Re-run without fear. The installer handles already-installed tools gracefully.

4. Single Source of Truth: The manifest defines everything. Installer scripts are generated from it.

5. Security by Default: HTTPS enforcement, checksum verification, no blind curl | bash.

6. Modern Defaults: Latest versions, modern tools, optimal configurations out of the box.

The Vibe Coding Manifesto

"Vibe coding" isn't just a catchy name—it's a philosophy about how humans and AI should collaborate on software development.

What Is Vibe Coding?

Vibe coding is the practice of directing AI agents to write code while you focus on intent, architecture, and quality. Instead of typing every line yourself, you:

1. Describe what you want in natural language
2. Review and guide the agent's output
3. Iterate rapidly through multiple approaches
4. Ship faster while maintaining quality

The "vibe" comes from the flow state you enter when you're no longer fighting syntax, boilerplate, or implementation details—you're just vibing with your AI partner.

The Three Laws of Vibe Coding

1. Velocity Over Ceremony

Traditional development is ceremony-heavy: create branch, write tests first, implement, refactor, write docs, create PR, wait for review, merge, deploy. Each step has friction.

Vibe coding inverts this: ship fast, iterate faster. The AI handles boilerplate while you focus on the 10% that requires human judgment.

Traditional: Think → Plan → Implement → Test → Document → Ship
Vibe:        Describe → Generate → Verify → Ship → Iterate

2. Throwaway Environments Enable Boldness

The magic of vibe coding happens on ephemeral VPS instances. When your environment is disposable:

• You can experiment without fear
• Catastrophic failures are just "rebuild the VPS"
• Agents can have dangerous permissions (they can't break what's disposable)
• You focus on output, not on protecting your setup

This is why ACFS's "vibe mode" enables passwordless sudo and dangerous agent flags—on a $5/month throwaway VPS, there's nothing worth protecting.

3. Multi-Agent Is The Default

One agent is useful. Three agents working in parallel are transformative.

Vibe coding assumes you'll run multiple agents simultaneously:

• Claude for complex reasoning and architecture
• Codex for rapid prototyping and refactoring
• Antigravity for documentation and research

ACFS provides the coordination layer (Agent Mail, NTM, SLB) that makes this practical.

The Anti-Patterns

Vibe coding is NOT:

• Blindly accepting agent output without review
• Abandoning tests and quality standards
• Ignoring security on production systems
• Treating agents as replacements for understanding

The goal is augmented human judgment, not abdicated human judgment.

When NOT to Vibe Code

• Production systems with real users
• Security-critical infrastructure
• Anything involving credentials or secrets
• Long-running servers (use safe mode)
• Shared team environments (use coordination tools)

Vibe coding is for greenfield development, prototyping, experimentation, and learning. Use ACFS's safe mode for everything else.

State Machine & Checkpoint System

ACFS implements a robust checkpoint-based state machine that enables reliable resume-from-failure. This section explains how it works under the hood.

State File Format

Progress is tracked in ~/.acfs/state.json:

{
  "schema_version": 3,
  "started_at": "2024-12-21T10:30:00Z",
  "last_updated": "2024-12-21T10:45:23Z",
  "mode": "vibe",
  "completed_phases": ["user_setup", "filesystem", "shell_setup"],
  "current_phase": "cli_tools",
  "current_step": "Installing ripgrep",
  "failed_phase": null,
  "failed_step": null,
  "failed_error": null,
  "skipped_phases": [],
  "phase_timings": {
    "user_setup": 12,
    "filesystem": 8,
    "shell_setup": 145
  }
}

Phase State Transitions

Each phase goes through a defined state machine:

┌─────────────────────────────────────────────────────────────────────────────┐
│  PHASE STATE MACHINE                                                         │
│                                                                              │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐                             │
│  │ PENDING  │────▶│ RUNNING  │────▶│ COMPLETE │                             │
│  └──────────┘     └────┬─────┘     └──────────┘                             │
│       │                │                                                     │
│       │                ▼                                                     │
│       │          ┌──────────┐     ┌──────────┐                              │
│       │          │  FAILED  │────▶│  RETRY   │──┐                           │
│       │          └──────────┘     └──────────┘  │                           │
│       │                                ▲        │                           │
│       │                                └────────┘                           │
│       │                                                                      │
│       └──────────────────────▶┌──────────┐                                  │
│          (--skip flag)        │ SKIPPED  │                                  │
│                               └──────────┘                                  │
└─────────────────────────────────────────────────────────────────────────────┘

Resume Logic

When the installer runs, it follows this decision tree:

def should_run_phase(phase_id):
    state = load_state_file()

    if phase_id in state.completed_phases:
        return SKIP  # Already done

    if phase_id in state.skipped_phases:
        return SKIP  # User explicitly skipped

    if state.failed_phase == phase_id:
        if user_wants_retry():
            return RUN  # Retry failed phase
        else:
            return ABORT  # Don't continue past failure

    return RUN  # Normal execution