humanctl

humanctl is a control plane for the human bottleneck.

You are the scarce resource in an agent fleet. Codex and Claude Code sessions pile up faster than you can watch them, and the expensive failure mode is silent: an agent finishes or blocks, and nobody notices for an hour. humanctl is an attention router for that scarce human. It tells you which sessions need you, why, and how to resume the work after you answer.

The core thesis: the session is not the work, the checkpoint is the work. Agents should package blockers into the smallest unit of human attention, keep the supporting context attached, and resume as soon as the answer lands.

humanctl ships two surfaces today:

• a desktop app: a local-first, read-only control room over your real Codex and Claude Code session transcripts
• a CLI: the agent-facing inbox plus the durable ask / artifact / watch object model under .humanctl/

The desktop app

The app reads recent Codex and Claude Code transcripts on your machine and shows the whole fleet in one exception-first surface: sessions that need you lead, everything healthy recedes. Three modes (Focus / Triage / Wall, keys 1/2/3) sit under a persistent chief-of-staff header that says who is waiting on you. Rows carry real signals only: context fill, token usage, spend at API rates, Codex 5h and weekly quota, model and reasoning effort. Pins and real session titles are kept. One click resumes a session in your terminal.

It is read-only and offline by default. It never writes to your transcripts and never sends anything off the machine, with one explicit opt-in exception: AI summaries, which pipe a session's recent messages through your local claude or codex CLI (you pick the engine). See docs/desktop.md.

Install

Desktop (macOS, from source):

npm install
npm run app:install   # builds and installs to /Applications/humanctl.app
                      # (falls back to ~/Applications if /Applications is not writable)

CLI:

npm i -g humanctl

Quick start

humanctl init .        # create a .humanctl/ workspace in this repo
humanctl status .      # summarize what is there
npm run desktop        # or run the control room live from source

Agents use the same CLI to escalate instead of blocking silently:

humanctl note --level review "PRs are up, need a review + merge in ~5m"
humanctl ask create --title "Redis or Postgres?" --prompt "Pick one" \
  --option "redis|Redis|fast, volatile" --option "pg|Postgres|durable"

The agent inbox

humanctl note is the core loop: a short aside to the human, appended to ~/.humanctl/notes.jsonl (one global inbox across every repo). The desktop app surfaces notes at the top of the control room.

• humanctl note --level fyi|review|blocked|done "message"
• --session <id> links a note to a session so the inbox can open it
• cwd and repo are captured automatically

Underneath sits the durable object model for bigger handoffs:

• humanctl ask create|get|list|update|answer|delete for bounded decisions
• humanctl artifact put|get|list|delete for previews and evidence
• humanctl watch create|get|list|update|delete for standing conditions

Everything is plain files plus an append-only event log, so future sessions resume from durable state instead of chat-history reconstruction. Prefer --json when another agent or script consumes the result.

Docs

Current:

• docs/desktop.md: the desktop control room reference
• docs/agentic-control-layer.md: the control-layer spec (workRef / executionRef / proofRef / checkpoint, pulse)
• docs/control-layer.md: the deeper control-layer framing

Historical and design-trail docs (kept for context, not current direction):

• docs/agent-first.md, docs/how-we-got-here.md, docs/source-identity.md, docs/decision-surface-research.md, docs/mvp-plan.md, docs/v1.md, docs/repo-topology-and-privacy.md
• notch docs (docs/notch-mvp.md, docs/notch-next-spec.md, docs/notch-recovery-protocol.md, docs/notch-shell-contract.md, docs/notch-shell-lessons.md): the native macOS notch shell is parked under attic/notch/, kept, not deleted

Development

The renderer is plain HTML/CSS/JS with no build step. Without the Electron bridge it falls back to synthetic fixtures, so the whole UI runs in a plain browser with zero real session data. That is the default loop:

npm run renderer       # serves electron/renderer/ at http://localhost:4173
npm run desktop        # Electron against your real local sessions
npm run desktop:sessions   # print the recent-session table to stdout

See AGENTS.md for the full operator notes.

Hygiene

This repo is public and born clean: no real session data, secrets, or personal paths in tracked files or history. Screenshots and demos use the synthetic fixtures, never real transcripts. scripts/secret-scan.sh gates the build. See docs/repo-hygiene.md.

Copy guardrail

On user-facing pages, do not leak builder notes into the copy. Do not narrate implementation details like "manually curated" or "backed by files" unless that detail is directly valuable to the user. Sell the outcome, not how the page was assembled.

Brand note

Use humanctl in lowercase for user-facing brand copy. Code identifiers and build target names may still use Humanctl... where needed.

License

Apache-2.0. See LICENSE. Contributions are expected under the same terms unless explicitly agreed otherwise.

Publishing (maintainers)

The npm package is intentionally CLI-only: the published tarball is limited by the files field in package.json, so the desktop app and site are not published to npm. Publishing runs via npm trusted publishing from GitHub Actions (.github/workflows/publish.yml); maintainer notes live in humanctl-trusted-publishing-notes.md.