thinqos-harvest 0.3.0

Mind-as-observer probe — ship Claude Code (and other external) conversations into your thinqOS Mind.

thinqos-harvest

Mind-as-observer probe for thinqOS. Ships every Claude Code session you have into your thinqOS Mind as a captured Episode, so the Mind learns from where you actually do your work — without sitting in the request path.

Pattern: observer, not proxy. The probe runs as a Claude Code Stop hook (fires after every model reply), reads the session JSONL from disk, normalizes it to the public external ingest v1 contract, and POSTs it to /api/ingest/external/v1 on your thinqOS instance. Your Claude Code UX is unchanged.

Install

The hook command (uvx thinqos-harvest hook capture) needs uv on PATH; uvx fetches and runs thinqos-harvest on demand, no separate install step.

curl -LsSf https://astral.sh/uv/install.sh | sh

(If you'd rather install the package globally: pipx install thinqos-harvest and reference it as thinqos-harvest hook capture instead of uvx thinqos-harvest hook capture.)

Wire up

1. Mint an ingest key. Go to https://thinqos.com/api-keys, click Create, copy the tq_... value. (Same key kind as the MCP keys — one key per machine is fine.)

2. Set env vars in your shell rc (~/.zshrc, ~/.bashrc, or equivalent):

   export THINQOS_BASE_URL=https://thinqos.com
   export INGEST_API_KEY=tq_xxxx...
   

   Reload your shell (source ~/.zshrc).

3. Print the hook JSON snippet:

   thinqos-harvest install-hook
   

   Copy the JSON it prints.

4. Paste the snippet into ~/.claude/settings.json under the top-level "hooks" object. Example after pasting:

   {
     "hooks": {
       "Stop": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "uvx thinqos-harvest hook capture",
               "timeout": 30
             }
           ]
         }
       ]
     }
   }
   

   If you already have a Stop hook configured, append our entry to the existing hooks array rather than replacing. install-hook will warn you when this is the case.

5. Smoke test:

   • Start a Claude Code session, type one prompt, exit normally.
   • Run thinqos-harvest list — your session should appear within a second.

CLI

Command	What it does
thinqos-harvest list [--limit N]	List your captured sessions newest-first.
thinqos-harvest forget <session_id>	Delete one captured session by id (irreversible).
thinqos-harvest install-hook	Print the JSON snippet for ~/.claude/settings.json.
thinqos-harvest run	Manual sweep — discover any sessions not yet shipped and POST them. Use for backfill or after a long offline period.
thinqos-harvest hook capture	Hook entry point — reads transcript_path from stdin JSON. You should not run this directly; Claude Code does.

Denylists

Two opt-out layers, both edited at ~/.config/thinqos-harvest/:

• denylist.txt — newline-delimited substrings; any session whose cwd contains a substring is skipped entirely. Example: add personal-taxes to skip captures from ~/Documents/personal-taxes/.
• Content denylist is hard-coded: turns containing .env, api_key=…, sk-…, or matching (api_key|secret|password|token)=<16+ chars> are dropped before POST. Oversized tool_result content (>32KB) is also dropped.

Reliability

• Probe always exits 0; never blocks a Claude Code session even on bug or network failure.
• Failed POSTs spool to ~/.config/thinqos-harvest/pending/<uuid>.json and drain on the next run or hook invocation.
• Server-side dedup keyed by (source, source_external_id); re-shipping the same session is idempotent.

Forgetting a capture

thinqos-harvest forget <session_id>

Where <session_id> is the value thinqos-harvest list shows in the last column (Claude Code session UUID). This deletes the Episode on the server side and cascades to any extracted knowledge.

For a per-turn / per-content scrub (rather than whole-session delete), open an issue on github.com/AI4Outcomes/thinqos — it's a deliberate Phase-A non-goal but ship-able if asked for.

Privacy posture

Opt-out, not opt-in. Adapter ships everything that isn't denied. If you'd rather have explicit opt-in per session, this probe is the wrong tool for you — the design decision is explicit in the spec.

Versioning

Tagged tools/thinqos-harvest-vX.Y.Z in the thinqos monorepo. A push to a matching tag triggers the publish workflow.