@nullmesh/abide

abide ⚖️

A working agreement your AI agent actually keeps.

Coding agents do things you never agreed to — push to main, rm the wrong directory, edit files outside the repo. The usual answer is a rules file (AGENTS.md, .cursorrules) the model is asked nicely to follow and quietly ignores.

abide is the agreement your agent keeps. You write the rules once, in plain language; abide enforces them where the tool can block (a Claude Code hook that actually stops or asks), and compiles them everywhere else (AGENTS.md, CLAUDE.md) so they travel with you. When you correct the agent, the correction becomes a durable rule.

npx @nullmesh/abide init      # a sensible agreement, good on day one
npx @nullmesh/abide install   # wire it into Claude Code (the enforcing hook)

That's it. The next time the agent tries something you ruled out:

⛔ We agreed: no pushes straight to main — open a PR instead.  [abide:no-push-main]

Why it's different

• It enforces, it doesn't just advise. Rules with deny/ask become a real Claude Code PreToolUse hook that blocks or prompts — not prose the model can skip.
• Declare once, works everywhere. One abide.yaml compiles to the enforcing hook and to AGENTS.md/CLAUDE.md for tools that only read. Switch tools without re-litigating the rules.
• Good on day one. abide init ships a curated agreement (no force-push, ask before pushing, stay in the repo), not an empty file you have to fill in.
• It learns. abide learn "never touch migrations without asking" turns a correction into a durable, version-controlled rule.
• Local-first, zero network, fail-open. The hook never phones home and never blocks your agent because of its own error.

Usage

abide init [solo|oss|team]     # scaffold abide.yaml (default: solo)
abide install [--global]       # register the Claude Code hook + /abide skill
abide learn '<rule>'           # record a rule  [--deny|--ask] [--command '<glob>'] [--tool <name>]
abide compile                  # regenerate AGENTS.md + CLAUDE.md from abide.yaml
abide check '<cmd>'            # show what abide would decide for a command
abide uninstall [--global]     # remove the hook + skill

The agreement (abide.yaml)

The single source of truth — readable enough to commit and review:

version: 1
project: my-project

roles:
  agent: Implements changes, writes tests, proposes plans before large edits.
  human: Reviews and approves; owns releases and anything published.

rules:
  - id: ask-before-push
    description: Ask before pushing — don't push without a confirmation.
    match: { tool: Bash, command: ["git push*"] }
    action: ask           # deny | ask | allow

  - id: stay-in-project
    description: Don't edit files outside the project directory.
    match: { tool: [Edit, Write, MultiEdit], pathOutsideProject: true }
    action: deny

conventions:               # advisory only — compiled into AGENTS.md/CLAUDE.md
  - Match the style of the surrounding code.
  - Report failing tests as failing.

earned: []                 # rules that accrue from `abide learn`

How it works

abide.yaml  ──compile──►  AGENTS.md / CLAUDE.md   (advisory: every tool reads it)
            ──install──►  Claude Code PreToolUse  (enforced: deny / ask / allow)

Before the agent runs a tool call, the hook reads it, matches it against your rules (first match wins), and returns allow / ask / deny. Commands match by glob; file edits can match pathOutsideProject. Anything unmatched is allowed.

Install options

• npm: npm i -g @nullmesh/abide
• Claude Code plugin: /plugin marketplace add nullmesh/abide
• Cross-agent skill: npx skills add nullmesh/abide --skill abide

Honest limitations

• A PreToolUse hook is defense-in-depth, not a security boundary. It raises the floor against an agent doing the wrong thing by habit; it is not a sandbox. For untrusted execution, pair it with OS-level isolation.
• Enforcement (block/ask) only happens in tools that support hooks (Claude Code today). Elsewhere the same rules ship as advisory AGENTS.md/CLAUDE.md — "declare everywhere, enforce where you can."

License

MIT — see LICENSE. Part of nullmesh.