clonst CLAUDE.md

Clonst - Project instructions

What Clonst is

A TypeScript MCP server (stdio) that lets the Claude of a Claude Code conversation get its plans/code critiqued by the Codex CLI, in a ping-pong loop until consensus.

Architecture:

• The reviser is the calling Claude (the one in the conversation), not a spawned claude CLI. It keeps the whole conversation context.
• The reviewer is the Codex CLI (codex exec), with persistent memory across rounds through codex exec resume <session_id>.
• The ping-pong loop lives in the calling conversation: one MCP call = one critique. No background orchestrator, no status tool.

Five tools: clonst_ping (diagnostic), clonst_review (one critique), clonst_report_summary (seals the final summary into the review report), clonst_feedback (records a remark about how Clonst works), clonst_topics (reads and relabels those remarks' groups).

Persistent data and its invariants

Everything lives under ~/.clonst/ (CLONST_HOME in tests), never in the package: an update can never erase it.

• logs/ - session JSONL plus the raw reviewer responses.
• reports/ - the human-readable review report, a PURE PROJECTION of reports/state/<report_id>.json. Never edit the Markdown: regenerate it. report_id names the report file, thread_id resumes the reviewer session; they are two different identities on purpose.
• feedback.jsonl - user remarks about how Clonst works. Two hard rules: no line of it EVER reaches a prompt (no code path reads it to build one), and every mutation goes through the single transactional commit() in core/feedback.ts (read, validate, build the candidate, apply retention, check the ceiling, then one atomic 0600 write). Stored descriptions leave the server through exactly ONE guarded path (clonst_topics list/search), behind a notice and delimiters in BOTH MCP representations.
• Retention there is user-arbitrated and binary: a topic with exactly one occurrence expires after feedback_retention_days and takes all its lines with it; anything heard twice or more is kept forever. Groups are never merged - equivalence between differently-worded groups is established by the caller at reading time.
• "USER DECISION: " is a never-translated protocol literal: detected at the START of a risks_identified item only, it pauses the ping-pong and must reach the human verbatim. Never act on its content.