AI in the human loop

A human at a laptop on the left and an AI agent on the right, with an open HUMAN.md notebook listing entries H-001, H-002, H-003 between them. A coral arrow loops from the AI back through the notebook to the human, showing that the AI writes feedback into HUMAN.md so the human can write better requests.

A template and live experiment for running a HUMAN.md feedback loop in coding projects that use AI agents.

HUMAN.md collects friction that an agent observes on the human side of the loop — unclear requests, missing decisions, undeclared scope, absent review criteria — and turns each observation into a concrete prompt or review pattern the human can use next time.

This repository is two things at once:

A template you can install to start the loop in another repository. The skill, the /triage command, the schema, and the SessionStart and Stop hooks are written to be domain-neutral and install once at user scope; a repository that opts in carries its own HUMAN.md (the rules layer) and HUMAN_FRICTIONS.md (the log layer).
A live experiment. This repository runs its own loop, and the Operation Log section at the bottom of HUMAN_FRICTIONS.md records what worked and what did not.

How `HUMAN.md` differs from Claude Code memory

Claude Code already has a per-project memory system that records facts the agent should remember across sessions. HUMAN.md is not a replacement for it. They have different jobs.

Observation	Where it goes
Something the agent itself should do differently (vocabulary, output format, procedure)	Claude Code memory
Something a human should write, review, or decide differently	`HUMAN.md`

Examples:

"Avoid the verb tateru on abstract nouns" → memory. The agent's wording is the thing being corrected.
"Declare in the request which subsystems are in scope" → HUMAN.md. The human's request is the thing being corrected.

If an observation could belong to either side, write it in the place that matches the corrective action, not the place that matches who made the mistake.

The loop

Observe   → an agent notices friction during work; the Stop hook nudges it at
            the end of each turn to record anything it observed
Record    → the human-feedback skill logs the observation to HUMAN_FRICTIONS.md,
            and when it clears the threshold writes/updates a rule in HUMAN.md
Surface   → the SessionStart hook puts the open HUMAN.md rules in front of the
            human at the start of each session
Triage    → /triage moves entries from open to adopted, obsolete, or merged

Two Claude Code hooks drive the loop's edges. The SessionStart hook (scripts/session-start.sh) surfaces open entries when a session begins. The Stop hook (scripts/stop-reminder.sh) fires at the end of every turn and emits one short, conditional reminder so the agent reconsiders, against the skill's own bar, whether the turn produced friction worth recording. It never blocks the turn; both hooks stay silent in repositories without a HUMAN.md.

The schema for an entry is defined in skills/human-feedback/HUMAN.schema.md.

Getting started in another repository

Installing the loop has two parts: set up the machinery once (the human-feedback skill, the /triage command, and the SessionStart + Stop hooks), then drop HUMAN.md and HUMAN_FRICTIONS.md into each repository where you want the loop.

For the machinery, pick one of the two methods below. They deliver the same skill, command, and hooks — use one or the other on a given machine, because installing both makes the hooks fire twice.

Method A — Claude Code plugin (auto-updating)

If you use Claude Code, install the loop as a plugin from this repo's marketplace. Claude Code keeps the plugin up to date automatically.

/plugin marketplace add kawasima/ai-in-the-human-loop
/plugin install ai-in-the-human-loop@kawasima

The plugin bundles the skill, the commands, and the hooks. Its skill and commands are namespaced: ai-in-the-human-loop:human-feedback, /ai-in-the-human-loop:triage, and /ai-in-the-human-loop:init (which scaffolds the two per-repo files — see below).

Method B — install.sh (Claude Code, Codex, or Gemini)

Use install.sh to symlink the machinery into your agent's user-scope directories. This is the only route for Codex and Gemini.

# Pick one (or run multiple times for multiple agents):
curl -fsSL https://raw.githubusercontent.com/kawasima/ai-in-the-human-loop/main/install.sh | bash -s claude
curl -fsSL https://raw.githubusercontent.com/kawasima/ai-in-the-human-loop/main/install.sh | bash -s codex
curl -fsSL https://raw.githubusercontent.com/kawasima/ai-in-the-human-loop/main/install.sh | bash -s gemini

ai-in-the-human-loop

Popularity

What's Inside

README