Agentic Coding Flywheel Setup: Building an OS for AI

Fixed in commit 01f5bd47 ('fix: address installer issues #157-#165, #169'). Please update to the latest version.

— Dicklesworthstone

The Junior Developer with Root Access

Giving a large language model raw terminal access is like handing root privileges to an eager but highly amnesic junior developer. The agent might brilliantly refactor a complex function, then immediately hallucinate a non-existent package manager, switch arbitrarily from bun to npm, or delete a critical configuration file because it looked "unused."

This is the fundamental control problem of agentic coding. Most tools attempt to solve it by building better prompts or wrapping the agent in a restrictive sandbox. The Agentic Coding Flywheel Setup (ACFS) takes a different approach: it treats the AI as a first-class citizen of the operating system.

Drafting a Constitution for AI

ACFS controls agent behavior through system-level constraints. At the root of every project lies AGENTS.md, a foundational document that acts as a constitution. It establishes hard rules: the human is always in charge, file deletion is strictly forbidden, and specific package managers must be used.

But rules are only useful if enforced. ACFS implements an Ultimate Bug Scanner (UBS) through shell hooks. Every time an agent attempts to save a file, a script intercepts the action.

#!/bin/bash
# .claude/hooks/on-file-write.sh
# Triggers static analysis before the agent's write completes
if ! ./scripts/lib/ubs-scan.sh "$1"; then
  echo "ERROR: UBS scan failed. Fix syntax before proceeding."
  exit 1
fi

This barrier forces the agent to fix its own syntax errors and hallucinated variables before the save operation even finishes. It transforms the filesystem itself into a strict supervisor.

Bootstrapping the Cockpit

Building this environment manually is tedious and error-prone. ACFS automates the process using a declarative manifest (acfs.manifest.yaml). This single source of truth defines a multi-phase installation pipeline mapping system dependencies, user normalization, and shell configurations.

Because installing dozens of upstream binaries is inherently brittle, the ACFS installer is strictly idempotent. A specialized "Doctor" verification subsystem constantly checks the health of the 30+ installed tools, ensuring they are not just present, but correctly authenticated, networked, and running under the appropriate user privileges.

Stringing Beads to Prevent Context Collapse

Even in a perfect environment, an LLM's context window eventually collapses under the weight of sprawling requirements. ACFS mitigates this using a methodology called "Beads."

Instead of referencing massive Jira tickets, work is chunked into atomic, self-contained state files stored in a .beads/ directory. Each bead carries its own specific metadata, context, and success criteria—optimized explicitly for machine reading rather than human project management.

The Missing Middle of Agentic DevTools

While the broader ecosystem focuses on either the prompt interface or full-blown autonomous IDEs, ACFS targets the underlying infrastructure layer.

Vibe Mode and the Velocity Trade-off

Ultimately, ACFS is an opinionated tool prioritizing developer velocity over traditional, restrictive security paradigms. This is most evident in "Vibe Mode," a configuration state that explicitly enables passwordless sudo and bypasses standard safety prompts.

The philosophy is simple: if you want an AI to act autonomously, you have to give it the keys to the machine. By shifting the safety mechanisms from permission prompts to automated file-write hooks and idempotent recovery scripts, ACFS allows the agent to move at the speed of thought without permanently bricking the server.

Sources: Agentic Coding Flywheel Setup Repository; Vibe Sparking Blog.