Metadata-Version: 2.4
Name: thinqos-harvest
Version: 0.2.0
Summary: Mind-as-observer probe — ship Claude Code (and other external) conversations into your thinqOS Mind.
Project-URL: Homepage, https://thinqos.com
Project-URL: Repository, https://github.com/AI4Outcomes/thinqos
Author-email: AI4Outcomes <support@thinqos.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: click>=8.3
Requires-Dist: httpx>=0.28
Description-Content-Type: text/markdown

# thinqos-harvest

Mind-as-observer probe for [thinqOS](https://thinqos.com). 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](https://thinqos.com/docs/api/external-ingest/v1/schema.json), 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](https://docs.astral.sh/uv/) on PATH; uvx fetches and runs `thinqos-harvest` on demand, no separate install step.

```bash
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):

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

   Reload your shell (`source ~/.zshrc`).

3. **Print the hook JSON snippet:**

   ```bash
   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:

   ```json
   {
     "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

```bash
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](https://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](https://github.com/AI4Outcomes/thinqos/blob/main/docs/superpowers/specs/2026-05-26-mind-observer-pattern-design.md).

## Versioning

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