coolhand-cli

coolhand-cli

coolhand-cli is a free command-line tool that helps you analyze and improve your local AI workflows, identify silent agent failures, and interact with the Coolhand APIs to find improvements for your production agents.

Install

One-shot, no install:

npx coolhand-cli login

Globally:

npm install -g coolhand-cli
coolhand login

Requires Node 20 or newer.

Analyze Claude sessions

coolhand analyze-claude-sessions [--dry-run] [--client-id ID] [--json]

Upload your historical Claude Code session transcripts to your Coolhand account for analysis. Coolhand analyzes the uploaded conversations to surface:

• Repeatable patterns — tasks you do by hand on repeat that could be scripted or automated
• Efficiency gaps — workflows with unnecessary back-and-forth or redundant steps
• Cost insights — sessions with high token usage relative to their outcome

What gets uploaded: The conversation transcripts stored in ~/.claude/projects/ — the messages exchanged between you and Claude, including any code or context you shared in those conversations. Use --dry-run to preview exactly what would be sent before submitting anything.

See Session capture for capture logic, duplicate-avoidance details, and the full flag reference.

Wildcard (agent complaint box)

When an agent is blocked because a capability does not exist in its environment, it can record the blocker and get back an unambiguous "stop and move on" response:

coolhand wildcard \
  --complaint "I need to run database migrations but no database is reachable" \
  --agent-name code-review-agent \
  --thinking "I attempted to connect to localhost:5432 but got connection refused. I checked for a running postgres process and found none. Without a live database I cannot apply or validate the migration."

The command records the complaint as feedback tagged creator_type: agent, prints a terminal de-loop message, and exits 0 so the agent stops and moves on. The de-loop always fires — even if the feedback could not be recorded (not logged in or a server error) — because the missing capability is real regardless of whether the server was reachable, and a logged-out agent in a sandbox is exactly who this command is for. When recording fails the message says so plainly and a warning is logged, so the failure still surfaces without trapping the agent in the retry loop the command exists to break. When no API key is available, the feedback is saved locally to ~/.coolhand/pending/ and will be uploaded automatically the next time you run coolhand login.

Set COOLHAND_AGENT_NAME to avoid passing --agent-name on every call. Optional --thinking attaches the reasoning that led to the blocker; --log-id ties it to a specific LLM request log.

See Your AI agent has notes for a presentation on the research & best practices for using this pattern.

Commands

Command	Description
coolhand login	Authenticate and store API keys
coolhand logout	Remove a stored client
coolhand status	Check whether a token is configured
coolhand whoami	Show the currently configured client
coolhand clients	List or switch the default client
coolhand claude	Run Claude CLI through the Coolhand proxy
coolhand list-workloads	List workloads with optional search and pagination
coolhand get-workload	Fetch a single workload by ID
coolhand update-workload	Update a workload's name and/or description
coolhand search-optimizations	List and filter optimization records
coolhand get-optimization	Fetch a single optimization by ID
coolhand update-optimization	Update an optimization's fields
coolhand close-optimization	Close an optimization with a reason
coolhand analyze-claude-sessions	Submit Claude sessions for pattern and cost analysis
coolhand wildcard	Record an agent blocker and exit cleanly

See docs/commands.md for full flag reference and usage notes.

Security

• The callback listener binds to 127.0.0.1 only — never reachable from the LAN.
• Tokens are delivered through a one-shot localhost redirect; subsequent calls to the listener get 410 Gone.
• CSRF protection: every login generates a random state value verified with crypto.timingSafeEqual before any token is accepted.
• ~/.coolhand/config.json is written atomically with mode 0o600; the parent directory is 0o700.
• Raw tokens are never printed to stdout or stderr. JSON output uses a masked form (e.g. e885b463…1148).
• Zero runtime dependencies — minimal supply-chain surface for the auth flow.

Programmatic use

import { run, loadConfig, getClient, maskToken } from 'coolhand-cli';

await run(['login', '--json']);

const cfg = await loadConfig();
const client = getClient(cfg);
console.log(client!.api_key ? maskToken(client!.api_key) : '(no public key)');

The CLI is shipped as an ES module. Importers must be ESM as well, or use a dynamic import().

Use with AI agents

coolhand-cli is designed to be invoked by AI agents and automated workflows, not just humans at a terminal. Two patterns make this straightforward:

Check auth before starting work:

coolhand status --json   # exit 0 = token present, exit 1 = not configured

Wire up the API key in one step:

coolhand login --write-env .env
# sets COOLHAND_API_KEY=<token> in .env, idempotent on re-run

The CLI works especially well with the Coolhand feedback collection skill for Claude Code. The skill scans your project for LLM inference calls and implements best-practice human feedback collection — it reads COOLHAND_API_KEY from the environment, which coolhand login --write-env .env puts in place.

Configuration file

Located at $HOME/.coolhand/config.json (override with COOLHAND_CONFIG_DIR for testing). Schema:

{
  "version": 1,
  "default_client_id": "acme",
  "clients": {
    "acme": {
      "client_id": "acme",
      "client_name": "Acme Inc",
      "api_key": "e885b463541f1d1c6002268f32bbb7c82d9a350437bd587eb429504005831148",
      "base_url": "https://coolhandlabs.com",
      "saved_at": "2026-05-12T18:04:11.000Z"
    }
  }
}

Documentation

• Commands — full flag reference and usage notes for all commands
• Proxy — CA certificate setup, proxy env vars, and system trust store instructions
• Auth Flow — browser-callback sequence, state machine, timeout and error paths
• Configuration File — full config schema, multi-client model, COOLHAND_CONFIG_DIR override
• Session Capture — session scanning, envelope format, deduplication, scope and limitations

About Coolhand Labs

Coolhand Labs builds observability and feedback tooling for AI-powered applications.

License

Apache-2.0