agentic_coding_flywheel_setup Agent工作流

Agentic Coding Flywheel Setup (ACFS)

<p align="center"> <strong>🌐 <a href="https://agent-flywheel.com">agent-flywheel.com</a></strong> — Interactive setup wizard for beginners </p>

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

Quick Install

{ acfs_installer="$(curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh")" || acfs_installer="$(curl -fsSL "https://cdn.jsdelivr.net/gh/Dicklesworthstone/agentic_coding_flywheel_setup@main/install.sh")"; } && printf '%s\n' "$acfs_installer" | bash -s -- --yes --mode vibe

[!NOTE] raw.githubusercontent.com is listed first deliberately. jsDelivr caches a mutable @main reference, so it can serve an installer that is hours or days behind the repository. When that happens the stale installer's bootstrap extraction list does not match the current checksum ledger and the install fails with INTEGRITY: <file> missing — a failure that looks like a repository defect but is purely a CDN cache artifact. Keeping the authoritative source primary and the CDN as fallback preserves the resilience without that failure mode. Please do not reorder these. Each download is buffered before execution so a failed request cannot concatenate a partial installer with the fallback response.

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.9.0)
> curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/v0.9.0/install.sh" | bash -s -- --yes --mode vibe --ref v0.9.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.

---

it empty and every verified installer would fail closed.

./scripts/lib/security.sh --update-checksums > /tmp/acfs-checksums.candidate.yaml diff -u checksums.yaml /tmp/acfs-checksums.candidate.yaml # Review what changed cp /tmp/acfs-checksums.candidate.yaml checksums.yaml git commit -m "chore: update upstream checksums" ```

The Installer

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

Installer Modes

Installation Phases

Claude Code Settings Written at Install

The installer provisions a few keys in ~/.claude/settings.json, always merging non-destructively (a value you have already set is never overridden):

Post-Install Verification and Rollback

Before a verified installer replaces a tool binary, the previous binary is retained at <binary>.prev. After the install, a smoke check probes the fresh binary with a per-tool argument (update_tool_smoke_probe in scripts/lib/update.sh: fsfs version, mdwb --help, pfr --help) or, for tools without an entry, the chain --version → --help → version. Every probe is headless-safe and runs with stdin detached under a 20 s ceiling. Verdicts:

- healthy — a probe exited 0. - unsupported — every probe was rejected as an unknown argument (usage error). The binary ran, so it is kept and logged as POST-INSTALL VERIFICATION UNAVAILABLE; no rollback, no backoff. - broken — a probe timed out, could not execute, died by signal, or failed without a usage-style rejection (crash, traceback, missing runtime). The previous binary is restored atomically and the failure is recorded in ~/.local/state/acfs/update-rollback.state so nightly runs back off instead of reinstalling the same broken release every night.

acfs doctor reports rolled back tools; acfs-update --force retries immediately.

acfs-update exit codes distinguish partial from total failure: 0 all succeeded, 1 total failure (nothing updated), 2 partial failure (some tools updated, some failed).

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 installer-cache build` — Verified Installer Entrypoint Cache

Build a portable acfs-installer-cache/ directory containing the checksum-pinned upstream installer scripts selected from acfs.manifest.yaml. On Ubuntu, pass either that directory or its parent to a later installation:

acfs installer-cache build --output /mnt/acfs-cache
./install.sh --yes --verified-installer-cache /mnt/acfs-cache

Explicit cache selection is fail-closed: if a required cached entrypoint is missing, stale, malformed, for another Ubuntu/architecture target, or does not match the current manifest and checksums.yaml, ACFS refuses it instead of fetching that entrypoint live.

This is not a complete offline installer. The cached entrypoint scripts still need network access for release archives, package registries, Git repositories, APT packages, and other transitive payloads. The initial ACFS bootstrap is also separate; use --bootstrap-archive for that layer. The roadmap below retains full pre-downloaded package bundles as future work.

`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 /.

Usage

Full vibe mode (recommended for throwaway VPS):

{ acfs_installer="$(curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh")" || acfs_installer="$(curl -fsSL "https://cdn.jsdelivr.net/gh/Dicklesworthstone/agentic_coding_flywheel_setup@main/install.sh")"; } && printf '%s\n' "$acfs_installer" | 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

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 or incomplete install into a git checkout

--bootstrap-self-update replaces ACFS repository files with origin/main. Copy local files elsewhere or commit local edits before opting in. Routine updates leave non-git and incomplete Git installs untouched.

The control-plane boundary: with --no-self-update (the shipped nightly timer's default), automated runs update your stack tools but never ACFS itself -- neither the git checkout nor the deployed runtime copies under ~/.acfs (bin/acfs, bin/acfs-update, scripts/lib/*.sh). The control plane therefore needs its own periodic refresh: run acfs-update without --no-self-update from time to time, or git pull --rebase the checkout and then run acfs-update --shell-only to redeploy the runtime copies. acfs doctor warns (updates.runtime_skew) when the checkout and the deployed runtime disagree, so a stack kept current by the nightly cannot silently outrun a stale dispatcher.

`acfs agents` — Flywheel Agent Guide

ACFS generates a machine-wide agent guide (installed tools with live versions, workflows, safety rules). The guide lives only in ACFS-owned storage, and ACFS refreshes it there on install/update:

~/.acfs/docs/flywheel-agent-guide.md    # canonical, freely regenerated by ACFS
~/.acfs/docs/AGENTS.workspace.md        # workspace AGENTS.md template (canonical copy)

ACFS never automatically writes /AGENTS.md, ~/.codex/AGENTS.md, or a project's AGENTS.md — those files can contain user-authored rules and belong to you. (/data/projects/AGENTS.md is seeded once on a fresh install only when absent, and is never overwritten afterward.) Deploying the guide into a real instruction surface is an explicit step:

acfs agents update                       # regenerate the canonical guide
acfs agents path                         # print the canonical path
acfs agents install --codex-global       # deploy to ~/.codex/AGENTS.md (Codex global scope)
acfs agents install --project DIR        # deploy to DIR/AGENTS.md (project scope)
acfs agents install --workspace          # deploy to /data/projects/AGENTS.md
acfs agents install --root               # deploy to /AGENTS.md (legacy; not auto-discovered)
acfs agents install --to PATH            # deploy anywhere else

Deployment creates the destination only when it is absent. If the destination already exists with different content, the deploy refuses, leaves your file untouched, and writes a merge candidate next to it (<dest>.acfs-new) so you can diff and merge manually. Redeploying identical content is an idempotent no-op.

Discovery scopes worth knowing: Codex reads global guidance from ~/.codex/AGENTS.md and project guidance from the project root down to the working directory; filesystem-root /AGENTS.md is not automatically read by any major harness, which is exactly why ACFS no longer writes it.

Tool detection always runs in the target user's context (including under sudo, resolved via SUDO_USER with ~/.local/bin, ~/go/bin, etc. on PATH), so user-local tools are reported accurately.

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 Agent Flywheel stack tools (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)

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 agents update           # Regenerate the flywheel agent guide (ACFS-owned)
acfs agents install --help   # Explicitly deploy the guide (never overwrites)
acfs update                  # Update all tools
acfs holds                   # List per-tool version holds (acfs hold/unhold to manage)
acfs services status         # Check Agent Mail, CM, and CASS daemons
acfs services-setup          # Configure agent credentials
acfs continue                # View upgrade progress after reboot
acfs installer-cache build   # Cache checksum-pinned installer entrypoints

Command Reference

The Command Reference documents every installed tool:

Components

---

The Generator Pipeline

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

1. Category Libraries (scripts/generated/install_base.sh, install_agents.sh, etc.) - One source-only file per category with private module functions - Consistent logging and error handling - Verification checks after each module - Direct execution fails closed because a single category cannot satisfy cross-category dependencies

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. Generated Harness (scripts/generated/install_all.sh) - Sources all category libraries - Invokes private module functions in global dependency order - Sourceable generated-module harness; direct execution refuses because it omits orchestration-owned modules and production dispatcher semantics

4. Runtime Data (scripts/generated/manifest_index.sh, internal_checksums.sh) - Deterministic module/category/generated-ownership metadata - Closed-grammar schema-1 digests for checksum-controlled runtime scripts

Note: Production install.sh is the only supported installation entry point. It sources the category libraries and dispatches their private functions through its phase runner; it does not call install_all.sh.

To regenerate after manifest changes:

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

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 tooltip system (apps/web/components/jargon.tsx) that adapts to the pointer type:

Desktop behavior: - Hover or keyboard focus reveals a floating definition card, rendered through a portal so it escapes stacking contexts - Viewport-aware positioning (auto-flips when near edges) - A short close delay so the pointer can travel into the card

Mobile behavior: - Tap opens a bottom sheet (apps/web/components/ui/bottom-sheet.tsx, framer-motion) with the full definition - Swipe-to-dismiss from the handle, Escape and backdrop dismissal, focus returned to the term - Body scroll locked while open and restored on close

Visual features: - Dotted primary-colored underline marks a term as interactive - Reduced-motion users get fades instead of slides - Colors come from the OKLCH design 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