thinqos 1.0.2

Connect Claude Code and Codex to your thinqOS Mind.

thinqOS CLI

Mind-as-observer probe for thinqOS. Ships Claude Code and Codex 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 and Codex can call it from Stop hooks; Codex Desktop, VS Code Codex, and Codex CLI can also be swept from the shared ~/.codex session store 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

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 (the only channel Codex honors). 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 or --client codex (default: both, whichever has a config directory).
• 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 or --client codex 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). It prints a capture-only JSON snippet to paste into ~/.claude/settings.json (or ~/.codex/hooks.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.

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 or Codex (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 Codex or Claude Code backfill after a long offline period.
thinqos hook capture [--source SOURCE]	Hook entry point - reads transcript_path from stdin JSON. You should not run this directly; Claude Code and Codex 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 or Codex 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.