cxs

cxs

Use cxs to search old agent conversations in its own SQLite index. The current public CLI source has codex and experimental claude-code；find When --source is omitted, search defaults to across public sources; during normal agent use, do not first ask the user to choose a source.--source codex / --source claude-code is only for user-specified, narrowing scope, or diagnostics.claude-code is now public fixed-command support, but is still an experimental transcript-reader contract; do not describe it as a stable raw JSONL promise, and when encountering semantic gaps for non-text records, do not jump back to the raw source root to obtain evidence. Each source's raw sessions are only ingest sources; normal history retrieval only reads the cxs index. Core approach:First choose the retrieval primitive, then locate the candidate session, and finally use the cxs read command to get content evidence。

Installation (two steps)

1. Install the cxs CLI(this skill does not include the CLI package, it is just an agent workflow):

See the README's CLI Install Guide. After installation, do a sanity check once:

"${CXS_BIN:-cxs}" --version       # 应输出 cxs 版本号
"${CXS_BIN:-cxs}" --help          # 应列出 status/sync/find/read-range/read-page/list/stats
"${CXS_BIN:-cxs}" status --help   # 若显示 --source <id>,应列出 codex|claude-code

If cxs is not in PATH, set export CXS_BIN=/absolute/path/to/bin/cxs. If the installed version status --help does not have --source, it means the CLI predates source-aware behavior; omit source flags, or first update to a CLI release that includes that behavior.

2. Install the skill:

# Codex agent runtime
npx skills add catoncat/cxs --full-depth --skill cxs -g -a codex -y

# 其他 agent runtime — 把 -a codex 换成对应 runtime,或省略

-a The value depends on the target agent runtime,installing to the wrong slot will make the skill invisible. This only installs the skill in the corresponding agent runtime; it does not mean cxs supports that runtime's session source. After installation, the agent usually needs to be restarted / a new session opened.

First choose the retrieval primitive

Do not treat status -> sync -> find/list -> read as a fixed starting move. First determine which primitive the user actually needs:

User needs	Starting primitive	Evidence rules
metadata projection: earliest/latest, counts, distribution, cwd/session list, large sessions, time sorting	Read-only SQLite/bash/jq query of the cxs index's sessions table; use list as an aid if necessary	Only stable metadata can be projected; any content judgment must again read-page / read-range
semantic recall: topics, keywords, "has X been discussed before", local machine configuration archaeology	cxs find <query> --json, defaults to across public sources; include --cwd / --root / --selector / --sort ended	Use find to recall candidates, then use the sessionRef in the results to do read-range or read-page verification
context reading: known sessionUuid / sessionRef, hit seq, or need to expand context	cxs read-range <sessionRef> --seq/--query [--before N --after M] or cxs read-page <sessionRef>	content evidence only comes from read-* output
coverage/freshness/index availability: index missing, coverage stale, need to decide whether to sync	cxs status --json / status --cwd / status --selector	status does not answer content questions, only determines coverage and sync needs
mutation: build index or update coverage	cxs sync --cwd/--root/--selector	Do not use --prunefor ordinary retrieval; use it only when the user explicitly asks to clean up old index records for sources that have disappeared

In versions that support the source-aware CLI, all fixed commands can take --source <id>; the current public CLI supports codex and experimental claude-code。find Omitting --source is equivalent to searching across public sources, and explicit --source all also works; for other commands, omitting source is still handled according to the Codex-compatible default. When encountering unsupported_source, indicating the source id is unknown; do not switch to the raw source root. Claude Code support has been made public, but it is still experimental transcript-reader support; if the installed version directly reports unknown option --source, it is an old CLI; omit the source flags or update the CLI.

find / list Returning zero results is not an end condition. When encountering zero results, the user saying "there should be", the question involving the recent/current repo, or the JSON containing nextAction , you must first perform a coverage check over the same scope:

1. status --cwd <path> --json / status --root <dir> --selector '<json>' --json
2. If requestedCoverage.recommendedAction === "sync", run over the same scope sync --cwd / sync --root / sync --selector
3. then retry with the same selector find / list; only if there are still no results under fresh coverage should you say nothing was found

Read-only SQLite is only allowed to query cxs's own index; do not query Codex raw JSONL or other source roots. Stable session metadata fields are limited to:source_id, native_session_id, session_key, session_uuid, started_at, ended_at, cwd, title, summary_text, message_count, source_root, file_path。

Counterexamples(should use another tool):

• Current repo code/string search → code search tool
• Reading the current file or a known path → file read tool
• External documentation/web pages → WebFetch / WebSearch
• Asking only about current live state and with no historical configuration semantics → runtime/file check; but if the question carries semantics of "was configured/previously/what configurations exist on this machine", first use cxs to find historical clues, then verify live truth
• Today's commits/daily report → commit-daily-summary
• Current session wrap-up → session-wrap

Workflow principles

• The cxs index is the historical retrieval source of truth; bash/sqlite/jq are only cheap projection/orchestration, not the content evidence layer
• status is not a universal first step; only use it first for coverage/freshness/index availability/source inventory questions
• find is used for semantic recall; do not force metadata-only questions through full-text search
• read-range / read-page is the content evidence layer; before answering "what was said/what was decided at the time" you must read the content
• sync only writes/updates the SQLite index and coverage; lookup itself does not require sync. Only when the target scope's coverage is missing or stale do you sync --cwd <path> / sync --root <dir> / sync --selector
• sync By default, retain already-indexed history; after raw JSONL disappears from the source snapshot, do not guide the user to query another root. Only use it when the user explicitly wants cxs to discard old records that have already disappeared from the source sync --prune
• Use status --cwd <path> --json or status --selector '<json>' --json to check the target scope;requestedCoverage.recommendedAction === "query" query directly,"sync" only then sync
• stats.sessionCount many does not mean the target scope has source-aware complete coverage; fresh {"source":"codex","kind":"all",...} coverage can cover the cwd/date sub-selectors under the same source/root
• "latest/recent + keyword" do not directly treat the default find results as latest; use find <query> --cwd <path> --sort ended or find <query> --root <dir> --sort ended, and if necessary --exclude-session <current_uuid> exclude the current session/self-hit. If the user explicitly limits to Codex or Claude Code, then add --source <id>。
• For questions mixing natural language + English technical terms, you can first directly find the original sentence; when strict recall is 0, the new CLI conservatively extracts ASCII technical terms for one relaxed recall. Still use read-range / read-page to verify the content; do not draw conclusions based only on hit titles.
• find --json results include sourceId and sessionRef; for subsequent read, prefer directly using sessionRef. Do not guess the source from the uuid yourself.
• matchSource = "session" when matchSeq = null; for such hits first read-page sample,do not fabricate read-range --seq
• User gives cwd but sync status is uncertain → status --json; after confirming the absolute cwd, run status --cwd <path>; only if missing/stale, then sync --cwd <path>
• find --json / list --json when there are zero results, look at nextAction: it is a machine-readable hint that prevents the agent from giving up. Follow the hint to choose/check the selector, sync if necessary, and retry.
• cwd is only candidate filtering, not topic truth; you also need to look at title、summaryText, the first few messages
• the same topic may have multiple uuids; choose by cwd / startedAt / matchCount , do not deduplicate by guessing from the title

Result recap (to the user, restrained)

cxs tool output is usually collapsed in the conversation, and only you (the agent) can see it. When the following conditions are met, youmustinclude a restrained one-line efficiency footnote in the recap so the user perceives "fast / economical"; but never spam, and never induce yourself to read less.

• Only when the answer is indeed compressed into onescaledcxs investigation (the retrieval corpus is at scale, or spans multiple sessions / multiple reads), append to the end of the substantive answerat most one sentenceof efficiency footnote.
• Anchor the wording to thereal measured valuesin the CLI header: retrieval coverage scale (find's "searched ~N records"), the actual number of records read (sum of each read's "read K records"), end-to-end elapsed time (each Xms roughly summed). Template:（从 ~N 条历史里用 ~Yms 定位，读了 Z 条）。
• If it spans multiple calls, roughly sum the read count and ms, report only the order of magnitude, do not pretend to be precise。
• Do not report a fabricated "saved X%". "Saving" speaks for itself through the gap between two real numbers (how many records were read out of 170,000), do not attach an estimated denominator.
• Neverappend an efficiency footnote on zero results / coverage-miss / single direct lookup—saying "saved" when nothing was found, or when nothing was actually saved, is shooting yourself in the foot.
• This sentence isan answer footnote for the user to see, and is a different thing from the "post-use self-assessment" below (internal reflection, not output to the user) ; do not mix them up.
• Efficiency recap is on by default. If the user finds it noisy, they can set CXS_STATS=0(or off) to turn off the annotations in the CLI header; then there is no "searched ~N records / read K records / Xms" in the text to anchor to,do not hardcode numbers, just omit the efficiency footnote (--json 's scannedMessageCount / elapsedMs is unaffected).

Post-use self-assessment

After each answer with cxs, do a lightweight self-assessment; do not output this long passage to the user, only briefly expose the conclusion when there is a problem.

This self-assessment and $cxs-dogfood are a paired workflow:cxs only discovers and hints at recordable cases,cxs-dogfood is responsible for interactive collection, writing to the private golden, running eval, and generating the fix handoff.

Determine which category this result belongs to:

• good: the found session/cwd/time/context can support the answer.
• query-refine: the first query was not ideal, but it was solved through normal usage such as changing keywords, selector,--sort ended、--exclude-session , etc.
• coverage-issue: the problem comes from missing/stale index or selector not covering it; you should explain that status --cwd / sync --cwd / sync --root / status --selector / sync --selectoris needed, do not attribute it to ranking.
• skill-guidance-issue: the cxs CLI is not wrong, the agent did not use it according to the skill workflow, for example treating the default find as the latest, fabricating read-range --seq, skipping the selector.
• dogfood-candidate: There are still reproducible cases that do not meet expectations, such as recall miss, obvious misranking, incorrect context window, and session hit/message hit behavior that make it hard for the agent to use reliably.

If it is dogfood-candidate：

1. Do not automatically write a private golden;cxs-dogfood it can only be explicitly triggered by the user.

2. Give the user a prompt they can directly confirm, for example:

   这次像是 cxs dogfood candidate：<一句话原因>。如果要记录，直接说 `$cxs-dogfood 记录这个 case`。
   

3. Keep enough handoff clues in the current reply: the original query, the actual top1/competing items, the expected session/cwd, or the missing context phrase.

4. If the user then says "record/add it in/yes, record this case", treat it as an explicit trigger of cxs-dogfood, and that skill will interactively complete and verify it.

5. Do not continue designing the fix plan inside the cxs skill; after recording is complete, "whether to start the fix / output handoff" is handled as the closing step by cxs-dogfood .

Prerequisites

• If it is only metadata projection, read the cxs SQLite index first; there is no need to run full-text find
• If it is only semantic recall, first find; when the target coverage is unclear or it returns index_unavailable then use status
• Only when coverage/freshness/index availability is needed, first status --json or status --cwd <path> --json / status --selector '<json>' --json
• If the index does not exist, the read command returns index_unavailable, or requestedCoverage.recommendedAction === "sync" → sync --cwd <path> / sync --root <dir> / sync --selector '<json>'
• sync defaults to strict mode; only add --best-effortif the user accepts partial success; best-effort does not write complete coverage
• sync --prune is an explicit cleanup action, and will delete old index records in the selected source that have disappeared; do not add it for ordinary historical queries and daily incremental synchronization
• When invoking from another cwd, if the default db is wrong, explicitly pass --db

Reference

Detailed command surface, fields, flows, error handling:

• references/cli-surface.md — options + Example for each subcommand
• references/progressive-workflow.md — 4 worked scenarios
• references/json-schema.md — complete JSON fields
• references/failure-cookbook.md — quick reference for error symptoms / --json quick reference for error shape
• references/advanced-queries.md — query semantics / read-only SQLite metadata projection / CJK behavior

skill-sync: distributable cxs skill package, zero-result coverage retry workflow, 2026-06-02