Metadata-Version: 2.4
Name: thinqos
Version: 1.3.0
Summary: Connect Claude Code, Codex, and Grok Build to 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.4
Requires-Dist: httpx>=0.28
Description-Content-Type: text/markdown

# thinqOS CLI

Mind-as-observer probe for [thinqOS](https://thinqos.com). Ships Claude Code,
Codex, and Grok Build sessions into your thinqOS Mind as captured Episodes, so
the Mind learns from where you actually do your work - without sitting in the
request path.

Pattern: **observer, not proxy.** The probe reads 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. Claude Code,
Codex, and Grok Build can call it from native hooks; their local session stores
can also be swept for backfill.

## Install

The hook command needs [uv](https://docs.astral.sh/uv/) on PATH:

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

Verify the install works:

```bash
uvx thinqos --help
```

## Wire up

One command makes thinqOS your default memory across Claude Code **and** Codex:

```bash
uvx thinqos install --pat tq_xxxx... --repair
```

Add Grok Build too with `--client all`, or wire it alone with:

```bash
uvx thinqos install --client grok --pat tq_xxxx... --repair
```

`install` does five things, idempotently:

1. **Installs the thinqOS command** and wires hooks to
   the installed binary by absolute path - so a stale `uvx` cache never pins an
   old version, and a daily `uv tool upgrade` keeps it current.
2. **Wires the memory hooks** - **capture** (after each session), **incremental
   capture** (debounced mid-session snapshots at PostToolUse, so a mid-turn
   crash still lands the work), **reflexive retrieve** (before each turn),
   **resume** ("where you left off" at session start), and **self-update** (the
   daily background upgrade).
3. **Bootstraps your existing native memory** into the Mind in the **background** -
   the per-fact Claude memory files and the legacy Codex `MEMORY.md`, as durable
   native-memory Mind sources. The server queues extraction for the worker, so
   `install` spawns a detached drain that stores them in parallel and returns
   immediately; progress is logged to `~/.config/thinqos/import.log`. A
   content-hash manifest makes it resumable; server-side source IDs make imports
   idempotent; `--no-import-memory`
   skips it. Run `thinqos import-memory` anytime to drain or resume.
4. **Adds a write-redirect** so your agents persist *new* durable learnings into
   thinqOS: a one-line reminder in Claude's recall block, and a marker-delimited
   block in `~/.codex/AGENTS.md` and `~/.grok/AGENTS.md`. After this,
   native memory should contain only always-fire hard rules; thinqOS
   `search_mind` + `recall_mind` are the durable memory source of truth.
5. **Verifies the product contract** with `doctor`: managed hooks, Claude MCP
   registration, required Mind tools (`search_mind`, `recall_mind`, `consult_mind`, `observe`,
   `believe`), replay queue, server captures, installed binary, and auto-update
   status.

- **Mint a key** at <https://thinqos.com/api-keys> (*Create* -> copy the
  `tq_...`). Already connected the thinqOS MCP server? Omit `--pat` and the key
  is read from that registration.
- Scope to one client with `--client claude`, `--client codex`, or
  `--client grok`. The default `both` remains Claude+Codex for compatibility;
  `--client all` includes Grok Build.
- Add `--repair` when installing or re-running setup. It prints local health
  guidance and drains at most 25 queued replay payloads, so a stale offline queue
  cannot unexpectedly flush an unbounded backlog.
- **Safe to re-run.** Existing thinqOS hooks are detected, migrated, and never
  duplicated; your other hooks (coordinator, etc.) and AGENTS.md content are left
  untouched.
- Needs [uv](https://docs.astral.sh/uv/) on PATH (the same `uv`/`uvx` you used to
  run this command).

Open a new session (or restart your agent) and it will auto-capture, reflexively
retrieve your Mind/corpus, consult the Mind for high-stakes work, and greet you
with where you left off.

**Smoke test:** start a session, type one prompt, exit normally, then run
`uvx thinqos doctor` - it should show managed Claude hooks, the thinqOS
MCP registration, replay queue depth, and recent server captures without
printing your key. The final `health:` line should be `pass` or explain the
specific repair step.

## Repair, health, and uninstall

Repair is safe to run any time:

```bash
thinqos install --client claude --repair
thinqos doctor
```

`--repair` migrates stale managed hooks, refreshes the installed package path,
preserves unknown hand-authored hooks, and drains at most 25 queued replay
payloads so an old offline queue cannot unexpectedly flush without bounds.

Doctor is the local source of truth for install health:

```bash
thinqos doctor
```

It prints the installed version/binary, auto-update status, hook inventory, MCP
registration, required Mind tool availability, last hook status, replay queue by
source, and recent server captures. It ends with `doctor_checks:` and `health:`.

Uninstall removes local managed integration artifacts only:

```bash
thinqos uninstall --client claude
```

By default it removes managed Claude hooks and the `thinqos` Claude MCP
registration, preserves hand-authored hooks, preserves logs and queued replay
payloads under `~/.config/thinqos/`, and does **not** delete existing
server-side captures or Mind knowledge. Add `--dry-run` to preview changes,
`--remove-state` to delete local logs/queue/manifest, or `--remove-foreign-hooks`
only when you intentionally want to remove custom thinqOS hooks too.

## Fresh-machine continuity

On a second computer, run the same install command with an observer key for your
identity, restart Claude Code, and run `thinqos doctor`. thinqOS remains
the durable source of truth; local native memory is only for always-fire hard
rules. The session prime and resume hooks retrieve relevant Mind/project context
from thinqOS so Claude Code can continue from your accumulated history.

## Uninstall

Remove the managed local hooks with:

```bash
thinqos uninstall --client both
```

Use `--client claude`, `--client codex`, or `--client grok` to remove only one
integration. The
uninstaller removes hooks previously emitted by `thinqos install`,
recognized legacy thinqOS wrapper hooks, and the managed Codex write-redirect
block from `~/.codex/AGENTS.md`. It preserves unrelated hooks and unrecognized
hand-curated thinqOS wrapper commands so it does not destroy local automation
you wrote yourself.

This is local cleanup only. It does not delete server-side captures, revoke API
keys, or forget extracted knowledge. Use `thinqos forget <session_id>`
for captured sessions and revoke the observer key in thinqOS if the machine
should no longer connect. Add `--remove-tool` to remove the local `thinqos`
command too.

### Manual wiring (advanced)

To hand-place the hooks instead, set `THINQOS_BASE_URL` and `INGEST_API_KEY` in
your shell rc, then run `uvx thinqos install-hook` (add
`--source openai.com/codex` for Codex or `--source x.ai/grok_build` for Grok
Build). It prints a capture-only JSON snippet to paste into
`~/.claude/settings.json`, `~/.codex/hooks.json`, or
`~/.grok/hooks/thinqos.json` under the
top-level `"hooks"` object, and warns rather than overwriting an existing `Stop`
hook.

## Codex

`install` already wires Codex. Codex Desktop, VS Code Codex, and Codex CLI write
rollout JSONL files under `~/.codex/sessions/YYYY/MM/DD/`; older files may live
under `~/.codex/archived_sessions/`. The Codex adapter reads both locations.
Codex passes the current `transcript_path` to the hook; the hook uploads the
completed turn and exits 0 so it does not block Codex.

For a one-time backfill of past Codex sessions, run:

```bash
thinqos run --sources openai.com/codex --since 2026-05-01T00:00:00 --batch-size 5
```

Prefer a bounded backfill such as the last 7 days. `run` chunks uploads by
default so large local histories do not exceed server request limits.

For a one-shot run without installing the package globally:

```bash
THINQOS_BASE_URL=https://thinqos.com \
INGEST_API_KEY=tq_xxxx... \
uvx thinqos run --sources openai.com/codex --since 2026-05-01T00:00:00 --batch-size 5
```

Omit `--sources` to sweep all registered adapters.

## Grok Build

`install --client grok` uses Grok Build's native integration points. It writes
managed hooks to `~/.grok/hooks/thinqos.json`, registers the remote thinqOS MCP
server in `~/.grok/config.toml`, and adds the managed durable-memory block to
`~/.grok/AGENTS.md`. The adapter discovers session updates under
`~/.grok/sessions/<encoded-workspace>/<session-id>/updates.jsonl` and uses the
adjacent `summary.json` for stable metadata.

The first source-specific capture is the connection proof. Merely installing a
shared API key does not mark Grok Build connected. Native Grok memory import is
not currently performed; the normal prime, recall, observe, and capture paths
provide continuity after setup.

Grok Build ignores stdout from passive lifecycle hooks, so the installer does
not add ineffective `prime` or `resume` hooks. Recall is instead driven by the
managed `AGENTS.md` instructions calling the registered thinqOS MCP tools.
Capture and incremental-capture hooks run detached and resolve the session from
Grok's runner-provided `GROK_SESSION_ID`, keeping them off the interactive UI
path.

## CLI

| Command | What it does |
| --- | --- |
| `thinqos install [--client ...] [--no-import-memory] [--repair]` | One-shot setup: install the tool, wire hooks, bootstrap legacy native memory, add the write-redirect. Safe to re-run; `--repair` drains up to 25 queued replay payloads. |
| `thinqos uninstall [--client ...] [--remove-tool] [--remove-state] [--dry-run]` | Remove managed local hooks/MCP config safely. Preserves hand-authored hooks and server-side captures by default. |
| `thinqos import-memory [--concurrency N] [--dry-run] [--claude-limit N] [--codex-limit N]` | Queue legacy native Claude/Codex memory as durable Mind sources, most-recent first, `N` in parallel (default 5). Idempotent server-side and resumable by content-hash manifest; `0` limit = all pending. |
| `thinqos list [--limit N]` | List your captured sessions newest-first. |
| `thinqos forget <session_id>` | Delete one captured session by id (irreversible). |
| `thinqos install-hook [--source SOURCE]` | Print the JSON hook snippet for Claude Code, Codex, or Grok Build (advanced manual wiring). |
| `thinqos run [--sources SOURCE] [--since TIMESTAMP] [--batch-size N] [--no-drain-pending]` | Manual sweep - discover any sessions not yet shipped and POST them in chunks. Use for bounded coding-client backfill after a long offline period. |
| `thinqos hook capture [--source SOURCE]` | Hook entry point - resolves the native session from stdin JSON. You should not run this directly; coding-client hooks do. |
| `thinqos hook capture-incremental [--source SOURCE]` | Hook entry point - mid-session snapshot wired at PostToolUse, debounced per session (`THINQOS_INCREMENTAL_MIN_INTERVAL_S`, default 90s) and shipped non-final. Fail-open; do not run directly. |
| `thinqos hook self-update` | Hook entry point - daily-gated background update. Wired at SessionStart; do not run directly. |
| `thinqos doctor` | Prove authenticated thinqOS MCP connectivity and the SLA independently from hook/replay health; exits non-zero only when connectivity fails. |

## Denylists

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

- **`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

- Hook capture always exits 0; never blocks a Claude Code, Codex, or Grok Build session even on bug or network failure.
- Hook health is written to `~/.config/thinqos/status.json`; detailed hook output goes to `~/.config/thinqos/hook.log`.
- Failed POSTs spool to `~/.config/thinqos/pending/<uuid>.json` and drain on the next `run` by default. Use `--no-drain-pending` for a tightly scoped backfill.
- Server-side dedup keyed by `(source, source_external_id)`; re-shipping the same session is idempotent. Claude Code captures include a monotonic `session_revision` so a later hook can replace an earlier partial capture.

## Forgetting a capture

```bash
thinqos forget <session_id>
```

Where `<session_id>` is the value `thinqos list` shows in the last column. This deletes the Episode on the server side and cascades to any extracted knowledge. For Codex captures, pass `--source openai.com/codex`.

For a per-turn / per-content scrub (rather than whole-session delete), contact support. 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-vX.Y.Z` in the thinqos monorepo. A push to a matching tag triggers the publish workflow.
