Metadata-Version: 2.4
Name: thinqos
Version: 1.4.1
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, Grok Build, and VS Code (Copilot agent host) 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, Grok Build, and VS Code 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 --link-mode=copy thinqos install --pat tq_xxxx... --repair
```

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

```bash
uvx --link-mode=copy thinqos install --client grok --pat tq_xxxx... --repair
```

VS Code's native **Agents** panel (Copilot Chat / Copilot CLI agent mode - not
the Claude Code or Codex *extensions*, which are wired via `--client claude` /
`--client codex`) is a separate client, wired on its own:

```bash
uvx --link-mode=copy thinqos install --client vscode --pat tq_xxxx...
```

This registers thinqOS as an MCP server in VS Code's own `User/mcp.json` AND
wires capture/reflexive-retrieve/resume hooks into the **workspace**
`.claude/settings.json` the Copilot agent host reads (verified by live
inspection of a real agent session). Run it from the repo you want captured.
`--client vscode` is included in `all`.

`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`,
  `--client grok`, or `--client vscode`. The default `both` remains Claude+Codex
  for compatibility; `--client all` includes Grok Build and VS Code.
- 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`, `--client grok`, or `--client vscode`
to remove only one integration. For VS Code it removes the workspace capture
hooks and the managed `thinqos` entry from the native user-level `mcp.json`. 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.

## VS Code (Copilot agent host)

`install --client vscode` wires thinqOS into VS Code's native Copilot agent host
(the Agents panel - a distinct client from the Claude Code and Codex
*extensions* that also run inside VS Code, which are wired separately via
`--client claude` / `--client codex` into `~/.claude` / `~/.codex`). VS Code
reads the **workspace** `.claude/settings.json` in the Claude hook format
(verified by live inspection), so the installer writes managed
capture/incremental/reflexive-retrieve/resume hooks there rather than to a
global file, and registers the remote thinqOS MCP server in VS Code's native
user-level `mcp.json`:

- macOS: `~/Library/Application Support/Code/User/mcp.json`
- Windows: `%APPDATA%\Code\User\mcp.json`
- Linux: `~/.config/Code/User/mcp.json`

The adapter reads the Copilot session store under
`~/.copilot/session-state/<session-id>/events.jsonl`
(`%APPDATA%\Copilot\session-state` on Windows), keying the session id from the
directory name and converting the host's camelCase `transcriptPath` hook payload
to the same capture path Claude uses.

Because the wiring lives in the workspace `.claude/settings.json`, run
`install --client vscode` from the repo root you want connected (the installer
walks up for `.git` to find the workspace root). It is safe to re-run: managed
hooks are detected and migrated, and unrelated MCP servers already in
`mcp.json` (e.g. `github/github-mcp-server`) are preserved.

`uninstall --client vscode` removes the workspace capture hooks and the
`servers.thinqos` entry from `User/mcp.json`, leaving any other MCP servers you
have registered untouched.

For a one-time backfill of past VS Code sessions in the current workspace:

```bash
thinqos run --sources microsoft.com/vscode_copilot --since 2026-08-01T00:00:00 --batch-size 5
```

## 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, Grok Build, or VS Code 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.
