Agent Estate

Agent Estate

Perpetual autonomous work loop plugin for Claude Code. Turns Claude into an agent that works cycle after cycle, maintaining a persistent ledger across all sessions, never stopping until explicitly told to.

Overview

Agent Estate creates an infinite work loop by intercepting Claude's stop events via a shell hook. Each time Claude tries to exit, the hook blocks the exit, increments the cycle counter, and re-injects the prompt — creating a true perpetual agent.

Architecture

agent-estate/
├── .claude-plugin/plugin.json   # Plugin manifest (name, version, author)
├── commands/
│   ├── start.md                 # /agent-estate:start — activates the loop
│   ├── stop.md                  # /agent-estate:stop — removes state file to allow exit
│   └── status.md                # /agent-estate:status — shows cycle count, ledger summary
├── hooks/
│   ├── hooks.json               # Registers stop-hook.sh on the "Stop" event
│   └── stop-hook.sh             # Core engine: blocks exit, increments cycle, re-injects prompt
├── scripts/
│   └── setup-estate.sh          # Creates .claude/agent-estate.local.md state file
├── LICENSE
└── README.md

Key Components

Stop Hook (hooks/stop-hook.sh)

The core engine. Runs on every Claude "Stop" event:

• Checks if .claude/agent-estate.local.md exists (is the loop active?)
• If not active: exits normally (exit 0)
• If done (done: true in frontmatter): removes state file, exits normally (auto-stop)
• If active and not done:
• Detects rate limits (429) → waits 60s
• Detects API overload (529) → waits 30s
• Increments cycle counter in the state file
• Outputs a JSON {"decision": "block", "reason": "..."} to prevent exit
• Re-injects the prompt for the next cycle

Setup Script (scripts/setup-estate.sh)

Creates the state file at .claude/agent-estate.local.md with YAML frontmatter (active, cycle, started_at, user_prompt) and the full cycle protocol instructions. If already active, outputs current state and continues.

Ledger (.claude/agent-estate.md)

The persistent brain — every Claude session reads and updates it. Contains:

• Current Status — phase, focus, momentum, cycle count
• Session Log — what happened each session
• Worked Things — table of everything done with files touched
• Future Works — prioritized task queue
• More Works — ideas, discoveries, nice-to-haves
• Statistics — cycles, tests, bugs fixed, features shipped
• Tell The Next Claude — sacred handoff message for cross-context memory

State File (.claude/agent-estate.local.md)

Ephemeral file that signals an active loop. Contains the cycle counter and preserved user prompt. Removing this file (via /agent-estate:stop) is the only way to end the loop.

Commands

| Command | Description |

|---------|-------------|

| /agent-estate:start | Activate the loop in perpetual mode (no end condition) |

| /agent-estate:start <prompt> | Start perpetual mode with a specific task focus |

| /agent-estate:start --done <prompt> | Start in done mode — auto-stops when task is complete |

| /agent-estate:status | Show current cycle, mode, stats, and the latest handoff message |

| /agent-estate:stop | Manually remove the state file to stop the loop |

Work Priority Protocol

Built into the agent instructions, in order:

• Broken things — failing tests, bugs, errors
• Incomplete things — half-finished features, TODOs, FIXMEs
• Missing things — no tests, no error handling
• Ugly things — code smells, dead code
• Slow things — performance issues
• New things — features that improve the project
• Creative things — surprise the user

Cycle Protocol

Each cycle follows this pattern:

• Read .claude/agent-estate.md (the ledger)
• Decide what to work on next
• Do the work — write code, fix bugs, add features, run tests
• Update the ledger with what was done, discovered, and planned
• Update statistics, session log, and "Tell The Next Claude" handoff
• Immediately start the next cycle (never stop)

Prerequisites

• jq — required for JSON output in the stop hook
• Claude Code with plugin support

Installation

git clone https://github.com/MercuriusDream/agent-estate.git
mkdir -p ~/.claude/plugins/local
ln -s "$(pwd)/agent-estate" ~/.claude/plugins/local/agent-estate
chmod +x agent-estate/scripts/setup-estate.sh
chmod +x agent-estate/hooks/stop-hook.sh

Tips

• Long sessions: Claude Max recommended for extended autonomous runs
• Guiding prompts: Use /agent-estate:start <prompt> for focused work without being restrictive
• Ledger size: If it exceeds ~300KB, Claude will auto-summarize older cycles
• Resuming: The ledger persists after stop. Start again and Claude picks up from the handoff
• Full autonomy: No prompt = Claude explores and decides what's most valuable