What Is the GUPP Principle and How Does It Ensure Agent Autonomy?

The Gas Town Universal Propulsion Principle (GUPP) mandates that every agent must immediately execute any work placed on its Hook bead, establishing a pull-based, crash-surviving execution model that eliminates central orchestration.

The GUPP principle is the foundational design rule of the gastownhall/gastown framework. Defined formally in docs/glossary.md, it governs how autonomous agents—such as Polecats, Crews, and Dogs—discover and process tasks without external scheduling. This principle directly enables Gastown to sustain 20-30 parallel agents where conversation-based frameworks typically stall at 3-5 agents.

What Is the GUPP Principle?

The GUPP principle is succinctly expressed as:

"If there is work on your Hook, YOU MUST RUN IT."

In the Gastown architecture, every agent owns a pinned Hook bead that functions as its personal work-queue. When components like Slings, Watchers, or the Mayor place a Bead on that Hook, the GUPP rule forces the agent to begin processing immediately. This is enforced by the session-start hook that automatically runs gt prime --hook as soon as an agent’s tmux pane is created.

Unlike traditional push-based systems where a central scheduler dispatches tasks, Gastown uses a pull-based model. The agent continuously polls its Hook bead via gt prime, triggering execution only when work appears. This mechanism is embedded in templates/polecat-CLAUDE.md, which includes the recovery instruction: "Run gt prime after compaction" to ensure the GUPP hook fires on every session restart.

How GUPP Ensures Agent Autonomy

The GUPP principle guarantees autonomy through three specific architectural characteristics:

Self-Driving Execution

The agent never waits for an external prompt. By continuously polling its Hook bead, it becomes self-driving—detecting new work autonomously and entering its execution loop without coordination overhead. As implemented in the source code, the gt prime --hook command expands the role template, reads the Hook bead, and immediately invokes the next step of the molecule.

Crash Resilience

GUPP is crash-surviving by design. If a session terminates unexpectedly, the Hook bead remains pinned to the agent’s state. When the tmux session restarts, the same gt prime --hook invocation rediscovers the pending work, allowing the agent to resume exactly where it left off. This durability ensures that no task is lost due to process failure.

Scalable Coordination

Because each agent runs as an independent process with its own Hook, adding agents does not increase coordination overhead. The GUPP model eliminates the need for a central scheduler to "push" work, removing the bottleneck that constrains traditional multi-agent frameworks. According to docs/research/w-gc-004-agent-framework-survey.md, this architecture is why Gastown achieves linear scalability while others encounter coordination collapse.

GUPP Implementation in Practice

The following examples demonstrate how GUPP operates within the Gastown runtime.

Placing Work on a Hook

To dispatch work to an agent named "alice," you use the Sling command:

# Put a new work bead on the polecat's pinned Hook

gt sling alice --bead sg-abc123

This writes a Bead to alice’s Hook bead. The next time alice’s session starts or polls, the GUPP hook triggers immediate execution.

Session Activation

When an agent’s tmux pane initializes, the Deamon automatically invokes:

# Inside the agent's tmux pane (run automatically on startup)

gt prime --hook

This command checks the Hook bead for pending work. If work exists, the agent fires its execution loop; if the Hook is empty, the agent idles efficiently until new work arrives.

Violation Detection

The Deacon daemon monitors for stalled agents that violate the GUPP principle:

# Check if Hook bead shows no progress for 30 minutes

if gt check-hook alice --stalled 30m; then
  gt nudge witness "GUPP_VIOLATION: alice"
fi

When detected, the Witness component intervenes to reset the bead or re-dispatch the work, maintaining the health of the autonomous loop.

Violation Handling and Lifecycle Management

The docs/design/polecat-lifecycle-patrol.md specifies that a GUPP violation occurs when an agent shows no progress on its Hook bead for a defined timeout period. In this case, the Witness remediation protocol activates—either restarting the agent or migrating the work to another Polecat.

Additionally, docs/design/polecat-self-managed-completion.md analyzes how GUPP improves throughput by freeing Polecats immediately upon task completion. Because agents pull new work autonomously rather than waiting for central dispatch, they transition to new tasks faster than in managed-queue architectures.

Summary

• The GUPP principle requires agents to execute any work found on their Hook bead immediately, enforced by the gt prime --hook command.
• Agent autonomy is achieved through self-driving polling, crash-resilient state persistence, and scalable decentralization.
• Work enters the system via gt sling, while violations are detected by gt check-hook and remediated by the Witness.
• This architecture supports 20-30 parallel agents without coordination bottlenecks, as documented in the framework's research surveys.

Frequently Asked Questions

What does GUPP stand for in the Gastown framework?

GUPP stands for Gas Town Universal Propulsion Principle. It is formally defined in docs/glossary.md as the core rule that agents must run any work present on their Hook bead without external prompting.

How does GUPP differ from traditional push-based scheduling?

Traditional frameworks use a central scheduler to push tasks to agents, creating a coordination bottleneck. GUPP uses a pull-based model where agents independently poll their Hook beads via gt prime, eliminating the need for central dispatch and enabling higher parallelism.

What happens when an agent violates the GUPP principle?

When an agent fails to progress on its Hook bead for a timeout period (typically 30 minutes), the Deacon daemon detects the stall using gt check-hook and notifies the Witness. The Witness then triggers remediation, either resetting the agent or re-dispatching the work, as detailed in docs/design/polecat-lifecycle-patrol.md.

How does GUPP enable scaling to 20-30 parallel agents?

By removing the central scheduler and allowing agents to autonomously discover work through their pinned Hook beads, GUPP eliminates the coordination overhead that limits traditional frameworks. According to docs/research/w-gc-004-agent-framework-survey.md, this decentralized approach allows Gastown to linearly scale while conversation-based architectures stall at 3-5 agents due to synchronization constraints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}