coolhand-cli 0.6.0 → 0.8.0

package/README.md

@@ -22,7 +22,7 @@ Requires Node 20 or newer.
 ## Analyze Claude sessions
 
 ```bash
-coolhand analyze-claude-sessions [--dry-run] [--client-id ID] [--json]
+coolhand analyze-claude-sessions [--dry-run] [--client-id ID] [--json] [filter options]
 ```
 
 Upload your historical Claude Code session transcripts to your Coolhand account for analysis. Coolhand analyzes the uploaded conversations to surface:
@@ -31,7 +31,7 @@ Upload your historical Claude Code session transcripts to your Coolhand account
 - **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.
+> **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. You control the scope: `--since`/`--until` bound the time period, and `--project`/`--exclude-project`/`--projects-dir` choose which folders are uploaded from — excluded sessions are never even read from disk.
 
 See [Session capture](./docs/session-capture.md) for capture logic, duplicate-avoidance details, and the full flag reference.
 
@@ -52,6 +52,23 @@ Set `COOLHAND_AGENT_NAME` to avoid passing `--agent-name` on every call. Optiona
 
 See [Your AI agent has notes](https://michael.carroll.io/talks/2026/your-ai-agent-has-notes) for a presentation on the research & best practices for using this pattern.
 
+## Optimizations
+
+Coolhand surfaces optimizations found for your production agents — a way to search, inspect, and act on suggested improvements without leaving the terminal:
+
+```bash
+# Find open, high-impact optimizations
+coolhand search-optimizations --status proposed --sort-by impact_desc
+
+# Inspect one in full (human-readable by default; add --json for scripting)
+coolhand get-optimization opt-123
+
+# Apply the fix, then close it out with a reason
+coolhand close-optimization opt-123 "Added the suggested index; verified query latency dropped from 800ms to 120ms in staging."
+```
+
+`get-optimization` prints a scannable summary by default — title, status, impact/complexity, analysis, and plan — not a raw JSON dump. Internal agent transcript data (`orchestrator_messages`) is only included with `--full`. See [docs/commands.md](./docs/commands.md) for the full flag reference, including `update-optimization` for editing an optimization's fields in place.
+
 ## Commands
 
 | Command | Description |
@@ -62,6 +79,7 @@ See [Your AI agent has notes](https://michael.carroll.io/talks/2026/your-ai-agen
 | `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 monitor` | Run an arbitrary 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 |
@@ -69,6 +87,8 @@ See [Your AI agent has notes](https://michael.carroll.io/talks/2026/your-ai-agen
 | `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 search-feedback` | Search and filter feedback records |
+| `coolhand get-feedback` | Fetch a single feedback record by ID |
 | `coolhand analyze-claude-sessions` | Submit Claude sessions for pattern and cost analysis |
 | `coolhand wildcard` | Record an agent blocker and exit cleanly |
 

package/dist/api/feedback-client.d.ts

@@ -0,0 +1,17 @@
+import { Coolhand } from 'coolhand-node';
+import { CliError } from '../errors.js';
+/**
+ * Resolves the CLI's stored client and returns a `Coolhand` instance authenticated with its
+ * *private* key. `searchFeedback`/`getFeedback` (coolhand-node#89) require the private key — the
+ * public key used by `wildcard`/`createFeedback` will 401 here.
+ */
+export declare function getFeedbackClient(opts?: {
+    clientId?: string;
+}): Promise<Coolhand>;
+/**
+ * Maps an error thrown by `Coolhand#searchFeedback`/`getFeedback` to a `CliError` with a clear,
+ * actionable message — a 401 means the stored private key was rejected (mirrors `mcp-call.ts`'s
+ * hint), a 404 uses the caller-supplied message (e.g. "Feedback \"x\" not found").
+ */
+export declare function mapFeedbackHttpError(err: unknown, notFoundMessage: string): CliError;
+//# sourceMappingURL=feedback-client.d.ts.map

package/dist/api/feedback-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-client.d.ts","sourceRoot":"","sources":["../../src/api/feedback-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAa,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAGxC;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAoB3F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,GAAG,QAAQ,CAcpF"}

package/dist/api/feedback-client.js

@@ -0,0 +1,40 @@
+import { Coolhand, HttpError } from 'coolhand-node';
+import { CliError } from '../errors.js';
+import { loadConfig, resolveClient } from '../config.js';
+/**
+ * Resolves the CLI's stored client and returns a `Coolhand` instance authenticated with its
+ * *private* key. `searchFeedback`/`getFeedback` (coolhand-node#89) require the private key — the
+ * public key used by `wildcard`/`createFeedback` will 401 here.
+ */
+export async function getFeedbackClient(opts = {}) {
+    const cfg = await loadConfig();
+    const client = await resolveClient(cfg, opts.clientId);
+    if (!client.private_key) {
+        throw new CliError('NO_PRIVATE_KEY', "No private key configured. Run 'coolhand login --scope private' first.");
+    }
+    try {
+        // Coolhand validates baseUrl in its constructor (https required; http only for localhost).
+        return new Coolhand({ apiKey: client.private_key, baseUrl: client.base_url, silent: true });
+    }
+    catch (err) {
+        throw new CliError('INVALID_BASE_URL', `Invalid base_url for client: ${client.base_url} (${err.message})`);
+    }
+}
+/**
+ * Maps an error thrown by `Coolhand#searchFeedback`/`getFeedback` to a `CliError` with a clear,
+ * actionable message — a 401 means the stored private key was rejected (mirrors `mcp-call.ts`'s
+ * hint), a 404 uses the caller-supplied message (e.g. "Feedback \"x\" not found").
+ */
+export function mapFeedbackHttpError(err, notFoundMessage) {
+    if (err instanceof HttpError) {
+        if (err.status === 401) {
+            return new CliError('FEEDBACK_ERROR', "The stored private key was rejected. Run 'coolhand login --scope private' to re-authenticate.");
+        }
+        if (err.status === 404) {
+            return new CliError('FEEDBACK_ERROR', notFoundMessage);
+        }
+        return new CliError('FEEDBACK_ERROR', `Feedback request failed (${err.status}): ${err.message}`);
+    }
+    return new CliError('FEEDBACK_ERROR', `Feedback request failed: ${err.message}`);
+}
+//# sourceMappingURL=feedback-client.js.map

package/dist/api/feedback-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-client.js","sourceRoot":"","sources":["../../src/api/feedback-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAA8B,EAAE;IACtE,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEvD,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAChB,gBAAgB,EAChB,wEAAwE,CACzE,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,2FAA2F;QAC3F,OAAO,IAAI,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAChB,kBAAkB,EAClB,gCAAgC,MAAM,CAAC,QAAQ,KAAM,GAAa,CAAC,OAAO,GAAG,CAC9E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAY,EAAE,eAAuB;IACxE,IAAI,GAAG,YAAY,SAAS,EAAE,CAAC;QAC7B,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,OAAO,IAAI,QAAQ,CACjB,gBAAgB,EAChB,+FAA+F,CAChG,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,OAAO,IAAI,QAAQ,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,IAAI,QAAQ,CAAC,gBAAgB,EAAE,4BAA4B,GAAG,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,gBAAgB,EAAE,4BAA6B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;AAC9F,CAAC"}

package/dist/api/last-sync.d.ts

@@ -1,14 +1,16 @@
 /**
- * Ask the server for the timestamp of the most recent log it already holds from this collector, so
+ * Ask the server for the timestamp of the most recent Claude Code log it already holds, so
  * `capture-sessions` only re-scans files newer than that. This is a server-authoritative cutoff that
  * survives local state-file loss or a reinstall.
  *
- * It NEVER throws: any problem (no api key, bad base url, 404, network failure, non-JSON body, or a
- * missing/invalid `last_created_at`) returns `null` so the caller can fall back to local state. The
- * companion server endpoint may not exist yet; a 404 is therefore an expected, non-fatal outcome.
+ * Queries the `/api/v2/llm_request_logs` index for the single newest `claude_code` row. The server
+ * has no default sort, so newest-first is requested explicitly via `q[s]`. Index reads require the
+ * client's PRIVATE key (`private_key`, or the `COOLHAND_PRIVATE_KEY` env var); the public ingest
+ * key is write-only and the server answers it with a 401.
  *
- * Auth mirrors the ingest path (`log-request.ts`): the public `api_key` sent as `X-API-Key`, since
- * the endpoint lives on the same `/api/v2/llm_request_logs` path.
+ * It NEVER throws: any problem (no private key, bad base url, 401, network failure, non-JSON body,
+ * an empty result set, or an invalid `created_at`) returns `null` so the caller can fall back to
+ * local state.
  *
  * `opts.clientId` is expected to be an **already-resolved** `client_id` string (e.g. from
  * `resolveClient`), not a raw user input. `getClient` is used here deliberately: by the time this

package/dist/api/last-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"last-sync.d.ts","sourceRoot":"","sources":["../../src/api/last-sync.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAuD1F"}
+{"version":3,"file":"last-sync.d.ts","sourceRoot":"","sources":["../../src/api/last-sync.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,CAAC,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAmE1F"}

package/dist/api/last-sync.js

@@ -1,19 +1,18 @@
 import { loadConfig, getClient } from '../config.js';
 import { DEFAULT_BASE_URL } from '../types.js';
-import { PACKAGE_IDENTIFIER } from '../version.js';
-/** Identifies this tool's logs in the server's collector field (matches the ingest collector). */
-const COLLECTOR = `${PACKAGE_IDENTIFIER}/claude-code`;
 /**
- * Ask the server for the timestamp of the most recent log it already holds from this collector, so
+ * Ask the server for the timestamp of the most recent Claude Code log it already holds, so
  * `capture-sessions` only re-scans files newer than that. This is a server-authoritative cutoff that
  * survives local state-file loss or a reinstall.
  *
- * It NEVER throws: any problem (no api key, bad base url, 404, network failure, non-JSON body, or a
- * missing/invalid `last_created_at`) returns `null` so the caller can fall back to local state. The
- * companion server endpoint may not exist yet; a 404 is therefore an expected, non-fatal outcome.
+ * Queries the `/api/v2/llm_request_logs` index for the single newest `claude_code` row. The server
+ * has no default sort, so newest-first is requested explicitly via `q[s]`. Index reads require the
+ * client's PRIVATE key (`private_key`, or the `COOLHAND_PRIVATE_KEY` env var); the public ingest
+ * key is write-only and the server answers it with a 401.
  *
- * Auth mirrors the ingest path (`log-request.ts`): the public `api_key` sent as `X-API-Key`, since
- * the endpoint lives on the same `/api/v2/llm_request_logs` path.
+ * It NEVER throws: any problem (no private key, bad base url, 401, network failure, non-JSON body,
+ * an empty result set, or an invalid `created_at`) returns `null` so the caller can fall back to
+ * local state.
  *
  * `opts.clientId` is expected to be an **already-resolved** `client_id` string (e.g. from
  * `resolveClient`), not a raw user input. `getClient` is used here deliberately: by the time this
@@ -26,7 +25,7 @@ export async function fetchLastSync(opts = {}) {
     try {
         const cfg = await loadConfig();
         const client = getClient(cfg, opts.clientId);
-        apiKey = client?.api_key ?? process.env.COOLHAND_API_KEY;
+        apiKey = client?.private_key ?? process.env.COOLHAND_PRIVATE_KEY;
         baseUrl = client?.base_url ?? DEFAULT_BASE_URL;
     }
     catch {
@@ -41,8 +40,10 @@ export async function fetchLastSync(opts = {}) {
         if (parsedBaseUrl.protocol !== 'http:' && parsedBaseUrl.protocol !== 'https:') {
             return null;
         }
-        const endpoint = new URL('/api/v2/llm_request_logs/last_sync', parsedBaseUrl);
-        endpoint.searchParams.set('collector', COLLECTOR);
+        const endpoint = new URL('/api/v2/llm_request_logs', parsedBaseUrl);
+        endpoint.searchParams.set('q[source_api_in][]', 'claude_code');
+        endpoint.searchParams.set('q[s]', 'created_at desc');
+        endpoint.searchParams.set('per', '1');
         url = endpoint.toString();
     }
     catch {
@@ -60,20 +61,30 @@ export async function fetchLastSync(opts = {}) {
         return null;
     }
     if (!res.ok) {
-        // 404 (endpoint not built yet) or any other non-2xx — degrade to local state.
+        // 401 (key lacks read access) or any other non-2xx — degrade to local state.
         return null;
     }
     let body;
     try {
-        body = (await res.json());
+        body = await res.json();
     }
     catch {
         return null;
     }
-    if (typeof body.last_created_at !== 'string') {
+    // The index returns a bare JSON array; an empty one means the server holds no
+    // claude_code logs for this client yet.
+    if (!Array.isArray(body) || body.length === 0) {
         return null;
     }
-    const date = new Date(body.last_created_at);
+    const newest = body[0];
+    if (newest === null || typeof newest !== 'object') {
+        return null;
+    }
+    const createdAt = newest.created_at;
+    if (typeof createdAt !== 'string') {
+        return null;
+    }
+    const date = new Date(createdAt);
     return Number.isNaN(date.getTime()) ? null : date;
 }
 //# sourceMappingURL=last-sync.js.map

package/dist/api/last-sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"last-sync.js","sourceRoot":"","sources":["../../src/api/last-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,kGAAkG;AAClG,MAAM,SAAS,GAAG,GAAG,kBAAkB,cAAc,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA8B,EAAE;IAClE,IAAI,MAA0B,CAAC;IAC/B,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,GAAG,MAAM,EAAE,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;QACzD,OAAO,GAAG,MAAM,EAAE,QAAQ,IAAI,gBAAgB,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,aAAa,CAAC,QAAQ,KAAK,OAAO,IAAI,aAAa,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC9E,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,oCAAoC,EAAE,aAAa,CAAC,CAAC;QAC9E,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QAClD,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YACrB,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,EAAE;SAC7D,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,8EAA8E;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,IAAyC,CAAC;IAC9C,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAwC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,IAAI,CAAC,eAAe,KAAK,QAAQ,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC5C,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC"}
+{"version":3,"file":"last-sync.js","sourceRoot":"","sources":["../../src/api/last-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA8B,EAAE;IAClE,IAAI,MAA0B,CAAC;IAC/B,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,UAAU,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,GAAG,MAAM,EAAE,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACjE,OAAO,GAAG,MAAM,EAAE,QAAQ,IAAI,gBAAgB,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,aAAa,CAAC,QAAQ,KAAK,OAAO,IAAI,aAAa,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC9E,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,0BAA0B,EAAE,aAAa,CAAC,CAAC;QACpE,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,oBAAoB,EAAE,aAAa,CAAC,CAAC;QAC/D,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;QACrD,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACtC,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YACrB,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,EAAE;SAC7D,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,6EAA6E;QAC7E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8EAA8E;IAC9E,wCAAwC;IACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,SAAS,GAAI,MAAmC,CAAC,UAAU,CAAC;IAClE,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC"}

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 interface ParsedArgs {
     command: string;
     positional: string[];
-    flags: Record<string, string | boolean>;
+    flags: Record<string, string | boolean | string[]>;
 }
 /**
  * Strips a leading `--client-id VALUE` or `--client-id=VALUE` from argv,

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsCA,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;CACzC;AAmOD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAgE7F;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAqCpD;AA+VD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmHzD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA2CA,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAC;CACpD;AAkRD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAgE7F;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAiDpD;AAkdD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAsIzD"}

package/dist/cli.js

@@ -12,14 +12,19 @@ import { run as runCloseOptimization } from './commands/close-optimization.js';
 import { run as runUpdateOptimization } from './commands/update-optimization.js';
 import { run as runWildcard } from './commands/wildcard.js';
 import { run as runClaude } from './commands/claude.js';
+import { run as runMonitor } from './commands/monitor.js';
 import { run as runAnalyzeClaudeSessions } from './commands/analyze-claude-sessions.js';
 import { run as runListWorkloads } from './commands/list-workloads.js';
 import { run as runGetWorkload } from './commands/get-workload.js';
 import { run as runUpdateWorkload } from './commands/update-workload.js';
 import { run as runFlushPending, spawnBackgroundFlush } from './commands/flush-pending.js';
+import { run as runSearchFeedback } from './commands/search-feedback.js';
+import { run as runGetFeedback } from './commands/get-feedback.js';
 import { countPending, flushFailed } from './pending-store.js';
 import { confirm } from './prompt.js';
-const BOOLEAN_FLAGS = new Set(['all', 'help', 'h', 'json', 'version', 'v', 'dry-run', 'include-archived', 'include-system', 'include-templates']);
+const BOOLEAN_FLAGS = new Set(['all', 'help', 'h', 'json', 'version', 'v', 'dry-run', 'include-archived', 'include-system', 'include-templates', 'full', 'matched', 'unmatched']);
+/** Flags whose repeated occurrences accumulate into an array instead of overwriting. */
+const REPEATABLE_FLAGS = new Set(['project', 'exclude-project']);
 const COMMANDS = [
     {
         name: 'login',
@@ -91,8 +96,9 @@ const COMMANDS = [
     {
         name: 'get-optimization',
         oneLiner: 'Get a single optimization by ID',
-        usage: 'coolhand get-optimization <id> [options]',
+        usage: 'coolhand get-optimization <id> [--full] [options]',
         options: [
+            { flag: '--full', description: 'Include the internal orchestrator_messages transcript (large; contains raw thoughtSignature blobs), on both text and --json output' },
             { flag: '--client-id ID', description: 'Use a specific stored client' },
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
         ],
@@ -132,6 +138,35 @@ const COMMANDS = [
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
         ],
     },
+    {
+        name: 'search-feedback',
+        oneLiner: 'Search and filter feedback records (requires a private key)',
+        usage: 'coolhand search-feedback [options]',
+        options: [
+            { flag: '--sentiment positive|negative|neutral', description: 'Filter by sentiment' },
+            { flag: '--search TEXT', description: 'Filter by explanation substring' },
+            { flag: '--creator-id ID', description: 'Filter by creator_unique_id' },
+            { flag: '--workload-id ID', description: 'Filter by workload ID' },
+            { flag: '--matched', description: 'Only feedback linked to an LLM request log' },
+            { flag: '--unmatched', description: 'Only feedback not linked to an LLM request log' },
+            { flag: '--since DATE', description: 'Only feedback created at or after DATE' },
+            { flag: '--sort-by created_at|updated_at', description: 'Sort field (default: created_at)' },
+            { flag: '--sort-dir asc|desc', description: 'Sort direction (default: desc)' },
+            { flag: '--page N', description: 'Page number (default: 1)' },
+            { flag: '--per-page N', description: 'Results per page (default: 25, max: 100)' },
+            { flag: '--client-id ID', description: 'Use a specific stored client' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
+    {
+        name: 'get-feedback',
+        oneLiner: 'Get a single feedback record by ID (requires a private key)',
+        usage: 'coolhand get-feedback <feedback-id> [options]',
+        options: [
+            { flag: '--client-id ID', description: 'Use a specific stored client' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
     {
         name: 'analyze-claude-sessions',
         oneLiner: 'Submit historical Claude Code sessions to Coolhand for pattern and cost analysis',
@@ -140,6 +175,11 @@ const COMMANDS = [
             { flag: '--dry-run', description: 'Scan and report what would be submitted, without sending' },
             { flag: '--client-id ID', description: 'Use a specific stored client' },
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+            { flag: '--since WHEN', description: 'Only sessions modified at or after WHEN (YYYY-MM-DD, ISO datetime, or 12h/7d/2w)' },
+            { flag: '--until WHEN', description: 'Only sessions modified at or before WHEN (same formats; a date means its whole day)' },
+            { flag: '--projects-dir PATH', description: 'Scan PATH instead of ~/.claude/projects' },
+            { flag: '--project NAME', description: 'Only sessions from matching project folders (repeatable, comma-separable)' },
+            { flag: '--exclude-project NAME', description: 'Skip sessions from matching project folders (repeatable, comma-separable)' },
         ],
     },
     {
@@ -151,6 +191,15 @@ const COMMANDS = [
             { flag: '[claude args...]', description: 'Everything after `claude` is passed straight to the Claude CLI' },
         ],
     },
+    {
+        name: 'monitor',
+        oneLiner: 'Run an arbitrary CLI through the Coolhand proxy (captures LLM calls)',
+        usage: 'coolhand [--client-id ID] monitor [--] <command> [args...]',
+        options: [
+            { flag: '--client-id ID', description: 'Use a specific stored client (must come before `monitor`, not after)' },
+            { flag: '<command> [args...]', description: 'The CLI to run and its arguments, e.g. `kimi --resume`' },
+        ],
+    },
     {
         name: 'list-workloads',
         oneLiner: 'List workloads with optional name search and pagination',
@@ -303,6 +352,18 @@ export function peelClientId(argv) {
 export function parseArgs(argv) {
     const flags = {};
     const positional = [];
+    const setValueFlag = (name, value) => {
+        const prev = flags[name];
+        if (REPEATABLE_FLAGS.has(name) && typeof prev === 'string') {
+            flags[name] = [prev, value];
+        }
+        else if (REPEATABLE_FLAGS.has(name) && Array.isArray(prev)) {
+            flags[name] = [...prev, value];
+        }
+        else {
+            flags[name] = value;
+        }
+    };
     let i = 0;
     while (i < argv.length) {
         const arg = argv[i];
@@ -313,14 +374,14 @@ export function parseArgs(argv) {
         if (arg.startsWith('--')) {
             const eq = arg.indexOf('=');
             if (eq >= 0) {
-                flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+                setValueFlag(arg.slice(2, eq), arg.slice(eq + 1));
                 i += 1;
             }
             else {
                 const name = arg.slice(2);
                 const next = argv[i + 1];
                 if (!BOOLEAN_FLAGS.has(name) && next !== undefined && !next.startsWith('-')) {
-                    flags[name] = next;
+                    setValueFlag(name, next);
                     i += 2;
                 }
                 else {
@@ -479,6 +540,9 @@ function getOptimizationOptions(parsed) {
     if (parsed.flags.json === true) {
         opts.json = true;
     }
+    if (parsed.flags.full === true) {
+        opts.full = true;
+    }
     return opts;
 }
 function closeOptimizationOptions(parsed) {
@@ -519,6 +583,15 @@ function updateOptimizationOptions(parsed) {
     }
     return opts;
 }
+/** Flatten a repeatable flag's value(s) into a trimmed list, splitting each on commas. */
+function stringListFlag(value) {
+    const raw = Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
+    const items = raw
+        .flatMap((entry) => entry.split(','))
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return items.length > 0 ? items : undefined;
+}
 function analyzeClaudeSessionsOptions(parsed) {
     const opts = {};
     if (parsed.flags['dry-run'] === true) {
@@ -530,6 +603,23 @@ function analyzeClaudeSessionsOptions(parsed) {
     if (parsed.flags.json === true) {
         opts.json = true;
     }
+    if (typeof parsed.flags.since === 'string') {
+        opts.since = parsed.flags.since;
+    }
+    if (typeof parsed.flags.until === 'string') {
+        opts.until = parsed.flags.until;
+    }
+    if (typeof parsed.flags['projects-dir'] === 'string') {
+        opts.projectsDir = parsed.flags['projects-dir'];
+    }
+    const projects = stringListFlag(parsed.flags.project);
+    if (projects) {
+        opts.projects = projects;
+    }
+    const excludeProjects = stringListFlag(parsed.flags['exclude-project']);
+    if (excludeProjects) {
+        opts.excludeProjects = excludeProjects;
+    }
     return opts;
 }
 function getWorkloadOptions(parsed) {
@@ -618,6 +708,88 @@ function listWorkloadsOptions(parsed) {
     }
     return opts;
 }
+const SENTIMENT_VALUES = new Set(['positive', 'negative', 'neutral']);
+const SORT_BY_VALUES = new Set(['created_at', 'updated_at']);
+const SORT_DIR_VALUES = new Set(['asc', 'desc']);
+function searchFeedbackOptions(parsed) {
+    const opts = {};
+    if (typeof parsed.flags.sentiment === 'string') {
+        if (!SENTIMENT_VALUES.has(parsed.flags.sentiment)) {
+            throw new CliError('INVALID_ARGS', '--sentiment must be one of: positive, negative, neutral');
+        }
+        opts.sentiment = parsed.flags.sentiment;
+    }
+    if (typeof parsed.flags.search === 'string') {
+        opts.search = parsed.flags.search;
+    }
+    if (typeof parsed.flags['creator-id'] === 'string') {
+        opts.creatorId = parsed.flags['creator-id'];
+    }
+    if (typeof parsed.flags['workload-id'] === 'string') {
+        opts.workloadId = parsed.flags['workload-id'];
+    }
+    if (parsed.flags.matched === true && parsed.flags.unmatched === true) {
+        throw new CliError('INVALID_ARGS', '--matched and --unmatched are mutually exclusive');
+    }
+    if (parsed.flags.matched === true) {
+        opts.matched = true;
+    }
+    if (parsed.flags.unmatched === true) {
+        opts.unmatched = true;
+    }
+    if (typeof parsed.flags.since === 'string') {
+        opts.since = parsed.flags.since;
+    }
+    if (typeof parsed.flags['sort-by'] === 'string') {
+        if (!SORT_BY_VALUES.has(parsed.flags['sort-by'])) {
+            throw new CliError('INVALID_ARGS', '--sort-by must be one of: created_at, updated_at');
+        }
+        opts.sortBy = parsed.flags['sort-by'];
+    }
+    if (typeof parsed.flags['sort-dir'] === 'string') {
+        if (!SORT_DIR_VALUES.has(parsed.flags['sort-dir'])) {
+            throw new CliError('INVALID_ARGS', '--sort-dir must be one of: asc, desc');
+        }
+        opts.sortDir = parsed.flags['sort-dir'];
+    }
+    if (typeof parsed.flags['page'] === 'string') {
+        const raw = parsed.flags['page'];
+        const n = parseInt(raw, 10);
+        if (!/^\d+$/.test(raw) || isNaN(n) || n < 1) {
+            throw new CliError('INVALID_ARGS', '--page must be a positive integer');
+        }
+        opts.page = n;
+    }
+    if (typeof parsed.flags['per-page'] === 'string') {
+        const raw = parsed.flags['per-page'];
+        const n = parseInt(raw, 10);
+        if (!/^\d+$/.test(raw) || isNaN(n) || n < 1 || n > 100) {
+            throw new CliError('INVALID_ARGS', '--per-page must be an integer between 1 and 100');
+        }
+        opts.perPage = n;
+    }
+    if (typeof parsed.flags['client-id'] === 'string') {
+        opts.clientId = parsed.flags['client-id'];
+    }
+    if (parsed.flags.json === true) {
+        opts.json = true;
+    }
+    return opts;
+}
+function getFeedbackOptions(parsed) {
+    const id = parsed.positional[0];
+    if (!id) {
+        throw new CliError('INVALID_ARGS', 'get-feedback requires a <feedback-id> argument');
+    }
+    const opts = { id };
+    if (typeof parsed.flags['client-id'] === 'string') {
+        opts.clientId = parsed.flags['client-id'];
+    }
+    if (parsed.flags.json === true) {
+        opts.json = true;
+    }
+    return opts;
+}
 function wildcardOptions(parsed) {
     const complaint = typeof parsed.flags.complaint === 'string' ? parsed.flags.complaint.trim() : '';
     if (!complaint) {
@@ -692,6 +864,20 @@ export async function run(argv) {
         if (argv2[0] === 'claude') {
             return await runClaude({ args: argv2.slice(1), clientId: globalClientId });
         }
+        // `monitor` is a passthrough wrapper too: everything after the wrapped
+        // command's name goes to it verbatim (e.g. `coolhand monitor kimi --resume`).
+        // An optional leading `--` may be used to separate it from `monitor` itself.
+        if (argv2[0] === 'monitor') {
+            let rest = argv2.slice(1);
+            if (rest[0] === '--') {
+                rest = rest.slice(1);
+            }
+            const [command, ...args] = rest;
+            if (!command) {
+                throw new CliError('INVALID_ARGS', 'monitor requires a command to run, e.g. `coolhand monitor -- kimi --resume`');
+            }
+            return await runMonitor({ command, args, clientId: globalClientId });
+        }
         parsed = parseArgs(argv2);
         // Merge a peeled global --client-id if the per-command flag wasn't also supplied.
         if (globalClientId !== undefined) {
@@ -759,6 +945,10 @@ export async function run(argv) {
                 return await runUpdateOptimization(updateOptimizationOptions(parsed));
             case 'wildcard':
                 return await runWildcard(wildcardOptions(parsed));
+            case 'search-feedback':
+                return await runSearchFeedback(searchFeedbackOptions(parsed));
+            case 'get-feedback':
+                return await runGetFeedback(getFeedbackOptions(parsed));
             case 'analyze-claude-sessions':
                 return await runAnalyzeClaudeSessions(analyzeClaudeSessionsOptions(parsed));
             case 'list-workloads':