bridle

The problem

GOOD  nightly-20260728T053205Z-349e54
      harness v1.2.0 (2c35307e6bac) · agent claude-sonnet-5
      5 events · 0 escalation(s)

When to reach for it

• Your agents run for hours, not minutes

  Long-running and overnight agents are exactly where implicit, in-your-head policy falls apart. Write the policy once; audit it forever.

• You need to explain a run afterwards

  Every event carries the run ID, the agent, the harness version and a hash of the harness file — if someone edits the policy mid-run, the trace shows it.

• You already have AGENTS.md and skills

  Bridle is the layer above, not a replacement. Your orchestrator — Claude Code, LangGraph, cron + scripts — stays the runtime. Bridle hands it a script.

• You want CI to enforce the process

  The linter exits 1 on a broken harness. A ready-made GitHub Action lints every harness on every PR.

What you get · the four pillars

• 1 · Run Charter

  What a good run observably looks like: the Plan → Act → Evaluate loop, budgets, and which sub-agents may exist.

• 2 · Trace Contract

  Which events — tool calls, code edits, DB writes, API hits — must be logged, where, and how they tie back to a run ID and harness version.

• 3 · Skill Lattice

  Which skills, tagged cheap/frontier and safe/risky, may be used in which phase. Planning never writes. Evaluation uses different eyes.

• 4 · Governance Lane

  What auto-merges, what needs a PR and a human, what's forbidden, and how a run gets rolled back. Your VCS is the control plane.

• + Recovery & Escalation

  A per-run progress log and resume protocol so a restarted agent never redoes finished work — and explicit triggers for stopping and calling a human.

• Three tiers, start small

  lint --tier 1 holds you to just the Charter. One honest tier-1 harness beats four aspirational ones. Move up when it stops being a lie.

Install · adopt in 30 minutes

1. Install it

   Node 18+. Install from GitHub — the bare name bridle on npm belongs to an unrelated package, so always go through the repo.

   npm install -g github:manpreet171/bridle

   Prefer not to install anything? Every command below also works as npx github:manpreet171/bridle <command>.

2. Scaffold the harness

   bridle init

   your-project/
   ├── AGENTS.md      # project OS (skipped if you have one)
   ├── HARNESS.md     # ★ the Harness Script — fill in its sections
   ├── prompts/       # AI-written plans, human-approved
   ├── skills/        # tool know-how, tagged with cost/trust bands
   └── logs/          # append-only run traces (JSON Lines)

3. Fill it in, then lint it

   The linter refuses a harness missing any pillar for your tier. Exit 1 — CI-friendly.

   bridle lint

4. Run under it

   bridle run start nightly --agent claude-sonnet-5
   bridle run log tool_call --detail '{"tool":"oxylabs","status":"ok"}'
   bridle run log check_pass --phase evaluate
   bridle run end good
   bridle status

   Recent runs:
   
     GOOD  nightly-20260728T053205Z-349e54
           harness v1.2.0 (2c35307e6bac) · agent claude-sonnet-5 · 5 events · 0 escalation(s)

Written down, not locked down: Bridle never sits between your agent and its work. No server, no daemon, no API key — if you delete the CLI tomorrow, your HARNESS.md is still a useful document your agents read.

Source & docs

The manifesto, the pillar deep-dive, the 30-minute adoption guide, real example harnesses and the trace JSON schema live in the repository. MIT licensed.