agentic_coding_flywheel_setup Agent工作流

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.

Temp space: if TMPDIR (default /tmp) refuses a test write, because it is full or over a per-user tmpfs quota, acfs-update moves the run to the first of ACFS_UPDATE_TMPDIR, /data/tmp, /var/tmp and ~/.cache/acfs/tmp that accepts one. Verified installers are staged in a system directory instead of TMPDIR: /tmp, or /var/tmp when /tmp refuses the write.

Cloud agent environments

The public cloud agent setup guide selects the right recipe for your provider. Claude Code and ChatGPT / Codex have hosted test evidence; Amp Orbs, Devin and Grok Bot have documentation-based recipes awaiting hosted acceptance. Meta Muse needs shell/runtime and persistence checks before an installation recipe can be accepted. The installer retains its original filename and supports claude, codex and provider-neutral generic modes.

ChatGPT / Codex cloud environments

The same public bundles work in a Linux x86_64 Codex cloud environment. In Work in → Cloud, create or edit an environment and put this in its Install script:

#!/bin/bash
(
set -o pipefail
acfs_cloud_root="$(git rev-parse --show-toplevel)" || exit 1
acfs_cloud_setup="$(curl -q -fsSL --proto '=https' --proto-redir '=https' --connect-timeout 5 --max-time 20 -A 'acfs (+https://github.com/Dicklesworthstone/agentic_coding_flywheel_setup)' -H 'Accept-Encoding: identity' https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/scripts/claude-code-web-setup.sh)" || { printf '%s\n' 'ACFS cloud bootstrap download failed; tools were not installed. Check network access and retry.' >&2; exit 1; }
printf '%s\n' "$acfs_cloud_setup" | ACFS_CLOUD_SKILL_DIR="$acfs_cloud_root/.agents/skills/acfs-cloud-tools" ACFS_CLOUD_AGENT=codex ACFS_CLOUD_ROOT="$acfs_cloud_root/.acfs-cloud" bash || exit 1
acfs_cloud_exclude="$(git rev-parse --git-path info/exclude)" || exit 1
mkdir -p "$(dirname "$acfs_cloud_exclude")" || exit 1
printf '\n/.acfs-cloud/\n/.agents/skills/acfs-cloud-tools/\n' >> "$acfs_cloud_exclude"
) || exit 1

Enable internet access and add raw.githubusercontent.com and downloads.agent-flywheel.com to Additional allowed domains. These public downloads need no secrets or ownership of the tool repositories. The recipe installs into the writable repository workspace because hosted home/config paths can be read-only, and excludes its data directory through local Git metadata. It preserves HOME and CODEX_HOME. Review <repo>/.acfs-cloud/.acfs/cloud/setup.log, then Publish the prepared environment. After changing its setup, Republish for new tasks. See OpenAI's current cloud environment guide.

Save these instructions in the environment's Start skill and include them at the start of each new task. Our hosted checks reused all eleven executables but did not automatically load the saved Start skill or generated repository skill; explicitly loading the guide and setting PATH works:

Find the repository root with git rev-parse --show-toplevel.
Read <repo>/.acfs-cloud/.codex/AGENTS.md for the installed flywheel tools and <repo>/.acfs-cloud/.acfs/cloud/setup.log for failures.
In each task shell, run acfs_cloud_root="$(git rev-parse --show-toplevel)/.acfs-cloud"; export PATH="$acfs_cloud_root/.local/bin:$PATH" before using the tools.
Follow the guide's CASS_DATA_DIR, CASS_MEMORY_HOME and JFP_HOME exports in each task shell so search data, memory and prompt caches use the writable workspace; preserve existing overrides and keep any XDG_DATA_HOME/XDG_CONFIG_HOME writable.
Before using Agent Mail with a read-only HOME, follow the guide's command-scoped STORAGE_ROOT recipe; reuse existing configuration and preserve DATABASE_URL.
Before using JSM with a read-only HOME, follow the guide's command-scoped XDG recipe; reuse existing configuration and check skill installation targets separately.
Before using MS, follow the guide's local initialization and indexing steps in a writable project; reuse existing .ms/MS_ROOT/MS_CONFIG state.
Check br --version, bv --version, ubs --version and jsm --version before starting work.
Use br ready --json and bv --robot-triage; never open their interactive TUIs.

Codex mode preserves existing instructions outside its managed block. Without a custom root it uses $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md; a nonempty AGENTS.override.md takes precedence, so setup warns. The workspace recipe also creates .agents/skills/acfs-cloud-tools/SKILL.md in Codex's documented repository skill location; an existing skill at that path is preserved. Reading that skill loads the separate guide and configures PATH. Automatic hosted catalog discovery failed in our checks: a fresh task still omitted it after removing its Git exclusion, so changing exclusions is not a proven fix. Use the explicit startup instructions above. See OpenAI's instruction discovery rules. Agent Mail is available as a CLI; this setup does not configure or claim hosted MCP support. Local Codex MCP configuration and ChatGPT's remote MCP connections are different surfaces; see OpenAI's MCP guide.

If your UI instead has Setup script and Maintenance script, it uses the legacy environment workflow. Put the install command in Setup script; avoid reinstalling in Maintenance script on every cached resume. Configure task-phase internet separately if tools need online access after setup.

Verification boundary: both installer modes are tested on Ubuntu 24.04, including real public downloads. On 2026-10-08, a fresh Claude-hosted Full session pinned to 4a0e6bfa792ce73ad4c69847755ecd64384288c2 installed all ten tools in 12 seconds; all eleven versions passed, the guide loaded automatically, and Agent Mail's stdio MCP health check passed. On 2026-10-09, a cold default-Trusted Claude session pinned to 31c8180860f9ed461d9843d6ed298939a5b3ea74 installed all ten tools through public fallbacks in 53 seconds; all eleven versions, automatic instructions and actual Agent Mail MCP health passed. That run's first UBS helper download failed TLS; its release-hash-verified recovery was tested separately. The later complete UBS fallback removes that lazy module download, but has not been rerun in that hosted session. Codex hosted installation took 6 seconds at 140a845d; fresh published tasks reused all eleven executables, including after the repository-skill update at 4bdbf5a7. A task that explicitly loaded the guide configured PATH and passed all eleven probes. Automatic Codex skill loading remains open. These times describe the pinned earlier recipes, not a fresh hosted acceptance of later changes. The script reports individual failures but exits zero; successful session startup alone does not prove every tool installed. Default UBS exit 0 can include warnings; inspect its report or use --ci --fail-on-warning for a warning-strict check.

Optional Ubuntu Release Upgrade

A no-flags install keeps supported Ubuntu 22.04 and 24.04 LTS hosts on their current release. Non-root users with sudo and Ubuntu 24.04 Docker/WSL environments can install ACFS without opting into an OS upgrade.

Pass --target-ubuntu=26.04 to explicitly request an upgrade to Ubuntu 26.04 LTS. An OS upgrade requires a root-run installer on a host that can reboot; it is separate from installing or updating the ACFS tools.

How it works: 1. Detects your current Ubuntu version 2. Calculates a supported upgrade path (e.g., 24.04 → 26.04 LTS) 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 - Multiple LTS hops take longer; the path must be offered by Ubuntu's stable release upgrader - SSH sessions disconnect during reboots (reconnect to monitor)

To explicitly request the 26.04 LTS upgrade:

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

To suppress an explicit upgrade request:

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

--skip-ubuntu-upgrade wins regardless of flag order. Neither this flag nor an ordinary no-target install bypasses an active system upgrade checkpoint: normal installation remains blocked until the unfinished upgrade is resolved. Inspect the checkpoint and resume logs before retrying; keep the recovery state intact.

Monitoring upgrade progress: ```bash

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

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