thinqOS CLI

Mind-as-observer probe for thinqOS. 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, 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.

Cognitive contract

The installed CLI writes a versioned thinqOS cognitive contract into persistent Codex guidance. It selects prime_mind for cheap ambient context, recall_mind for a normal focused lookup, search_mind for the widest Mind-only search, conversation_search for dated evidence, and conversation_aggregate for counts. It asks consult_mind before consequential work.

Capture only durable user decisions, corrections, and verified outcomes with their source and user-versus-assistant attribution. observe confirms a durable source record and may queue extraction. A queued extraction is not a learning receipt. believe is reserved for a user-confirmed fact that must be available immediately.

The server exposes its source text, version, and SHA-256 receipt through mind_describe().cognitive_contract. Marketplace/plugin maintainers should compare that version and checksum before copying the text into a host-specific skill. A changed checksum requires review; do not assume an MCP client refreshes tool descriptions automatically after a server deployment.

Install

The hook command needs uv on PATH:

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

Verify the install works:

uvx thinqos --help

Wire up

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

uvx --link-mode=copy thinqos install --pat tq_xxxx... --repair

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

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:

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.local.json the Copilot agent host reads (verified by live inspection of a real agent session). Note settings.local.json, NOT settings.json: the shared file is git-tracked in every AI4O repo, and writing there committed machine-absolute paths and made every hook fire twice. Run it from the repo you want captured. --client vscode is included in all.

All four targets use the same persistent thinqos installation. The installer does not install four copies: it registers that one binary in each client's native MCP and hook configuration. ChatGPT is not a local installer/capture target; its app does not use this CLI registration path.

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. Managed SessionStart hooks check at most once per 24 hours and launch uv tool install --upgrade --link-mode copy thinqos in the background; the next process/session uses the upgraded version.
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://app.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 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.

Automatic updates apply to managed installations while a wired client is being used. They are deliberately fail-open: an offline machine or missing/broken uv never blocks an agent session. A client that is never started, a machine whose managed SessionStart hook was removed, or a hand-wired installation is not guaranteed to update. doctor reports the latest update attempt it can observe; restart the client after an update so the next process loads the new version.

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.

For another client, select it explicitly, for example:

thinqos doctor --client vscode

Repair, health, and uninstall

Repair is safe to run any time:

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:

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:

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:

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.

Codex hooks live in ~/.codex/hooks.json. Codex requires a manual trust decision for a changed hook configuration: when thinqos install reports a Codex hook change, open Codex, run /hooks, and trust User config. A routine reinstall does not rewrite an unchanged hooks.json, so it preserves existing trust.

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

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:

THINQOS_BASE_URL=https://app.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). The host reads workspace hook sources including .claude/settings.local.json; thinqOS writes its managed capture/incremental/reflexive-retrieve/resume hooks to the Copilot-only .github/copilot/settings.local.json so they cannot double-fire inside Claude Code. It 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 .github/copilot/settings.local.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:

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

CLI

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

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.

Versioning

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