apprval.md human approval for agent actions

npm install -g approval-md

git clone https://github.com/approval-md/approval.md && cd approval.md && npm ci && npm run build && npm link

An action travels from the agent, stops at the gate until a tap on the phone approves it, then continues to the world, while an autonomous read action passes straight through.

1. Install.

   npm install -g approval-md

   Copy

   Node 20 or newer.

2. Scaffold. In your project:

   approval init

   Copy

   Writes APPROVAL.md and an empty .approval/.

3. Configure your APPROVAL.md.

   Specify agent autonomy across classes of actions.

   { autonomy: autonomous } # actions flow freely through the gate { autonomy: supervised-retro } # actions flow, a sample is reviewed afterwards { autonomy: supervised-live, live_rate: 0.01 } # a declared fraction pauses at the gate for approval { autonomy: manual } # every action pauses at the gate for approval { autonomy: human-only } # the human performs the action; agents cannot request it

   Add human values to inform agent judgement across the gate. Specify what you love, like, dislike, and how you give feedback.

   An APPROVAL.md file being typed into a terminal: a yaml approval-policy block giving each class of action an autonomy level, and a yaml approval-values block stating what the operator loves, dislikes and wants.

   APPROVAL.md

   # Approval Policy
   
   Agents working here handle my life admin. Anything that
   leaves the machine is declared below.
   
   ```yaml approval-policy
   version: "0.1"
   defaults: { autonomy: manual, channel: telegram }
   approvers:
     alice: { channels: [telegram, cli] }
   classes:
     read.*:                    { autonomy: autonomous }
     files.write.workspace:     { autonomy: autonomous }
     vcs.push.main:             { autonomy: supervised-live, live_rate: 0.1 }
     communicate.email.external: { autonomy: manual, approvers: [alice] }
     financial.spend:           { autonomy: manual, limits: { per_action_usd: 25 } }
     account.credential:        { autonomy: human-only }
   ```
   
   ```yaml approval-values
   version: "0.2"
   love:    [honest thoughts on the work, small diffs with one idea]
   like:    [success reported first, say when you are stuck]
   dislike: [confident documentation that is stale]
   communication: "I read the journal after a session and react on the samples."
   ```

4. Sign it.

   approval setup identity
   approval policy attest --as human:<you>

   Copy

   The gate only functions while the latest policy has been attested.

5. Turn it on.

   eval "$(approval env)"
   approval up

   Copy

   Run approval setup channel telegram first if you want the tap on your phone.

6. Harness-agnostic. Put the gate in front of whichever agent you run.

   Each one classifies every shell command and file edit against your policy.

   • Claude Code: a PreToolUse hook in .claude/settings.json running approval hook claude-code.
   • Cursor: a preToolUse hook in .cursor/hooks.json running approval hook cursor, with failClosed: true.
   • Claude Agent SDK: a HookMatcher that pipes the event to approval hook claude-code.
   • Any MCP client: approval mcp serve.
   • Codex: approval codex prepare writes the config templates; native enforcement is still experimental.

7. Release your approved agents.

   Tweak your APPROVAL.md to find good human-agent harmony: loosen the gate for some actions, tighten it for others, re-attest, keep going.

   An agent sends an email: the message is held at the gate, a tap approves it, it lands in the inbox as delivered, and two lines appear in the log.

   agent

   inbox

   Deposit chaser, delivered

   To: agency@example.co.uk

   Subject: Deposit chaser

   communicate.email.external · approve?

   {"event":"approval.granted","actor":"human:alice","action_key":"aprv-842:chaser"}

   {"event":"execution.completed","adapter":"adapter-email"}

Alternatively run approval quickstart for a walkthrough.