This repository provides code examples for building robust, long-running Claude agents. It addresses the need for structured execution beyond simple prompts, enabling agents to reliably track progress, verify work with evidence, and resume sessions cleanly. Aimed at developers creating complex, persistent agent applications, it offers primitives to enhance reliability and observability.

How It Works

The core of the project lies in three primitives forming a quality loop:

1. Default-FAIL Contract: Enforces that agent tasks must be validated by observable evidence before completion. Shell hooks gate tool use and file writes, preventing self-declaration of success without proof.
2. Fresh-Context Evaluator: A separate, tool-limited subagent reviews completed work (diffs, screenshots) from a clean context window, mitigating bias from the builder's execution history.
3. Agent-Maintained Handoff: Agents autonomously manage session continuity by writing progress notes to structured files (e.g., PROGRESS.md) and committing to Git, ensuring seamless restarts and a traceable history.

Quick Start & Requirements

To integrate, clone the repo and copy claude-code-config/.claude to your project root. Ensure hook scripts are executable (chmod +x). Run claude from the directory containing .claude. Prerequisites include a Claude Code environment and shell access. Links to detailed pattern descriptions are in the README.

Highlighted Details

• Primitives are standalone files for easy cherry-picking.
• Shell hooks map directly to Agent SDK PreToolUse and Stop callbacks.
• Includes operator control hooks (kill-switch.sh, steer.sh) for mid-run human intervention.
• Provides examples for live monitoring via watch commands on progress files, Git logs, and evidence captures.

Maintenance & Community

This project is explicitly marked as an "event demo; not maintained and not accepting contributions." No community links or roadmap are provided.

Licensing & Compatibility

The repository's license is not specified in the provided README text, a critical omission for due diligence. Compatibility focuses on Claude Code and the Agent SDK.

Limitations & Caveats

The project offers example ingredients, not a turnkey solution. Its "not maintained" status means no updates or bug fixes are expected. Users must adapt configuration files (e.g., RESULTS_FILE) and ensure correct execution context. Advanced patterns like custom rubrics or browser evaluation are referenced but not implemented. The absence of a specified license poses a significant adoption risk.