@loop-eng/kit

Create production-ready agent loops in 30 seconds — zero to loop with one command.

The Problem

Setting up a production-quality agent loop takes 30-60 minutes per project: reading docs, writing hooks, configuring budget caps, wiring up state tracking. Most developers either skip this (and get runaway loops) or copy-paste from prior projects (and accumulate drift).

The Solution

npx @loop-eng/kit init

Five questions. Six files. Production-ready loop.

 ┌ @loop-eng/kit v0.1
│
◇ What's the task?
│ Fix all TypeScript errors in src/
│
◇ How do you verify success?
│ ● Test suite (npx vitest run)
│
◇ Budget cap?
│ ● $20 (feature work)
│
◇ Which agent?
│ ● Claude Code
│
◇ Iteration limit?
│ ● 10 (standard)
│
◆ Files created
│ ✓ CLAUDE.md
│ ✓ .claude/hooks/verify.sh
│ ✓ .loop/goal.md
│ ✓ .loop/budget.yaml
│ ✓ .loop/ltf.config.yaml
│ ✓ .loop/state.md
│
└ Run claude to start your loop

Features

Feature	Description
Interactive wizard	Clack-powered prompts — 5 questions, beautiful UI
Auto-detection	Detects stack (TS/JS/Python/Go/Rust), test runner, installed agents
Cross-agent support	Generates configs for Claude Code, Codex CLI, Gemini CLI, Cursor
Template library	6 built-in templates for common tasks
Verification gates	Auto-generates hook scripts that enforce pass/fail
Budget enforcement	Cost caps, iteration limits, convergence criteria
LTF integration	Every loop emits LTF traces by default
Loop readiness score	kit score rates your loop setup 0-100
Loop status	kit status shows progress from LTF traces

Installation

# Use directly with npx (no install needed)
npx @loop-eng/kit init
# Or install globally
npm install -g @loop-eng/kit

Commands

kit init — Scaffold a loop

kit init # Interactive wizard
kit init --template fix-types # Use a specific template
kit init --yes # Accept all defaults (non-interactive)
kit init --dir ./my-project # Target a specific directory

kit templates — Browse templates

kit templates # List all templates
kit templates --search security # Search by name or tag

Built-in templates:

Template	Task	Verification
fix-types	Fix TypeScript errors	tsc --noEmit
fix-lint	Fix linting errors	eslint --max-warnings=0
add-tests	Add test coverage	npm test
migrate-api	Migrate deprecated APIs	Build + tests
dependency-update	Update outdated deps	Full test suite
security-audit	Fix vulnerabilities	npm audit

kit score — Rate loop readiness

kit score # Score current project
kit score --dir ./my-project # Score a specific directory

Checks for: agent config, goal definition, verification gate, budget config, state tracking, LTF config, stack detection, test runner, installed agents, convergence criteria.

kit status — Show loop progress

kit status # Show loop status
kit status --dir ./my-project # Status for a specific directory

Shows: current iteration, loop state, budget remaining, LTF trace summary (cost, tokens, duration).

Generated Files

project/
├── CLAUDE.md # Loop instructions for the agent
├── .claude/
│ └── hooks/
│ └── verify.sh # Verification gate script
├── .loop/
│ ├── goal.md # Goal definition
│ ├── state.md # Loop state tracking
│ ├── budget.yaml # Budget caps + convergence criteria
│ └── ltf.config.yaml # LTF trace emission config
└── .gitignore # Updated with .loop/state.md

Budget Configuration

budget:
max_cost_usd: 20max_iterations: 10max_duration_minutes: 60verification:
command: npm testmust_pass: trueretry_on_fail: trueconvergence:
stall_iterations: 3# Stop if no progress for 3 iterationssame_error_threshold: 2# Stop if same error repeats 2xltf:
enabled: trueoutput: .loop/trace.ltf.jsonl

Auto-Detection

Kit auto-detects your project to provide intelligent defaults:

Detected	Source	Default Verification
TypeScript	tsconfig.json	tsc --noEmit
Vitest	vitest.config.*	npx vitest run
Jest	jest.config.*	npx jest
Pytest	pyproject.toml[tool.pytest]	pytest
Go	go.mod	go test ./...
ESLint	eslint.config.*	npx eslint .
Ruff	ruff.toml	ruff check .

Architecture

src/
├── cli/ # Commander-based CLI commands
├── detectors/ # Auto-detect stack, test runner, agents
├── generators/ # Generate CLAUDE.md, hooks, budget, goal, LTF config
├── templates/ # Template registry and loader
└── utils/ # File system and git helpers

Competitive Landscape

Feature	kit	loop-init	spec-kit	claude-code-templates
Interactive wizard	✓ (Clack)	✗	✗	✗
Loop-specific output	✓	✓	✗	✗
Cross-agent support	✓ (4 agents)	Partial	✓	Claude only
LTF integration	✓	✗	✗	✗
Verification gates	Generated	Scored	Manual	Manual
Budget enforcement	Generated	Estimated	✗	✗
Template ecosystem	✓ (6 built-in)	7 patterns	3 templates	600+

Development

npm install # Install dependencies
npm run build # Build with tsup
npm run typecheck # Type check
npm run lint # Lint with ESLint
npm run test# Run tests with vitest
bash demo/trial.sh # Run interactive demo
bash demo/test_e2e.sh # Run E2E test suite

Part of the Loop Engineering Ecosystem

• loopguard — Runtime guardian for AI agent loops
• ltf — Loop Trace Format specification and parsers
• loopctl — htop for AI agent sessions
• kit — Loop scaffolding CLI (this project)

License

MIT