LoopKit

Long-running agent work should survive the session.

LoopKit is a portable agent operations kit for long-running software work. It helps coding agents keep goals, permissions, decisions, work state, routing, and handoffs intact across sessions, tools, and harnesses.

It is not a new agent runtime, wire protocol, or replacement for Spec Kit, OpenSpec, Superpowers, GSD, Agent OS, MCP, A2A, or Agent Skills. LoopKit uses those ecosystems where they are already strong and adds the missing operator layer around them.

Position

LoopKit owns:

• session continuity
• explicit operator permissions
• durable handoffs
• capability and host routing
• reuse-before-build reconnaissance
• scoped context with explicit show/hide controls
• script-issued route checklists
• executable state checks
• completion evidence

LoopKit borrows or integrates:

• spec-first workflows from Spec Kit and OpenSpec
• skill packaging from Agent Skills
• subagent and hook patterns from Claude Code, Codex, and Superpowers
• context and fresh-loop discipline from GSD and Ralph
• standards capture ideas from Agent OS
• runtime/tool interoperability from MCP and A2A

Core Loop

1. intake - capture the goal, constraints, current state, and permissions.
2. context - reveal only the context needed for the loop.
3. recon - look for existing code, standards, skills, tools, and prior art.
4. route - choose the harness, skills, plugins, tools, and workstreams.
5. plan - make a small, verifiable plan with completion evidence.
6. execute - do the work in bounded loops.
7. verify - run checks and record proof.
8. handoff - leave the next operator enough state to resume cold.

Layout

• AGENTS.md - portable instructions for coding agents.
• .loopkit/goal.md - active goal and completion evidence.
• .loopkit/state.md - current project/session state.
• .loopkit/permissions.yaml - operator authority and approval rules.
• .loopkit/decisions.md - durable decision log.
• .loopkit/handoff.md - cold-start handoff.
• .loopkit/routing.yaml - host, harness, skill, and tool routing policy.
• .loopkit/context/index.json - context manifest.
• .loopkit/context/active.json - currently visible context profile.
• .loopkit/context/active.md - tiny always-visible context capsule.
• docs/prior-art.md - what to borrow, adapt, or avoid.
• docs/concept-map.md - legacy terms mapped to LoopKit terms.
• docs/context-architecture.md - scoped context and context budgets.
• .loopkit/routes/default-loop.json - deterministic route checklist.
• scripts/loopkit.py - portable route, check, context, status, and validation CLI.

Commands

LoopKit uses Python standard-library scripts as the canonical executable surface:

python scripts/loopkit.py doctor
python scripts/loopkit.py init
python scripts/loopkit.py intake
python scripts/loopkit.py next
python scripts/loopkit.py record --step intake --evidence active_goal --note "Goal and boundaries confirmed"
python scripts/loopkit.py context list
python scripts/loopkit.py check --route default-loop
python scripts/loopkit.py validate

The interactive intake asks plain-language questions up front. Agents can use the same command non-interactively with explicit flags, then follow one script-issued step at a time.

Install for your harness

python scripts/loopkit.py install --target auto --scope user

Then start a fresh agent session and say:

Set up LoopKit for this project and task.

The agent should initialize the project, translate your request into completion conditions and permission boundaries, ask one consolidated set of questions for material gaps, and guide the work one verified step at a time. You do not need to learn LoopKit's files or command vocabulary.

Explicit targets are codex, claude-code, cursor, opencode, gemini-cli, and generic. See docs/distribution.md for native packaging and Windows invocation details.

Status

Version 0.2 adds guided intake, current-run evidence, deterministic next-step instructions, project initialization, host diagnostics, cross-platform installation, and thin native packages for popular agent harnesses.