gearbox ⚙

npx-bootstrappable AI agent harness packager. Installs a self-improving AI agent harness into any repo.

npx @mhingston5/gearbox

The core value is a session eval flywheel — hook scripts capture what happens during every AI coding session, turn that into portable runtime records and eval summaries, and give the agent better repo-specific context over time. No cloud service, no subscription — just files checked into your repo.

What you get

• 🪝 Hook runtime assets — capture session events, run policy guards, synthesise markdown evals, and ship portable prompts
• 🛠 10 user-facing harness utilities and helper CLIs — health scoring, docs drift detection, convention drift gate, event log, config sync, skill validation, and portable path helpers
• 🎓 33 portable skills — domain-agnostic agent skills that work with any codebase
• ⚡ 7 agentic workflows — GitHub Actions for ongoing repo health automation
• 🔌 Platform adapters — correct config files for 6 AI coding platforms
• 📝 Durable memory contract — AGENTS.md plus a learning guide and durable memory reference docs

Requirements

• Node.js ≥ 20.12.1
• Git repository

Installation

npx @mhingston5/gearbox                                    # Interactive wizard (recommended)
npx @mhingston5/gearbox --yes                              # Non-interactive — accept all defaults
npx @mhingston5/gearbox --dry-run                          # Preview files that would be written, no changes
npx @mhingston5/gearbox --platforms copilot,claude         # Select specific platforms
npx @mhingston5/gearbox --skills-dir .agents/skills        # Set custom skills directory (default: .agents/skills)
npx @mhingston5/gearbox --help                             # Show all options

The wizard asks which platforms you use and where to put skills, then writes everything in one shot.

After installation

1. Check harness health:

   npm run gearbox:health

2. Commit the generated files — everything under .gearbox/, .agents/skills/, AGENTS.md, .github/agents/, docs/agents/, platform config files, and any generated symlinks belongs in version control:

   git add .gearbox/ AGENTS.md .github/agents/ docs/agents/ .github/copilot/ .claude/ .agents/
   git add CLAUDE.md .github/copilot-instructions.md GEMINI.md  # if present
   git add .claude/skills/ .github/skills/  # if present
   git commit -m "chore: install gearbox agent harness"

3. Configure gitleaks (optional but recommended) — gearbox's pre-tool-use hook uses gitleaks for secret scanning before every file write. Install it and add a .gitleaks.toml to your repo root. Without it the hook degrades gracefully (fail-open).

4. Compile the agentic workflows — if you have the gh CLI with the gh-aw extension:

   gh aw compile .github/workflows/gearbox-*.md

   This turns the Markdown workflow definitions into runnable GitHub Actions.

What gets installed

.gearbox/hooks/ — shared hook runtime assets

These run at key moments during AI coding sessions. Each platform maps its native hook system to this canonical event set, then invokes the backing runtime asset shown below.

Hook event	Backing asset	What it does
sessionStart	self-learning.mjs sessionStart	Loads prior context and prepares runtime state
userPromptSubmitted	self-learning.mjs userPromptSubmitted	Captures the evolving task/goal for later compaction and evaluation
preToolUse	gitleaks-check.sh + policy-guard.mjs	Secret scanning via gitleaks, policy guard
postToolUse	self-learning.mjs postToolUse	Logs tool usage and updates runtime artefacts
errorOccurred	self-learning.mjs errorOccurred	Logs error context for post-session analysis
preCompact	context-compact.mjs	Writes compact context before a session compaction step
sessionEnd	self-learning.mjs sessionEnd	Flushes the event log, writes a session record, and triggers markdown eval

The installed asset set also includes shared implementations such as self-learning.mjs, markdown-eval.mjs, context-compact.mjs, helper shell scripts, and portable prompt files under .gearbox/hooks/prompts/.

.gearbox/scripts/ — 10 user-facing harness utilities and helper CLIs

Script	What it does
harness-audit.mjs	Health scoring (0–100) across 5 install dimensions, plus an advisory 5-subsystem harness rubric; also runs preflight checks before harness operations
docs-drift-check.mjs	Detects documentation that has gone stale relative to code changes
convention-drift-gate.mjs	Enforces coding conventions; runs as a post-merge CI gate
event-log.mjs	Append-only structured event log used by hooks for session tracing
harness-config.mjs	Reads harness-config.json; single source of truth for retry limits, budget settings, and hook tuning
sync-agent-config.mjs	Manages cross-platform symlinks (CLAUDE.md, GEMINI.md, skills dirs) for instruction compatibility
validate-skill.mjs	Validates bundled SKILL.md files for frontmatter, structure, and basic safety issues
paths.mjs	Resolves portable config/worktree roots from repo guidance, local folders, or platform defaults
normalize-error.mjs	Normalizes unstable error text values (temp paths, GUIDs, dates, positions) for loop detection
tmpdir.mjs	Creates or previews scoped helper temp directories under the host temp root

common.mjs is also installed in .gearbox/scripts/ as a shared support module for these CLIs, but it is not intended to be called directly.

{skillsDir}/ — 33 portable skills

Skills are Markdown files (SKILL.md) that the agent reads when triggered. They encode workflows, checklists, and domain knowledge that the agent applies consistently across sessions. See Skills reference below.

.github/workflows/ — 7 agentic workflows

Workflow	Cadence	What it does
pr-retrospective	Per PR merge	Mines merged PRs for learnings; updates AGENTS.md
convention-drift	Weekly	Audits the whole repo for convention drift; opens issues
docs-freshness	Weekly	Checks docs against recent code changes; flags stale content
decisions-hygiene	Weekly	Reviews architectural decision records for staleness
ci-health	Daily	Monitors CI pass rates and flags flaky tests
consolidate-memory	Weekly	Merges mature session lessons into permanent agent memory
daily-workflow-updater	Daily	Keeps agentic workflow definitions up to date

Platform config files

See Supported platforms for the exact file paths written per platform.

Durable memory contract

• AGENTS.md — top-level durable memory for repo guardrails, architecture notes, and quick links
• docs/agents/learning-guide.md — concise routing guide for where new durable learnings should live
• docs/agents/progress.md — lightweight running log for work that spans multiple sessions
• docs/agents/session-handoff.md — restart context for the next session or reviewer
• docs/agents/clean-state-checklist.md — wrap-up checklist before you hand off or pause work
• .github/agents/decisions.md — long-lived technical or workflow decisions and invariants
• .github/agents/user-directives.md — explicit user preferences that should shape future sessions

AGENTS.md starts as a stub and links to the other files so the installed memory bootstrap is immediately navigable.

For the smallest useful multi-session pack, start with AGENTS.md, docs/agents/learning-guide.md, docs/agents/progress.md, docs/agents/session-handoff.md, and docs/agents/clean-state-checklist.md.

package.json scripts

Three utility scripts are added to your package.json:

npm run gearbox:health      # Run harness health check (0-100 score + advisory subsystem rubric)
npm run gearbox:audit       # Run preflight checks
npm run gearbox:check-docs  # Check for documentation drift

Supported platforms

Platform	Config file(s)	Notes
GitHub Copilot CLI	.github/copilot/hooks.json	Full hook coverage
Claude Code	.claude/settings.json	Full hook coverage
OpenAI Codex	~/.codex/config.json + ~/.codex/instructions.md	⚠ No errorOccurred hook; ⚠ no sessionEnd hook
Gemini CLI	.gemini/settings.json	⚠ No errorOccurred hook
opencode	opencode.ts plugin	⚠ sessionEnd partially mapped
pi.dev	pi-plugin.ts	Full hook coverage

You can install config for multiple platforms in one run. The --platforms flag accepts a comma-separated list: copilot, claude, codex, gemini, opencode, pi.

The eval flywheel

The central idea in gearbox is a feedback loop that makes the AI agent better at your specific repo over time:

Session runs
    ↓
Hook scripts fire (pre-tool-use, post-tool-use, session-end, …)
    ↓
Event log accumulates structured session data (.gearbox/hooks/.runtime/)
    ↓
session-end hook writes a reusable session record
    ↓
markdown-eval synthesises `.gearbox/hooks/.runtime/latest-eval.md`
    ↓
Durable learnings are consolidated into `AGENTS.md`, `.github/agents/`, and docs
    ↓
Agent reads improved instructions at start of next session
    ↓
Better outcomes → more learnings → cycle continues

The pr-retrospective agentic workflow runs an additional flywheel turn after every PR merge, mining the git history and review comments for durable patterns.

AGENTS.md is the living memory entry point. Keep the full durable memory contract in version control so agents can follow repo conventions, durable decisions, and explicit user preferences from session one.

Skills reference

33 portable, domain-agnostic skills. Drop them into any repo and they work without modification.

Process & quality

Skill	Description
brainstorming	Explores user intent, requirements and design before any implementation work
test-driven-development	Enforces failing-test-first discipline before writing implementation code
verification-before-completion	Runs verification commands and confirms output before any completion claim
systematic-debugging	Structured debugging protocol for any bug, test failure, or unexpected behaviour
receiving-code-review	Handles code review feedback with technical rigour, not performative agreement
requesting-code-review	Verifies work meets requirements before submitting for review
writing-plans	Produces multi-step implementation plans from specs before touching code
executing-plans	Executes written implementation plans with review checkpoints in a separate session

Agent architecture & meta-skills

Skill	Description
using-superpowers	Establishes how to find and use skills — invoke before any response
subagent-driven-development	Runs independent tasks as parallel sub-agents within the current session
dispatching-parallel-agents	Dispatches 2+ independent tasks to parallel agents
stuck-loop-detection	Detects when the agent is burning tokens without progress; escalates with a structured summary
agentic-eval	Patterns for evaluating and improving agent outputs: self-critique, evaluator-optimizer pipelines, LLM-as-judge

Code & architecture

Skill	Description
refactor	Surgical refactoring without behaviour change: extract functions, rename, eliminate smells
improve-codebase-architecture	Finds architectural improvement opportunities, deepens shallow modules, reduces tight coupling
tech-debt	Identifies, categorises, and prioritises technical debt
context-map	Maps all files relevant to a task before making changes
diff-triage	Classifies staged/unstaged changes by intent and risk without touching the index
adopt	Compares the current codebase with a reference project to identify high-value adaptations

Git & GitHub

Skill	Description
gh-cli	Comprehensive GitHub CLI reference for repos, issues, PRs, Actions, releases, and more
using-git-worktrees	Isolates feature work in a git worktree before implementing plans
finishing-a-development-branch	Guides completion of development work: merge, PR, or cleanup options
fix-merge-conflicts	Resolves git merge conflicts with guided categorisation and cleanup
ci-monitor	Watches PR CI, runs a bounded fix loop, and updates PR status

Documentation & knowledge

Skill	Description
documentation-writer	Expert technical writer following the Diátaxis framework (tutorials, how-tos, reference, explanation)
create-specification	Creates a specification file optimised for AI consumption
mermaid-diagrams	Creates software diagrams in Mermaid: class, sequence, flowchart, ER, C4, state, git graphs
memory-merger	Merges mature lessons from a domain memory file into its instruction file
session-lessons	Mines recent session history for evidence-backed recommendations
wrap-up	End-of-session reflection to surface learnings and persist them

Skill management

Skill	Description
skill-creator	Creates new skills or improves existing ones; tightens descriptions for reliable triggering
writing-skills	Creates, edits, and verifies skills before deployment
find-skills	Helps discover skills when asking about capabilities

License

MIT

---

gearbox is inspired by the agent harness patterns developed at PureGym and the obra/superpowers skill collection.