thinqos 1.3.0

Connect Claude Code, Codex, and Grok Build to your thinqOS Mind.

thinqOS CLI

Mind-as-observer probe for thinqOS. 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, 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 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 thinqos install --pat tq_xxxx... --repair

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

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

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, 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:

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://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

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.