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:

copy

# 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:

   copy

   ./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 [email protected]

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.

…view the full README on GitHub.