Skip to main content

​
Sessions

Sessions are a HITL.sh primitive built for AI coding agents — Claude Code, Codex CLI, and any future agent that proposes file writes and shell commands. Where a classic HITL request is a one-off “review this piece of content”, a session is a long-running container of turns. Every turn is a proposed action the agent wants to take; every turn routes to a human reviewer, who approves, modifies, rejects, or escalates before the agent proceeds. This primitive exists because multi-turn coding workflows build up context: the agent reads files, forms a plan, edits several files, runs tests, commits. A single-shot review model can’t maintain that thread. Sessions do.

​
When to use

Use Sessions when:
  • You’re running an AI coding agent (Claude Code, Codex CLI) in an environment that shouldn’t make unsupervised changes to your repo.
  • You want mobile push review of every risky action: file writes, shell commands, git push, dependency installs, migrations.
  • You want a full audit trail of what the agent proposed and what humans decided.
Use classic Workflows/Responses when:
  • You just need one-off content review (moderation, classification, rating).
  • You have a single-turn automation that needs a thumbs-up/down.

​
Core resources

​
Session

A container for an agent coding session, scoped to a single project directory on the agent’s machine.

​
Turn

A single proposed action within a session.

​
Lifecycle

Abandoned sessions (idle 24h) are auto-cleaned after 30 days via MongoDB TTL.

​
How reviewers see turns

Every turn is backed by a standard HITL request (response_type single_select, options [approve, modify, reject, escalate]), so the existing mobile reviewer app renders turns with no changes. The request’s context carries session_id, turn_id, action_type, proposed_tool, proposed_args, and the repo / branch / commit — giving reviewers everything they need to decide on one screen.

​
Webhooks

Subscribe to turn.resolved to get push notifications when a reviewer acts:
Delivery is at-least-once with exponential-backoff retry (0s, 1s, 5s, 30s). 4xx responses are treated as subscriber rejects and not retried.

​
Install the plugin

See the Claude Code plugin guide to wire this into a real coding session.