AgentRelay

Coding agents often lose track of complex tasks when context windows fill up or sessions expire. You end up paying for the agent to re-explore the codebase and re-verify work it already did.

AgentRelay solves this by maintaining durable, token-efficient checkpoints that capture the objective, implemented changes, verified tests, and the exact next step. It ensures that any successor agent—whether in a new session or a different tool—can resume work immediately without retracing the entire conversation.

What it does

• State Checkpointing records task objectives, code maps, and implementation progress in a predictable .agent-state directory.
• Session Continuity allows agents to pick up exactly where a previous session ended by reading a concise ACTIVE.md index.
• Verification Tracking logs specific test results and commands so new agents don't waste tokens re-running successful checks.
• Decision Journaling captures non-obvious technical choices and failed approaches to prevent the agent from repeating mistakes.
• Handoff Optimization formats instructions for the next agent to answer what is done, what is true, and what to do next.

How it works

1. Initialize the task by creating a .agent-state structure and defining the objective.
2. Checkpoint progress at meaningful boundaries, such as after a successful implementation or a passing test suite.
3. Verify workspace facts upon resuming a session to ensure the checkpoint matches the current repository HEAD and dirty files.
4. Handoff by generating a final CHECKPOINT.md that summarizes the work and identifies remaining limitations for the user.

Frameworks & tools

This skill is compatible with SKILL.md-aware agents including Claude Code, Codex, and Cursor. It uses standard Markdown for state files and requires no external APIs or paid dependencies beyond the agent itself.

Why this beats prompting it yourself

Manual handoffs are inconsistent and often forgotten when context runs low. Relay provides a rigorous hierarchy for verifying workspace state and prevents agents from hallucinating that previous notes are higher-priority than current user instructions.

Use cases

• Resume complex refactors after reaching context-window limits.
• Move a task from a CLI-based agent to a VS Code-based agent.
• Track progress across multiple days or team members without re-explaining goals.
• Maintain a persistent log of architectural decisions made during a feature build.

Known limitations

Does not automate git commits or pushes. Requires local file read/write access. Effectiveness depends on the agent's ability to follow startup instructions and update files at milestones.