v0.11.1

coolhand-cli v0.11.1

September 2026 · npm · GitHub

What's new in v0.11.1

This patch release closes two secret-handling gaps found in a whole-package security review, upgrades coolhand-node to ^0.14.0, clears all open npm audit advisories in dev dependencies, and renames the repository's agent instructions file from CLAUDE.md to AGENTS.md. There are no new commands or flags.

Changed

coolhand-node bumped to ^0.14.0.

The repository's agent instructions file is now AGENTS.md (previously CLAUDE.md), with every reference updated. Claude Code 2.1.277+ falls back to AGENTS.md automatically; older versions won't pick up the instructions until updated. This affects contributors only, not the published package.

Dev dependencies updated: eslint to 10.10.0, @typescript-eslint/parser and @typescript-eslint/eslint-plugin to 8.70.0, and globals to 17.12.0.

Security

redactSecrets now catches quoted secret assignments whose quotes are JSON-escaped — for example export DB_PASSWORD="…" inside a captured tool input. Session payloads are stringified before redaction, so previously the secret value was uploaded to Coolhand unredacted.

The proxy sender and the last-sync lookup no longer follow HTTP redirects, so the X-API-Key header can't be forwarded to a redirect target.

Transitive dev-dependency advisories resolved (brace-expansion, browserslist, baseline-browser-mapping, qs) via a lockfile update. npm audit now reports 0 vulnerabilities.

Breaking changes

None.

v0.11.0

coolhand-cli v0.11.0

September 2026 · npm · GitHub

What's new in v0.11.0

This release adds four new commands for browsing LLM request templates, referenced files, and locally-built Claude skills, tightens the MITM proxy's network exposure and secret redaction, and drops the temporary coolhand-node git dependency now that its upstream release has shipped.

New commands

coolhand search-templates — lists and searches the resolved client's LLM request templates. The Unmatched and Ignored API Calls system buckets are hidden unless --include-system is passed.

coolhand search-templates --search "summarize" --workload-id abc123

Supports --search, --workload-id, --status, --include-deprecated, --include-system, --page, --per-page, --client-id, and --json. Requires a private API key (coolhand login --scope private).

coolhand get-template — fetches a single template by hashid, printing every list field plus the full, untruncated user_prompt_pattern and system_prompt_pattern.

coolhand search-referenced-files and coolhand list-referenced-file-sessions — read which files a client's logged requests are associated with. search-referenced-files lists files aggregated and ranked by reference count; list-referenced-file-sessions is the per-file drill-down.

coolhand search-referenced-files --file-path-contains src/config.ts
coolhand list-referenced-file-sessions --file-path src/config.ts

Both require a private API key and support pagination, --client-id, and --json.

coolhand sync-skills — discovers locally-built Claude skills (SKILL.md files) under ~/Documents/Claude, the Cowork local-agent-mode sessions directory, and ~/.claude/skills, content-hashes and dedupes near-identical copies, and uploads one canonical file per skill as a client file.

coolhand sync-skills --dry-run

Supports --root, --source, --skill, --exclude-skill, --force, --dry-run, --client-id, and --json. Requires a private API key, same as upload-client-file.

Changed

coolhand-node bumped to ^0.13.0 (now published to npm), dropping the temporary git-commit pin used while searchReferencedFiles/listReferencedFileSessions were in review.

Security

The MITM proxy (coolhand claude/coolhand monitor) now binds to 127.0.0.1 only, instead of all network interfaces — previously the unauthenticated forward proxy was reachable from any other host on the same network for as long as the wrapped command ran.

coolhand map-claude-projects --output PATH now asks for confirmation before overwriting an existing file, showing its size and modified time. Add --force to skip the prompt.

The MITM proxy now applies the same redactSecrets scrubber to captured request/response bodies that analyze-claude-sessions uses — previously only headers and the URL were sanitized, so a captured body echoing a live secret was uploaded to Coolhand verbatim.

redactSecrets now also catches Authorization: Basic headers and Slack/Discord webhook URLs — send-capable credentials that didn't match the existing assignment-keyword patterns.

Breaking changes

None. All changes are additive or security hardening — no removed/renamed commands, flags, or config fields.

v0.10.0

coolhand-cli v0.10.0

August 2026 · npm · GitHub

What's new in v0.10.0

This release adds two new commands for uploading files and generated reports to Coolhand as client files, attaches project-path metadata to submitted Claude Code sessions, and includes a batch of security hardening fixes to the MITM proxy, CA trust handling, and secret redaction.

New commands

coolhand upload-client-file — uploads a local file to Coolhand as a client file (via coolhand-node's Coolhand#uploadClientFile). Requires a private API key (coolhand login --scope private); a 20MB size cap matches coolhand-node's documented limit.

coolhand upload-client-file report.pdf --file-type report --description "Q3 summary"

Supports --name, --file-type, --description, --dry-run, --client-id, and --json.

coolhand map-claude-projects — recursively searches the home directory (or --root) for every folder named claude/.claude, and uploads a single markdown report listing the full file tree beneath each match with basic metadata (size, extension, created/modified times) — names and metadata only, never file contents.

coolhand map-claude-projects --dry-run --output ~/claude-map.md

Supports --root, --output (write the report locally for inspection without uploading), --dry-run, --client-id, and --json.

Changed

coolhand-node bumped to ^0.11.0 (now published to npm), dropping the temporary git-commit pin used while its PR was in review.

coolhand wildcard's scope broadened to cover tasks that would take too long or run indefinitely to complete, not just capabilities that are flatly unavailable.

analyze-claude-sessions now attaches metadata.project_path to submitted Claude Code sessions, taken from the transcript's own working directory. Cowork sessions are excluded, since Cowork has no real on-disk project concept.

Security

Terminal output is now stripped of ANSI/VT100 escape sequences before printing server-controlled text (status, whoami, clients, get-feedback), closing a terminal-control-sequence injection vector.

The MITM proxy's CA key/cert pair is now validated (ownership, file type, permissions) before being trusted, instead of silently adopting whatever's already on disk.

Sensitive query-string parameters are now redacted from captured proxy URLs before upload — some LLM APIs authenticate via ?key=... rather than a header.

The proxy's header-redaction list now includes cf-aig-authorization (Cloudflare AI Gateway).

map-claude-projects no longer walks a matched symlink whose target resolves outside the search root, closing a path where a planted symlink could leak an arbitrary directory's file listing into an uploaded report.

Fixed

redactSecrets now catches secrets in plain JSON ({"api_key": "value"}), not just unquoted-key assignment syntax, and adds a pattern for PEM-formatted private key blocks.

Pinned ip-address and get-port to resolve a high-severity SSRF advisory and a get-port ESM/CommonJS crash on Node 22.

--base-url now consistently enforces https-except-loopback across login and the proxy path.

analyze-claude-sessions --exclude-project now applies to Cowork sessions.

Windows: fixed a cmd.exe quoting inconsistency in the proxy's spawned-command escaping.

The prepare script now runs the full build, not just the version sync, fixing git-ref installs that previously produced a package with no compiled dist/.

Breaking changes

None. All changes are additive or security hardening — no removed/renamed commands, flags, or config fields.

v0.9.0

coolhand-cli v0.9.0

August 2026 · npm · GitHub

What's new in v0.9.0

This release adds two new commands for reading LLM request logs directly, plus a handful of documentation and validation fixes surfaced during release prep.

New commands

coolhand fetch-log and coolhand search-logs — fetch a single LLM request log's input/output content, or search logs with flexible filters, via GET /api/v2/llm_request_logs/{id} / GET /api/v2/llm_request_logs (coolhand-node's Coolhand#getLogContent/searchLogs). Requires a private API key (coolhand login --scope private).

coolhand fetch-log <log-id> --section end --max-chars 2000
coolhand search-logs --model gpt-4o --source-api-result failed --days-back 7

fetch-log <log-id> supports --section, --max-chars, --search-query, and --include-thinking; search-logs supports --template-id, --workload-id, --system-prompt-contains, --user-prompt-contains, --model, --source-api, --source-api-result, --unmatched-only, --days-back, --include-prompts, --sort, and pagination. search-logs's response is { logs, pagination }, matching search-feedback's shape — pagination totals are a conservative lower-bound estimate until the backend exposes exact counts.

Fixed

search-optimizations --page/--per-page now actually validates its documented 1-50 range. Previously any value silently passed through despite the CLI's own help text advertising the limit.

login's --timeout-ms and logout's --json flags were already implemented but missing from the CLI's built-in help and docs — both are now documented.

Breaking changes

None. All changes are additive — new commands, previously-missing docs, and a validation fix that only rejects input the tool never actually supported.

v0.8.0

coolhand-cli v0.8.0

July 2026 · npm · GitHub

What's new in v0.8.0

This release adds two new commands for browsing feedback records, gives analyze-claude-sessions fine-grained upload filters, and makes get-optimization significantly more readable by default — plus a handful of correctness fixes to existing commands.

New commands

coolhand search-feedback and coolhand get-feedback — search/list and fetch feedback records (GET /api/v2/llm_request_log_feedbacks). Requires a private API key (coolhand login --scope private) — the public key used by wildcard/createFeedback 401s on these read endpoints.

coolhand search-feedback --sentiment negative --since 7d
coolhand get-feedback fb-123

search-feedback supports --sentiment, --search, --creator-id, --workload-id, --matched/--unmatched, --since, --sort-by/--sort-dir, and pagination; get-feedback <id> prints a human-readable summary including original_output/revised_output/feedback_partials, which list results omit.

Changes

analyze-claude-sessions gains upload filters. --since/--until (date, ISO datetime, or 12h/7d/2w duration) narrow by modified time; --project/--exclude-project narrow by project folder name; --projects-dir redirects the scan to a custom directory. Filtered sessions are never read from disk, and a filtered run never advances the incremental sync cutoff.

get-optimization prints a human-readable summary by default (title, status, type, category, impact, complexity, client/template/workload, created date, analysis, and plan) instead of a raw JSON dump, plus a "Next steps" footer pointing to close-optimization/update-optimization.

mcp-call 401 errors now include a hint to run coolhand login --scope private to re-authenticate.

status, whoami, and clients now show whether a private key is stored (masked, or (no private key)), via a new masked_private_key field in JSON output and an extra column in clients' plain-text listing.

Fixed

login no longer drops a stored private_key when a later plain coolhand login (public scope only) re-authenticates the same client. Fixes intermittent 401s on private-scope commands (update-workload, list-workloads) after re-logging in without --scope private.

close-optimization now sends the field the backend actually requires (explanation instead of reason) — previously this command failed against the real API. The CLI-facing <reason> argument is unchanged.

get-optimization now correctly unwraps the { optimization: {...} } response shape returned by the backend — previously fields like pr_number, pr_url, and coding_prompt were read from the top level and silently never populated.

Breaking changes

None for existing commands or flags. One default-output change: get-optimization's --json output no longer includes the internal orchestrator_messages transcript by default (it can add tens of KB of internal agent-transcript data). Pass get-optimization --full --json to get the complete payload as before.

v0.7.0

coolhand-cli v0.7.0

July 2026 · npm · GitHub

What's new in v0.7.0

This release generalizes the proxy wrapping that coolhand claude already provided into a new coolhand monitor command, so any CLI — not just Claude Code — can have its outbound LLM traffic captured through the same in-process MITM proxy, without a separate daemon process.

New commands

coolhand monitor — runs an arbitrary CLI behind the Coolhand proxy, the same way coolhand claude already does for Claude Code. A leading -- is optional; everything after the wrapped command's name is passed straight through to it.

coolhand monitor -- kimi           # start kimi with capture on
coolhand monitor kimi --resume     # the -- is optional; flags pass through

Changes

coolhand claude's proxy wiring extracted into a shared engine. claude and monitor now both delegate to the same underlying CA-cert reuse, environment-variable injection, and spawn/exit-code handling. coolhand claude's behavior, flags, and output are unchanged.

Per-command collector labeling. Captured requests are now labeled with the CLI that produced them (e.g. coolhand-cli-0.7.0/kimi) instead of always being labeled claude, so traffic from wrapped tools is correctly attributed in the Coolhand dashboard.

Breaking changes

None. coolhand claude is unchanged.

v0.6.0

coolhand-cli v0.6.0

July 2026 · npm · GitHub

What's new in v0.6.0

This release adds workload management commands, a global --client-id flag with an environment-variable equivalent, interactive client selection when multiple accounts are configured, and moves coolhand claude's proxy off the deprecated coolhand-proxy binary onto an in-process HTTPS MITM proxy. wildcard also gained local feedback queuing so submissions are never silently dropped when logged out.

New commands

coolhand list-workloads — browse and search workloads by name with pagination (--search, --page, --per-page, --include-archived, --include-system, --include-templates). Requires a private API key (coolhand login --scope private).

coolhand get-workload --id <id> and coolhand update-workload --id <id> [--name VALUE] [--description VALUE] — fetch or rename/re-describe a single workload. update-workload requires at least one of --name/--description; renaming a system workload (Unmatched, Embedding Requests, Ignored API Calls) is rejected by the API, though updating its description is allowed.

Changes

--client-id ID now works as a global flag, placed before the subcommand (e.g. coolhand --client-id acme list-workloads), in addition to the existing per-command position. This also applies to coolhand claude.

COOLHAND_CLIENT_ID environment variable selects a stored client without passing --client-id on every invocation. Priority: --client-id flag > COOLHAND_CLIENT_ID env > configured default > auto-pick (single client) > interactive prompt.

Interactive client selection. When multiple clients are stored and no default is configured, API commands now prompt interactively (TTY) or emit a descriptive error listing all clients (non-TTY) instead of failing with NOT_CONFIGURED. Every client-aware command now also prints Client: <name> (<id>) to stderr so the active account is always visible.

coolhand claude now runs an in-process HTTPS MITM proxy (powered by mockttp) instead of shelling out to the deprecated coolhand-proxy binary. A CA certificate is generated on first run and persisted to ~/.coolhand/proxy/ca-cert.pem — see docs/proxy.md for system trust store installation. It also now works correctly on Windows (spawned via cmd.exe /d /s /c with explicit argument quoting) and exits with a clear error if the configured client has no public API key.

wildcard now saves feedback locally to ~/.coolhand/pending/ when no API key is configured, instead of silently dropping it. Pending feedback uploads automatically on the next coolhand login, with a retry prompt if that upload fails.

Login and account handling improvements: coolhand login --scope private no longer errors if the private key is declined on the consent page (it stores the public key and notes MCP access wasn't granted); a warning is now emitted when the default client no longer exists; status/whoami/clients show (no public key) instead of *** for private-key-only clients; mcp-call now uses the shared client-resolution chain and treats { error: "..." } tool results as failures.

Breaking changes

None.

v0.5.2

coolhand-cli v0.5.2

June 2026 · npm · GitHub

What's new in v0.5.2

This is a small polish release. The wildcard command now stamps each feedback submission with the running CLI version, making it easy to correlate complaints with the tool version that produced them.

Changes

wildcard feedback is now labeled with the CLI version. Submissions include a coolhand-cli-x.x.x label so the source version is visible in the Coolhand dashboard without having to cross-reference logs.

README restructured. The value proposition and section layout were rewritten for clarity and discoverability.

Breaking changes

None.

v0.5.1

coolhand-cli v0.5.1

June 2026 · npm · GitHub

What's new in v0.5.1

This release extends analyze-claude-sessions to capture Claude Cowork sessions alongside existing Claude Code sessions. Both sources are scanned in parallel and their results merged, so a single coolhand analyze-claude-sessions run covers your entire local session history regardless of which Claude client produced it.

Changes

analyze-claude-sessions now captures Claude Cowork sessions. The command scans ~/Library/Application Support/Claude/local-agent-mode-sessions/**/local_*/audit.jsonl and submits each agent invocation as a cowork://session/<uuid> envelope. Cowork sessions get their own mtime cutoff (coworkLastSyncAt in capture-state.json) so they are tracked independently from Claude Code sessions.

Robust error handling for missing or unreadable directories. If the Cowork sessions directory doesn't exist or can't be read, the error is swallowed and the Claude Code half of the run continues unaffected.

ScanResult gains an ok field. coworkLastSyncAt is only advanced when the Cowork directory was successfully read, preventing stale cutoffs from skipping sessions on the next run.

Breaking changes

None. Existing capture-state.json files are read forward-compatibly; coworkLastSyncAt defaults to the beginning of time on first run.

v0.5.0

coolhand-cli v0.5.0

June 2026 · npm · GitHub

What's new in v0.5.0

This release adds coolhand claude — a wrapper that runs Claude Code behind the Coolhand proxy so every session is captured automatically as you work, without any manual export step. It also upgrades analyze-claude-sessions to detect when a session has grown since it was last submitted and re-upload it with the full updated conversation, so incremental runs stay in sync with your local transcripts.

New commands

coolhand claude — runs Claude Code behind the Coolhand proxy, routing all outbound traffic through your configured client. Any arguments after claude are passed straight through to the Claude CLI.

```bash
coolhand claude # start Claude with capture on
coolhand claude --resume # pass flags through to Claude
```

Changes

analyze-claude-sessions now re-uploads updated sessions. Previously, a session submitted on a prior run was always skipped on re-runs. Now, if a session has more turns than when it was last submitted, the full updated conversation is re-uploaded. Unchanged sessions are still skipped. Turn count (not file mtime) is the source of truth; mtime is used only as a cheap pre-filter.

coolhand-node upgraded to 0.8.0, resolving a js-yaml audit vulnerability.

Breaking changes

coolhand capture-sessions no longer exists. The command was renamed to coolhand analyze-claude-sessions in this release. Update any scripts or aliases accordingly.