Claude Code Plugin
The HITL Sessions plugin for Claude Code intercepts proposed file writes, edits, and dangerous shell commands, routes each one to a human reviewer on your phone, and blocks the agent until you respond. It’s designed for engineers who want to let Claude Code move fast on a real repo without giving up supervision of the risky parts.Stateful
Every Claude Code session creates one HITL session. Context — repo, branch, commit, turn history — is preserved across all turns.
Mobile-first review
Turns route to the HITL mobile app via push notification. Approve, modify, reject, or escalate from anywhere.
Audit trail
Every proposed action, every decision, every outcome is stored on the session and visible in the dashboard.
Zero-config denylist
Read is never gated. Bash is only gated on commands that look risky (git push, rm -rf, piped shell, sudo, publish).Install
1
Clone the plugin repo
2
Point Claude Code at it
For a single shell session:Or register it persistently via a local marketplace:
3
Get an API key
Head to my.hitl.sh → API Keys and create one. Any HITL API key works — there’s no separate Sessions-only key type.
4
Configure
Either via env vars:Or via Env vars override the file.
~/.claude/plugins/hitl-sessions/config.json:What gets gated
The default denylist covers
rm -rf, git push, git reset --hard, git checkout --, piped shell (| sh, | bash), sudo, and package publishing (npm publish, pnpm publish, yarn publish). Override with your own regex list in the config file.
Bash action_type is inferred from the command so reviewers see the right label:
git push ... → git_push, git commit ... → git_commit, npm install ... → dependency_install, anything with “migrate” → migration_run, rm ... → file_delete, everything else → command_exec.
Decision flow
1
Agent proposes an action
Claude Code is about to call
Write /src/server.ts. The PreToolUse hook fires before the tool actually runs.2
Plugin creates a turn
The plugin posts a turn to the HITL API. This creates a backing
request in the configured loop and sends FCM push notifications to every active reviewer’s device.3
Plugin long-polls
The plugin holds the tool call open while it long-polls
/turns/:id/wait (60s per round, up to 10 rounds = 10 minutes of patience by default).4
Reviewer decides on mobile
The mobile app shows the proposed action with full context (repo, branch, diff/command). The reviewer picks approve / modify / reject / escalate, optionally with a comment.
5
Plugin unblocks
- Approve → Claude Code runs the tool. Reviewer’s comment (if any) is surfaced to Claude via stderr.
- Modify / reject / escalate → the tool is blocked; the reviewer’s reason is returned to Claude as a
permissionDecision: denyso it can re-plan.
6
Plugin records outcome
PostToolUse records exit_code, stdout/stderr excerpt (for Bash) or the file path (for Write/Edit), and files_modified onto the turn for the audit trail.Slash commands
Fail-open vs fail-closed
If the HITL backend is unreachable, by default the plugin fails open — the tool call proceeds without review so a network blip doesn’t freeze your session. To fail closed (block tool calls when HITL is down), setHITL_SESSIONS_FAIL_CLOSED=1 or "fail_closed": true in config. Pick based on your risk tolerance.