Auto-claude-code-research-in-sleep Documentation

Technical Documentation: wanshuiyin/Auto-claude-code-research-in-sleep

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Auto-claude-code-research-in-sleep (ARIS ⚔️🌙)

· · · · · · · · 💬 Join Community ·

🌱 ARIS is a methodology, not a platform. What matters is the research workflow — take it wherever you go.

💡 *Use ARIS as a skill-based workflow in Claude Code / Codex CLI / Cursor / Trae / Antigravity / GitHub Copilot CLI / OpenClaw / DeepSeek Harness — enjoy any way you like!*The executor drives, an independent model (Codex MCP by default) reviews. Alternative model combinations, including ModelScope-hosted models, need no Claude or OpenAI API.

📦 Those are the skills installed directly. Want it in one command? ARIS also ships as a standalone CLI and as plugins: · · ·

❗ codex-cli 0.154.0 removed codex mcp-server — the entry point every ARIS reviewer call used. No impact on ARIS: the codex MCP server is now ARIS's own bridge over codex exec (mcp-servers/codex-exec/), same tools, same results, all 82 skills unchanged, ultra and per-thread resume intact. One re-registration is all it takes — already installed? → Quick Start step 2b · new install → step 2 · what changed.

🧩 The ARIS family — same method, other jobs. One line each; the details live in their own repos.

— EasyAIOffer: 34 bilingual ML / LLM interview cheat sheets on one page — derivations, from-scratch PyTorch, 25 questions each. 希望大家秋招轻松一点 🌱

· — two sides of one disease. HERO: a ~550-token block for CLAUDE.md / AGENTS.md against the four shapes agents over-defend in (Hashing, Edge cases, Rubrics, Overbuild), bounding what the agent proposes, never what it looks for. Anti-Autoresearch: 61 integrity signals into a deterministic, reviewer-ready report — fabrication forensics, not an AI-text detector.

— ARIS goes multimodal: a rough story in, a movie told in still frames out, every scene checked by another model; the same loop draws clean method diagrams (/method-figure).

— a tiny always-on-top macOS widget that lights up 🔴 when a session waits for your approval; cd aris-monitor && ./run.sh. Many windows? Claude Fleet by @tianyilt is the full dashboard.

🔥 ARIS-Code CLI — 独立安装版 · English | ⬇️ Download · — v0.4.28: ARIS_REASONING_EFFORT works on the Anthropic channel, tool calls through {}-placeholder relays fixed, OS proxy honoured. v0.4.27: launching and quitting the REPL leaves no empty session file. v0.4.26: the fable alias and /model now point at Fable 5.1 (default stays Opus 5). v0.4.25: the Codex reviewer works again on codex-cli ≥ 0.154 (built-in codex exec bridge, nothing to register), /since takes you back to your last input, /resume lists sessions by index, Windows multi-line paste fixed (pending confirmation), 83 bundled skills on GPT-6-Astra.

ARIS-Code — screenshot, what's in v0.4.28, per-release details, older versions

📰 ARIS-Code v0.4.28 (2026-09) — latest: ARIS_REASONING_EFFORT works on the Anthropic channel (#446), tool calls through relays that send a {} placeholder no longer fail (#444), and the OS proxy on Windows / macOS is used without exporting HTTPS_PROXY (#401). v0.4.27: launching and quitting the REPL no longer leaves an empty session file, and /resume lists only sessions with messages (#439 follow-up). v0.4.26 made Fable 5.1 the fable alias and the first /model entry (the default executor stays Opus 5). v0.4.25 is the reviewer-bridge release: codex-cli 0.154 removed codex mcp-server, so every Codex review from ARIS-Code died on an updated codex. The reviewer now runs over a built-in codex exec bridge — no mcpServers.codex entry, old entries migrate in memory, thread records interoperate with ARIS's Python bridge. Also: /since replays everything after your last input (folded like the live display, /since full for complete output), /resume lists sessions with indices and shows where you stopped (#439), Windows multi-line paste no longer submits line by line (#430, pending confirmation), the Windows shim message carries the native installer (#428), and the bundle moves to 83 skills on GPT-6-Astra. Recent headliners: v0.4.24 — Claude 5 model refresh (Opus 5 default, Fable 5 tier, availability chain) and v0.4.23 — output folding. Caps a 24-release run (v0.4.5 → v0.4.28); per-release detail below. Credits: @GetIT-Sunday, @Anduin9527, @GO-player-hhy, @Jxy-yxJ, @screw-44, @StevenUST, @opposj, @ShijunLei-cn, @algojogacor, @YukinoshitaLove, @jinliye-2026, @SajimJC, @JasmineLCY.

Per-release details (v0.4.5 → v0.4.28)

v0.4.28 (2026-09-28) — ARIS_REASONING_EFFORT now works on the Anthropic channel (#446): low / medium / high / xhigh / max for the main session and subagents; unset, requests are unchanged. ARIS_MAX_TOKENS raises the output cap when a high effort runs into it. autoCompactEnabled: false in settings turns automatic compaction off. 🐛 #444 tool calls through relays that send a {} placeholder no longer fail with invalid tool input JSON. 🌐 System proxy on Windows / macOS is used without exporting HTTPS_PROXY (#401, by @JasmineLCY); NO_PROXY=* connects directly as before. Upgrading: if you already export ARIS_REASONING_EFFORT, have an OS proxy, or have autoCompactEnabled: false in settings, read the upgrade notes.

v0.4.27 (2026-09-19) — launching and quitting the REPL no longer leaves an empty session file; /resume lists only sessions with messages (#439 follow-up).

v0.4.26 (2026-09-16) — Fable 5.1: the fable alias now resolves to claude-fable-5-1, /model lists Fable 5.1 first (Fable 5 stays selectable) and the system-prompt identity names it; the default executor remains claude-opus-5 (the Mythos tier is $10/$50 vs Opus 5's $5/$25, so the default does not move). Saved executor_model values are ids, not aliases, and are untouched. Pricing already matched on fable; a test pins 5.1. Tests unchanged (aris-cli 225 + 4 e2e / runtime 252 / tools 71 / commands 6). Codex MCP (gpt-6-astra xhigh) gate: GO.

v0.4.25 (2026-09-16) — the reviewer-bridge release. codex-cli 0.154 removed codex mcp-server, the entry point ARIS-Code's aris setup had written into settings.json for every Codex review; on an updated codex every review call died. Built-in codex exec bridge: mcp__codex__codex / codex-reply run as codex exec --json with nothing to register — no settings entry, a legacy codex mcp-server entry is migrated in memory (env, -c defaults, requestTimeoutSecs, trust kept), an explicit Python-bridge entry is used as configured, thread records share ~/.codex/state/codex-exec/threads/ with the Python bridge, 1800 s budget for ultra audits, ARIS_CODEX_BRIDGE=0 restores the old path; aris doctor prints the effective backend. Found on the way: the model never received a Codex result's threadId (it lives only in structuredContent), so codex-reply could not continue a thread — results now start with a threadId: line. /since [full] replays the user's last input and everything after it with the live formatters (display only; after /resume and in --resume batch mode too); a dim hint after turns with ≥ 8 tool calls (ARIS_TURN_SUMMARY=0). #430 Windows consoles deliver no paste event, so each pasted line became its own Enter — lines are now merged into the input and never auto-submitted, Ctrl+C discards the rest (ARIS_PASTE_BURST=0; inferred from crossterm's source, pending confirmation on a Windows machine). #439 /resume lists sessions with [n] indices and ages and accepts an index, a unique id prefix or a path; the last turn is replayed after loading. #428 the .cmd-shim message carries the official native installer one-liner. Bundle 81→83 (pin 3e49e63 → 4734364): /proof-orchestrator, /research-implement-feature, 32 helpers (+review_gate.py, copilot_native_evidence.py, idea_discovery_gate.py), repo-root templates/ bundled; reviewer doctrine and system prompt on gpt-6-astra (fallback gpt-5.6-sol → gpt-5.5), explicit — reviewer: directives win, LlmReview results carry reviewer_model: so HTTP rounds report to review_gate.py truthfully; gpt-6-astra pricing tier $10/$50 (cache write $12.50, read $1). Tests: api 35+6 / aris-cli 225 + 4 e2e / runtime 252 / tools 71 / commands 6, all green; live codex exec fresh + resume roundtrip on codex-cli 0.154.0. Codex MCP (gpt-6-astra): ultra design gate (2 rounds), xhigh implementation gate per step (5/2/2/2 rounds), final whole-diff gate (2 rounds) → GO.

v0.4.24 (2026-08-09) — the Claude 5 model refresh (#392, requested by @YukinoshitaLove). Explicit --model claude-opus-5 / claude-fable-5 already passed through on every platform — this release makes them first-class. Default → claude-opus-5 (main session, subagents, aris setup; same $5/$25 tier as Opus 4.8); the v0.4.18 availability fallback becomes an ordered chain walk (Opus 5 → Opus 4.8 → Opus 4.7, one step per precise 404 not_found_error, explicit choices never silently change) — the naive constant swap would have stranded 4.7-only accounts and configs saved by v0.4.23's setup, a regression the cross-model review caught and an end-to-end mock-404 chain test now locks. /model picker adds Fable 5 / Opus 5 / Sonnet 5; new fable alias. New Mythos-class pricing tier (fable/mythos = $10/$50, cache write $12.50 / read $1, verified 2026-08 — previously fell to the conservative $15/$75 unknown-model tier, a 1.5× over-estimate); Opus 5 / Sonnet 5 pinned on their existing branches. Tests: api 41 / aris-cli 213 + 4 e2e / runtime 226 / tools 70 / commands 5, all green; live smoke on claude-opus-5, claude-fable-5 and the fable alias. Codex MCP (gpt-6-astra xhigh) implementation gate: NO-GO → NO-GO → GO.

v0.4.23 (2026-08-02) — the output-folding release (top real-user complaint: "aris dumps thinking and the full content of documents it reads onto the screen"). 🧹 Tool-output folding, display layer ONLY: the disk-verified culprits were format_read_result appending the ENTIRE read payload, bash pushing full stdout/stderr, grep dumping its full content blob, and the edit preview capping line counts but not line LENGTH. Now Read/Grep show the first 6 lines, Bash shows first 4 + last 4 per stream (stderr keeps its red), each kept line capped at 240 chars (the minified-single-line case), then one dim "… (+N more lines — set ARIS_TOOL_OUTPUT_LINES=0 for full output)" hint. ONE env knob: unset = defaults, a positive integer overrides every tool, 0 = the exact old display; the session, model context, --output-format json and /export are untouched and always complete. Thinking was verified to never print (Anthropic deltas only accumulate; Kimi reasoning_content only feeds the replay cache — the "thinking dump" perception came from the document dumps); two end-to-end sentinel tests (real binary vs mock SSE server) lock that thinking/reasoning never reaches the terminal. Interactive expand/collapse was deliberately rejected as over-engineering. 🐛 Bash timeout now kills the command: a timed-out call reported interrupted: true while the dropped tokio future left the child RUNNING — side effects landed after the report; now kill_on_drop (escape hatch ARIS_BASH_KILL_ON_TIMEOUT=0; background tasks untouched; locked by a real behavioral test — a timed-out "sleep 1 && touch marker" must not create the marker). 📦 Bundle 79→81 (pin 7182624 → 3e49e63): /integrity-forensics — the Anti-Autoresearch SHA-pinned thin launcher (span-anchored evidence ledger → GPT auditors propose → deterministic rules-only adjudicator decides → typed BLOCK/WARN gate + obligations ledger) — and /web-debug-search, +tools/forensics_gate.py (29 helpers, 104 embedded resources). 🎁 Also: grep's content mode no longer shows a false "0 matches" above real results (the gate caught that "numMatches": null serializes with the key present, defeating a naive presence check); all four crates' local-mock-server tests are now proxy-immune (a shell with http(s)_proxy set used to turn 15 tests red on a released tag — 127.0.0.1 was routed through the proxy). The rest of the runtime-state package (compaction re-arm, failed-turn cleanup, /cost dollars, SSE tail) ships as v0.4.24 — the cached-token cost fix is deliberately held back because it changes what the compaction trigger measures. Tests: api 41 / aris-cli 212 + 3 e2e / runtime 225 / tools 69 / commands 5 (+13), all green under a live proxy; new-code clippy delta zero. Codex MCP (gpt-6-astra): ultra scope+design adjudication, then a 3-round implementation gate (round 1 caught the null-serialization defeat and a non-hermetic behavioral test; round 3 GO).

v0.4.22 (2026-07-12) — the skills-resync + GPT-6-Astra release. 📦 Bundle resync (pin 7e3ab67 → 7182624, 93 commits): 79 bundled skills (+meta-apply, +paper-poster-html; paper-poster retired to a redirect stub), 28 tools helpers (8 new: capture_filter, evidence_check, iteration_log, provenance, run_state, threat_scan, meta_opt/trigger_eval + sample evals), 11 new shared-references docs (fan-out-pattern, acceptance-gate, external-cadence, skill-governance, compute-env-contract, resumable-runs, evidence-precheck, injection-hygiene, capture-antipatterns, output-composition, taste-calibration); sync hardening — ARIS_SYNC_EXPECT_SHA guard (aborts before touching assets if main moved; it caught a real move on first use) + exact-inventory drift tests + the vendored posterly MIT license text now ships. 🎛 GPT-6-Astra two-tier reviewer alignment: the CLI's system-prompt nudge now passes the skills' explicit model: gpt-6-astra + per-call effort pins through (the v0.4.17 blanket "never pass a model" rule would have silently stripped deep audits from ultra to xhigh), carries the canonical capability-only fallback chain (effort-unsupported → same model xhigh, deep tier only; model-unknown → explicit gpt-5.5+xhigh; never degrade on transport-class errors; an explicit call-level override disables the chain), pins approval-policy: "never" + explicit sandbox on every fresh codex call, and makes the HTTP fallback pre-dispatch-only with parameter stripping; the HTTP LlmReview default deliberately stays gpt-5.5 pending a real smoke; gpt-5.6 family pricing (sol $5/$30, terra $2.50/$15, luna $1/$6) verified against the official page; banner/Reviewer display//reviewer are honest about primary-vs-fallback (pure-Codex setups get status + guidance instead of a fake picker). 🐛 8 verified fixes: explicit --model was silently overridden by the saved executor model (model provenance now tracked end-to-end; the 4.8→4.7 availability fallback respects explicit choices; /model and /setup re-arm it); saved models no longer leak across provider transports (blank saved models count as absent; OpenAI transport with no model source fails fast; the first-run wizard's config now actually feeds startup model resolution); --output-format json never prompts (locked by a real end-to-end binary test against a mock SSE server); Windows aris login fixed (PKCE randomness read /dev/urandom → getrandom); Windows command probing fixed (the PowerShell tool probed itself through sh; now where.exe); codex .cmd shims classified honestly (three-state probe; setup requires explicit confirmation before writing a config the MCP client can't spawn); nested config.json warns instead of silently parsing to all-defaults; NotebookEdit mints collision-free cell ids. 🖥 New windows-latest CI job (workspace compile gate + three targeted test groups, each guarded against silent 0-test green). Tests: api 41 / aris-cli 204 + 1 e2e / runtime 223 / tools 69 / commands 5 (+54), all green; new-code clippy delta zero. Codex MCP (gpt-6-astra): ultra design gate — 5 rounds, NO-GO ×4 → GO — then a 3-round implementation gate whose round 2 caught a first-run config-wiring blocker before it shipped; 4 implementation subagents, every report disk-verified.

v0.4.21 (2026-06-28) — bug-fix patch: 5 new user-facing bugs from a Codex adversarial hunt (all disk-verified, distinct from v0.4.20), each cross-model reviewed at a design gate and an implementation gate (gpt-5.5 xhigh; both started NO-GO — the reviewer caught an off-by-one in the grep line-mapping and a missing stream-level test before GO). 🐛 Headline: OpenAI-compatible streaming corrupted multi-byte UTF-8 (CJK / emoji) split across network chunks into � — each HTTP body chunk was from_utf8_lossy'd independently, so a 3-byte Chinese character or 4-byte emoji straddling a chunk boundary broke on both sides (a frequent hit for Chinese users on domestic OpenAI-compatible providers — Kimi/GLM/MiniMax/DeepSeek/Qwen/Doubao — streaming Chinese text); the stream buffer is now raw bytes, decoding only complete SSE lines. A saved OpenAI/custom executor config no longer overrides a shell-set EXECUTOR_PROVIDER — the startup "shell-provided vars win" path had one ungated write that re-pointed EXECUTOR_PROVIDER=anthropic … aris … to OpenAI (wrong executor / model-not-found). An Anthropic stream truncated after content but before a terminal signal now hard-errors (premature_eof) instead of saving a half-finished answer to history as a complete turn (symmetric to the OpenAI #249 guard; the stop_reason-only compat path is preserved, and ARIS_ALLOW_EOF_WITHOUT_STOP=1 opts a terminal-signal-less proxy back into the old behavior). grep_search with multiline: true now matches across lines in content mode (was silently empty — count mode already worked). MCP tool results carried only in structuredContent (empty content) are no longer dropped — the model gets the JSON structured payload. Tests (CI mode): api 32→35 / runtime 205→212 / tools 67 / aris-cli 172→181 / commands 5 (+21, incl. 2 stream-level integration tests), all green. Codex MCP (gpt-5.5 xhigh): design gate (NO-GO → GO after fixing the off-by-one) → implementation gate (NO-GO → GO after adding the stream-level integration tests); the Anthropic streaming spec (every stream ends with message_stop) was WebFetch-verified. Two latent-only candidates (Anthropic block-index routing, OpenAI multi-line SSE) remain deferred.

v0.4.20 (2026-06-19) — bug-fix patch: 7 user-facing bugs surfaced by a Codex adversarial hunt, each reviewed across 3 rounds (the reviewer caught a redraw gap, a trailing-blank, a spinner tail, and a blank-line edge before GO). 🐛 Headline (#299): short REPL replies showed only "✔ Done" — the spinner draws "⠋ Thinking…" with Save/RestorePosition so streamed output overwrites it on the same line, but finish then cleared that whole line, erasing a short single-line reply. The REPL now finishes without clearing when the turn printed visible text (Clear(UntilNewLine) wipes only the spinner tail after the reply). Streamed multi-paragraph replies rendered glued ("para1para2") — each chunk's paragraph separator was trimmed at the stream boundary; the markdown streamer now preserves separators via a held-separator so streamed output equals a single full render (no dangling blank line). Markdown tables with CJK/fullwidth content misaligned — width now counts display cells (CJK = 2), not chars. aris "prompt" / --print ignored the executor model saved by aris setup (REPL-only before) — a configured OpenAI/custom executor got the Anthropic default sent to its endpoint; the one-shot and REPL paths now share one resolver. Esc now actually closes the completion dropdown (it was recomputed right back). glob_search reports the total matched count when truncated (not the capped 100, which made the model think a 1000-match glob had 100 files). /model's custom menu reads the effective env the executor uses, not stale on-disk config. Tests (CI mode): api 32 / runtime 205 / tools 67 / aris-cli 172 / commands 5, all green; +7 new; real-machine verified (short reply renders + "✔ Done"; paragraphs keep their blank lines). Codex MCP (gpt-5.5 xhigh): hunt → 3 review rounds (NO-GO → NO-GO → GO). Two latent-only candidates (Anthropic block-index routing, OpenAI multi-line SSE) deferred to a hardening pass.

v0.4.19 (2026-06-14) — honesty / guardrails patch (theme from a Codex fresh-eyes audit; no behavior change for healthy setups). 🔴 MCP protocol-version negotiation guard — the stdio handshake requested 2025-03-26 but never read the version the server negotiated back (a parsed-but-dead field), so a server agreeing on a version ARIS can't speak was silently accepted and later tools/list / tools/call ran on an incompatible protocol with opaque failures. ARIS now validates the negotiated version against a supported set (2025-11-25 / 2025-06-18 / 2025-03-26 / 2024-11-05 — stdio framing is identical across these) and, on an unsupported one, terminates the child + clears the slot + surfaces a clear per-server error (aris doctor shows it) — the "terminate when versions can't be agreed" behavior the MCP lifecycle spec requires. The request stays 2025-03-26 (proven against codex mcp-server), so healthy servers are unaffected — verified end-to-end: the real Codex MCP server still spawns + initializes + advertises its tools under the guard. 🧹 Papercuts: the OpenAI-family subagent fail-loud message dropped its stale "lands in v0.4.18" marker (now version-agnostic + actionable, still credential-free); OpenAI upstream error bodies are now truncated (500 chars) + credential-redacted (sk-… keys and Bearer … tokens, via a substring scanner that catches the compact-JSON shape {"api_key":"sk-…"} a misconfigured proxy can reflect back) instead of splatted verbatim; the system-prompt hook-events summary now counts only the hooks the runtime actually executes (a command hook with a command string), matching the parser. Tests (CI mode): api 32 / runtime 204 / tools 67 / aris-cli 167 / commands 5, all green; live smoke confirms the real Codex MCP server still initializes under the guard. Reviewed by Codex MCP (gpt-5.5 xhigh): design GO → impl NO-GO (compact-secret miss + command-string strictness) → GO after fixes.

v0.4.18 (2026-06-14) — default model → Claude Opus 4.8, with corrected pricing and a safety net. The bump moves DEFAULT_MODEL, the opus alias, the model picker, aris setup, and the subagent default to claude-opus-4-8 — with an availability fallback: if the account lacks 4.8 (the API returns 404 not_found_error), ARIS auto-falls-back to claude-opus-4-7 for the session, rebuilds the system-prompt model identity so it stays coherent (the model is never told it's 4.8 while served 4.7), warns once, and retries — for the main session (text + JSON) and subagents. It fires only on that precise 404 (never 400/rate-limit/auth), latches against loops, and the text path rebuilds from a pre-turn snapshot so a retry never double-appends the user message; accounts with 4.8 are byte-identical to a plain bump. 💰 Pricing corrected (verified against Anthropic's published schedule; had been a 3–5× over-estimate): current Opus 4.5–4.8 = $5/$25 (deprecated Opus 4/4.1 keep $15/$75, split by word-boundary so a future opus-4-10 isn't mis-tiered); Sonnet 4.x = $3/$15 (decoupled from the generic unknown-model fallback, which stays $15/$75); Haiku was already correct. 🧹 Backlog: aris setup option 10 pins the Codex MCP reviewer to model_reasoning_effort="xhigh" (deterministic for new setups, independent of ~/.codex/config.toml; idempotent merge never clobbers an existing entry); a startup + aris doctor misconfig hint (#259) for a silently-ignored/misplaced config (malformed JSON, or a stray ~/.aris/config.yaml — stderr-only so --print/JSON stdout stays clean); the system-prompt hook summary now marks parsed-but-never-fired events "PARSED ONLY … will NOT run" instead of implying dead hooks run (full event expansion — actually firing SessionStart/SessionEnd/… — deferred to a separate issue). Tests (CI mode): api 32 / runtime 202 / tools 67 / aris-cli 166 / commands 5, all green; a live one-shot smoke returns model=claude-opus-4-8 end-to-end. Reviewed by Codex MCP (gpt-5.5 xhigh) across the design + both implementation batches (design REWORK→GO, impl NO-GO→GO, batch-2 GO).

v0.4.17 (2026-06-13) — the MCP release. Before v0.4.17, mcpServers in settings.json parsed, showed in aris doctor, and did nothing; now ARIS spawns each configured stdio server, runs the MCP handshake, discovers tools, and advertises them as mcp__<server>__<tool> on both provider paths (Anthropic + OpenAI-family), with end-to-end dispatch, soft per-server degradation, and an approval gate for untrusted MCP tools (external processes the sandbox can't cover; --allowedTools now accepts mcp__ names). 🆕 zero-API-key cross-model reviewer: aris setup → option 10 (Codex MCP, ChatGPT subscription, no API key) writes an idempotent mcpServers.codex entry into the settings file the runtime actually reads (atomic write + backup, explicit consent before trust: true), with an optional API reviewer as fallback (ARIS_REVIEWER_PROVIDER=codex-mcp + ARIS_REVIEWER_FALLBACK_PROVIDER); /setup in-REPL rebuilds the system prompt + runtime so reviewer changes take effect without quitting. 🔴 Protocol fix the fakes couldn't catch: real-machine e2e against codex mcp-server exposed that our stdio transport spoke LSP-style Content-Length: framing while the MCP spec (and codex) use newline-delimited JSON-RPC — every fake-server test passed because the fakes spoke the same wrong dialect; writes are now NDJSON, reads auto-detect both, and the spec-mandated notifications/initialized is sent after initialize (a select-based round-trip also closes the #286 large-request deadlock). Hooks: object-style Claude Code hooks preserve matcher / timeout / async (anchored-regex matcher filtering; per-hook timeout, default 30 s kill = warning not deny). Long tail: ARIS_DISABLE_KEYCHAIN gate, Anthropic stop_reason clean-EOF symmetry (CL2), OpenAI tool-call index-missing merge-by-id (OE6), slash commands enter history. Real-machine push-gate hardening (the zero-key reviewer's first run): codex codex/event notification spam silenced by default (gated behind ARIS_MCP_STDERR=inherit), the system prompt now tells the model not to pass a model parameter to Codex (account default = gpt-5.5 + xhigh; arbitrary names are rejected by a ChatGPT account), and a Codex-MCP-primary-with-no-fallback LlmReview call returns a clear "use mcp__codex__codex" message instead of a misleading OPENAI_API_KEY/gpt-5.5 error. Built with the v0.4.16 zero-regression methodology (24 new characterization tests; every deliberate flip annotated in-place). Tests (CI mode): runtime 199 / aris-cli 165 / tools 67 / api 30 / commands 5, all green. Reviewed phase-by-phase by Codex MCP (gpt-5.5 xhigh) across 17 rounds (7 NO-GOs all resolved). Subagent MCP routing (P8) + MCP protocolVersion bump + hook async execution deferred to v0.4.18.

v0.4.16 (2026-05-30) — REPL UX + provider hardening, shipped under a zero-regression discipline: 64 characterization ("golden") tests locked the current provider-routing / pricing / reviewer / subagent / REPL behavior first, then stayed green through every change. Closes #274: command history now persists to ~/.config/aris/history (0600) and reloads on startup, with an ARIS_NO_HISTORY kill-switch and a disk-only secret-skip (credential-looking lines stay in in-session history but never touch disk); bash-style Ctrl+R reverse incremental search (CJK display-width-aware single-line render; no existing key binding changed; no new dependency). Security: an OpenAI-family main session (Kimi / GLM / MiniMax / …) spawning a subagent previously silently billed the user's Anthropic OAuth/Keychain credential — it now fails loud with a clear, credential-free error; full OpenAI-family subagent routing is a cross-crate change deferred to v0.4.17. Groundwork (no behavior change): the 3 byte-identical word-boundary matchers consolidate into one canonical runtime::word_match; new pure ProviderFamily classifier (unwired). Tests (CI mode): runtime 164 / aris-cli 128 / tools 49 / commands 5, all green. Codex MCP (gpt-5.5 xhigh) reviewed each phase + a final integration pass.

v0.4.15 (2026-05-29) — OpenAI-compatible streaming robustness hotfix. Closes #249: MiniMax (and other OpenAI-compatible providers / proxies) were effectively unusable because the clean-EOF completion check treated the data: [DONE] SSE sentinel as the only authoritative signal. A non-empty choices[].finish_reason is the Chat Completions spec's terminal-chunk marker; [DONE] is a transport convention some compatible providers never emit (MiniMax sends finish_reason: "stop" then closes without [DONE]). The clean-EOF decision is now a pure, unit-tested stream_eof_action(...) that completes on EITHER [DONE] OR a non-empty finish_reason; reads are NOT stopped early at finish_reason (a trailing include_usage usage-only chunk is still consumed), genuine truncation still hard-errors, and a pre-output proxy abort still restarts. Coupled fixes: OE7 reads finish_reason before the delta guard (delta-less terminal choice); OE2 flushes pending tool calls on any non-empty finish_reason; OE4 surfaces a mid-stream error envelope as a hard error instead of silently dropping it; OE3 tolerates data:{...} without the space after the colon. +5 unit tests (77→82) extract the previously-untested SSE completion logic into pure helpers. Anthropic SSE path untouched. Codex MCP (gpt-5.5 xhigh) 3 rounds (GO-WITH-NITS → GO-WITH-NITS → GO).

v0.4.14 (2026-05-25) — Security-hygiene release closing the top items from the v0.4.13 codex audit (gpt-5.5 xhigh, 6/10 NEEDS-REWORK verdict). 🔴 S9 (P0) system-prompt config redaction — before v0.4.14, render_config_section() dumped the merged settings.json verbatim into the system prompt sent to the LLM provider, leaking env, mcpServers.<name>.headers.Authorization Bearer tokens, hook command env, signed-URL query params, and apiKey fields. New renderer whitelists top-level fields (model/permissionMode/theme/outputStyle/permissions/sandbox with recursive redaction inside), redacts sensitive keys (apikey/token/secret/password/authorization/headers/env/_KEY/_SECRET/_TOKEN), replaces MCP command with <configured> placeholder, reduces MCP url to strict <scheme://host[:port]> origin (scheme allow-list http/https/ws/wss, ASCII host, digit-only port, IPv6 brackets), and drops hook command strings entirely. Regression test exercises 9 distinct leak surfaces; URL parser has its own targeted test for 7 smuggling attempts including port-position secret injection (codex round-3 catch). 🟡 P9 (P1): DeepSeek aris --help now points at aris setup option 7 instead of an env-var path the resolver never honored. 🟡 M1/M2 (P1) doc: aris doctor + README/README_CN gain experimental warning whenever mcpServers.len() > 0 (full MCP tool dispatch lands v0.4.16). 🟢 C11 (P2) stream idle timeout — both Anthropic MessageStream and the OpenAI SSE loop wrap response.chunk().await in tokio::time::timeout (env ARIS_STREAM_IDLE_TIMEOUT_SECS, default 120, clamp [10, 1800], 0/negative disables); closes the "aris hangs forever with no output" symptom when an upstream HTTPS proxy holds a connection without keepalives. Bundle: 77 skills (+1 /wiki-enrich via late same-day sync to main 7e3ab67 which also picks up upstream check_ready.sh awk + grep-c null-match fix), 54 helpers. Codex MCP 6 rounds (NO-GO + 4 → GO-WITH-NITS + 3 → NO-GO + port smuggling → GO → release metadata GO → sync GO).

v0.4.13 (2026-05-25) — Residue-cleanup release closing every codex audit P1 carried since v0.4.10–v0.4.12, plus the long-tail regression tests. 🟡 v0.4.10 P1.D per-server MCP timeout — mcpServers.<name>.requestTimeoutSecs override > MCP_REQUEST_TIMEOUT_SECS env > 300s default (clamped 1..=1800), so one Codex MCP agent can run 5 min while filesystem MCP errors in 5 s. 🟡 v0.4.10 known limitation closed — McpStdioProcess::request() skips JSON-RPC notifications (id absent/null) and keeps reading until the correlated response. 🟢 meta_opt hook deploy via aris init — tools/meta_opt/{log_event,check_ready}.sh bundle into the binary; aris init writes ARIS-namespaced aris-meta-opt-log-event.sh / aris-meta-opt-check-ready.sh to ~/.claude/hooks/ (codex round-1 #1: never clobbers user hooks); settings.json merge idempotent, backups hard-fail, final rewrite atomic via tempfile + rename. 🧪 9 v0.4.12 targeted regression tests for sandbox.strictMode (3) + parse strictMode + provider_match pricing + has_word o-series + stream_options 400 + meaningful-content classification + premature-EOF retry truth table (codex round-1 #3 — should_retry_on_premature_eof() extracted to pure fn, 7-row test). Bundle: 76 skills, 54 helpers (+2 meta_opt scripts vs v0.4.12). Codex 3 rounds (NO-GO + 3 → NO-GO + metadata → GO).

v0.4.12 (2026-05-22) — Bug-fix + small-feature release. #238 sandbox.strictMode opt-in config key; when set, SandboxConfig::resolve_request() ignores all five LLM-supplied overrides (dangerouslyDisableSandbox, namespaceRestrictions, isolateNetwork, filesystemMode, allowedMounts) — closes the gap where a tool call could silently bypass user sandbox policy. aris doctor adds a "Sandbox:" row; bash tool schema documents the strictMode semantics. #232 auto-review-loop-llm updated from legacy deepseek-chat / deepseek-reasoner (deprecate 2026-07-24; reasoner rejects tool_choice) to deepseek-v4-flash / deepseek-v4-pro. v0.4.10 audit P1 follow-ups: P1.A Anthropic stream retry gates on has_emitted_meaningful_content (a stream that only sent MessageStart before EOF is retry-eligible); P1.B supports_reasoning_effort + reviewer mirror use word-boundary match so openai/o3-mini / proxy:o4 route correctly; P1.C stream_options.include_usage:true proxy fallback retries once without on real 400 unknown-field errors; P2 pricing match precision via provider_match() so qwen3.6-plus / kimi-k2.5 route correctly while my-kimi-clone does not. Skills sync (76 skills, 52 helpers): /interview-cheatsheet + /render-html newly bundled; build.rs ALLOWED_EXTS gains html for render-html templates; EXCLUDED_SKILL_PREFIXES → starts_with("skills-codex"). CI fetch-depth: 0 + origin/main fetch so drift-test ancestor check runs. Cross-reviewed by Codex MCP (gpt-5.5 xhigh) over 4 rounds.

v0.4.11 (2026-05-18) — Skills bundle refresh + sync infrastructure. The embedded skills set in the v0.4.10 binary had fallen behind main (~6 of 56 main skills/ commits had been cherry-picked); v0.4.11 syncs the full set and ships sync infrastructure so the gap can't silently reopen. Bundle: 65→74 user-facing skills, 34→49 helper resources. 10 new skills bundled: /citation-audit (fourth-layer bibliography audit), /experiment-queue (SSH multi-seed job queue with OOM retry), /kill-argument (two-thread adversarial review for theory papers), /resubmit-pipeline (W5: text-only port to a new venue), /paper-talk (end-to-end conference talk pipeline), /slides-polish (per-page Codex layout review), /overleaf-sync (two-way Overleaf Git-bridge), /gemini-search + /openalex (broader literature sources), /qzcli (Qizhi GPU jobs). 46 existing SKILL.md refreshed — most critically the canonical resolver chain rollout (closes real user incident where /research-wiki was empty for a week from hardcoded tools/research_wiki.py), submission assurance gate + external verifier (/paper-writing Phase 6 now functions). tools/ goes 9→18: 9 baseline helpers refreshed (research_wiki.py 315→767 lines with canonical ingest_paper API), 9 new helpers (extract_paper_style.py, figure_renderer.py, paper_illustration_image2.py, overleaf_{setup,audit}.sh, verify_wiki_coverage.sh, watchdog.py, experiment_queue/{build_manifest,queue_manager}.py). New tools/sync_main_skills.sh automates main → bundle rsync with symlink pre-flight + codex-mirror prune + SKILLS_SOURCE_COMMIT pinning. 3 new CI drift tests in crates/runtime/src/cache.rs cover all 4 resolver layer patterns. Gemini MCP calls in /research-lit and /gemini-search now pass model: 'auto-gemini-3' (avoids silent downgrade to 2.5-pro on OAuth-personal capacity exhaustion). CLI runtime unchanged — codex-audit P1 follow-ups remain on v0.4.12 backlog. Cross-reviewed by Codex MCP (gpt-5.5 xhigh) across 5 rounds (REQUEST CHANGES → APPROVE WITH NITS → NO-GO → GO → final GO).

v0.4.10 (2026-05-17) — Stream + MCP reliability + multi-provider pricing. C6 whole-stream restart in Anthropic MessageStream + OpenAI SSE loop on chunk decode failure / premature EOF (ARIS_STREAM_RETRY, default 2, clamp 0..=5, fires only when nothing emitted yet — closes #228-style "error decoding response body" loop). M3 MCP stdio gains 300s default tokio::time::timeout over send+read (override MCP_REQUEST_TIMEOUT_SECS, clamp 1..=1800); response.id ↔ request.id correlation; ensure_server_ready() try_wait() dead-process respawn; kill().await on all failure paths so the next call starts clean (closes #151 / #172 "Calling codex..." stalls). C8/P4 OpenAI streaming requests now send stream_options.include_usage:true + parse cached_tokens; Anthropic streaming merges MessageStart.usage (input/cache) with MessageDelta.usage (output). C9 multi-provider pricing registry (15+ models, OpenAI cache_read = input × 0.1 corrects 5× generic overstatement, DeepSeek cache_hit/cache_miss tiers, has_word() boundary matcher for provider/<model> slugs). 9 dead-code warnings cleared; aris setup help text synced with actual behaviour.

v0.4.9 (2026-05-17) — Closes Codex v0.4.7 audit residuals (L1 TLS double-stack, L3 reasoning_cache compaction misalign, L4 reasoning replay unbounded). 2 new skills bundled (/figure-spec + /paper-illustration-image2 with scripts/ subdirs, new Layer 0b = $ARIS_CACHE_DIR/skills/<name>/scripts/); research_wiki.py promoted to shared tools/ (9+ callers); 5 more SKILL.md migrated to fallback chain.

v0.4.8 (2026-05-17) — Skill helper subsystem rewrite. Bundled helpers extract to ~/.config/aris/cache/<version>/ at startup; every Skill invocation surfaces helperReport JSON + 4-layer resolver preamble; /skills export copies helpers; new integration-contract.md with 6 failure policies; 8 shared helpers (arxiv/deepxiv/exa/S2/openalex/save_trace/verify_papers/verify_paper_audits) bundled; /research-lit + /deepxiv migrated. Plus 4 bug fixes: gpt-5.5+tools 400 on OpenAI; Custom reviewer reset; missing signature field (#228); --version Build date hardcoded.

v0.4.7 (2026-05-16) — DashScope Coding Plan 405 fixed (#159) via native-tls switch (#225); reasoning_content replay for all reasoning models (OpenAI o1/o3/o4 / DeepSeek-R1 etc.), not just Kimi (#226); 600+ lines dead code cleanup + rustyline dep removed + "Claw Code" → "ARIS-Code" rebrand.

v0.4.6 (2026-05-14) — 🚨 Two long-standing silent bugs fixed: PermissionMode::Prompt silently allowed every tool (derived-Ord bug); system prompt hardcoded current_date = "2026-03-31" made models reject post-cutoff data as future/prompt-injection. Plus Custom OpenAI-compatible provider (/setup option 11) with dynamic /models discovery (@Anduin9527 #221 + #222).

v0.4.5 (2026-05-13) — First-class reasoning-model support: thinking content blocks end-to-end (fixes #161) + reasoning_effort='xhigh' for GPT-5.5 / o1 / o3 / o4 / DeepSeek-thinking. DeepSeek V4 Pro + Xiaomi MiMo + Qwen 3.6 + Doubao in /setup (options 7-10). Object-style hooks parser. Default model bumped to Claude Opus 4.7 + GPT-5.5. REPL input hardening (multi-line wrap / Cmd+V paste / CJK boundary). GitHub Actions CI. Credits: @GO-player-hhy (#186), @Jxy-yxJ (#171), @GetIT-Sunday (#216 partial).

Older versions

v0.4.4 (2026-04-20) — Setup UX + reviewer routing fixes (resolves #158, #162) | /setup no longer forces Bearer for Anthropic + custom URL | Provider-aware proxy URL hints | Stale state no longer leaks across provider switches | LlmReview smart fallback

v0.4.3 (2026-04-17) — Third-party Anthropic-compat proxy support (Bedrock etc.) | Skip beta flags that proxies reject | Propagate custom base URL for anthropic provider | Credit @screw-44

v0.4.2 (2026-04-17) — Auto-compaction corruption fix | Compaction summary preserved on OpenAI-compat executors | Shell-provided API keys no longer erased on launch

v0.4.1 (2026-04-15) — Plan mode (/plan) | Cooperative Ctrl+C interrupt | Auto-retry (429/5xx/network) | Research Wiki 📚 (persistent knowledge base) | Self-Evolution 🧬 (/meta-optimize) | Local models (LM Studio/Ollama) | 62 skills synced

v0.3.11 (2026-04-13) — Reviewer Anthropic-compatible mode (Claude via proxy)

v0.3.9 (2026-04-11) — Proxy/custom base URL (CCSwitch) | Local models (LM Studio/Ollama) | Windows (experimental)

v0.3.5 (2026-04-08) — Research Wiki (persistent papers/ideas/experiments/claims + relationship graph) | Meta-Optimize self-evolution (analyze logs → propose SKILL.md patches)

v0.3.0 (2026-04-03) — Multi-file memory index | Rich task system (TodoWrite) | /plan | Security hardening

v0.2.2 (2026-04-03) — /plan step-by-step planning | /tasks persistent tracking

v0.2.1 (2026-04-03) — Persistent Memory | Kimi K2.5 multi-turn fix | CJK cursor fix

v0.2.0 (2026-04-02) — Open source | Kimi + MiniMax + GLM support | Smart LlmReview routing | CI/CD

v0.1.0 (2026-04-02) — Initial release | Multi-executor & reviewer | 42 bundled skills

中文版 README | English

🌙 Let Claude Code do research while you sleep. Wake up to find your paper scored, weaknesses identified, experiments run, and narrative rewritten — autonomously.

🪶 Radically lightweight — no infrastructure, zero lock-in. The entire skill layer is plain Markdown files. No framework to learn, no database to maintain, no Docker to configure, no daemon to babysit. Every skill is a single SKILL.md readable by any LLM — swap Claude Code for Codex CLI, OpenClaw, Cursor, Trae, Antigravity, Copilot CLI, Windsurf, or your own agent and the workflows still work. Fork it, rewrite it, adapt it to your stack.

💭 Why not self-play with a single model? Using Claude Code subagents or agent teams for both execution and review is technically possible, but tends to fall into local minima — the same model reviewing its own patterns creates blind spots.

Think of it like adversarial vs. stochastic bandits: a single model self-reviewing is the stochastic case (predictable reward noise), while cross-model review is adversarial (the reviewer actively probes weaknesses the executor didn't anticipate) — and adversarial bandits are fundamentally harder to game.

💭 Why two models, not more? Two is the minimum needed to break self-play blind spots, and 2-player games converge to Nash equilibrium far more efficiently than n-player ones. Adding more reviewers increases API cost and coordination overhead with diminishing returns — the biggest gain is going from 1→2, not 2→4.

Claude Code's strength is fast, fluid execution; Codex (GPT-6-Astra xhigh) is slower but more deliberate and rigorous in critique. These complementary styles — speed × rigor — produce better outcomes than either model talking to itself.

🧿 Want the strongest possible reviewer? Add — reviewer: oracle-pro to any skill to route reviews through GPT-5.5 Pro via Oracle MCP. Pro-level reasoning for proof verification, experiment auditing, and final stress tests. Works with API key or free browser mode. Setup →

Contents Copy Chapter

1. More Than Just a Prompt
2. What's New · changelog
3. Quick Start · install + first run
4. Features
5. Score Progression (Real Run)
6. Community Showcase — Papers Built with ARIS
7. Awesome Community Skills & Extensions
8. Workflows · 13 named pipelines (W1 / W1.5 / W2 / W3 / W4 / W5 / W6 / Wiki / WM + Effort / Assurance / Oracle)
9. Setup · prerequisites / install / update / usage / GPU server config
10. Customization · per-skill config knobs
11. Alternative Model Combinations · GLM / MiniMax / Kimi / etc.
12. Community
13. Citation
14. Star History
15. Acknowledgements
16. License

1. 🎯 More Than Just a Prompt Copy Chapter

These are full pipelines — you can also use each workflow independently. Already have an idea? Skip to Workflow 1.5. Have results? Jump to Workflow 3. Got reviews? Jump to Workflow 4. Want persistent memory? Enable Research Wiki. See Quick Start for all commands and Workflows for the full breakdown.

Basic mode — give ARIS a research direction, it handles everything:

/research-pipeline "factorized gap in discrete diffusion LMs"

🔥 Targeted mode — got a paper you want to improve? Give ARIS the paper + the code:

/research-pipeline "improve method X" — ref paper: https://arxiv.org/abs/2406.04329, base repo: https://github.com/org/project

ARIS reads the paper → finds its weaknesses → clones the codebase → generates ideas that specifically fix those weaknesses with that code → runs experiments → writes your paper. Like telling a research assistant: "read this paper, use this repo, find what's missing, and fix it."

Mix and match: ref paper only = "what can be improved?", base repo only = "what can I build with this code?", both = "improve this paper using this code."

🛠️ Build a feature — already know what to build?

/research-implement-feature "add KV-cache reuse to the decoder" — base repo: https://github.com/org/project

Spine first, then one feature at a time, each with a runnable check. Every choice the request left open is written to an assumption ledger before the code that depends on it, and a different model family then reads the raw diff for the ones that went undeclared. It reports "the checks passed", never "the method works". Contributed by @heroarmor.

🔥 Rebuttal mode — reviews just dropped? Don't panic. ARIS reads every concern, builds a strategy, and drafts a rebuttal that's grounded, structured, and under the character limit:

/rebuttal "paper/ + reviews" — venue: ICML, character limit: 5000

Three safety gates — rebuttal will NOT finalize if any fails:

• 🔒 No fabrication — every claim maps to paper/review/user-confirmed result
• 🔒 No overpromise — every promise is user-approved
• 🔒 Full coverage — every reviewer concern is tracked

Two outputs: PASTE_READY.txt (exact char count, paste to venue) + REBUTTAL_DRAFT_rich.md (extended version for manual editing).

Show rebuttal parameters — venue, character limit (required), quick mode, auto experiment, stress test rounds, followup rounds

After acceptance — your paper is in, now prepare the presentation:

/paper-slides "paper/"     # → Beamer PDF + PPTX + speaker notes + Q&A prep
/paper-poster-html "paper/" # → measurement-gated HTML/CSS poster → print-ready PDF

💡 From idea to paper to podium — one toolchain. 🌱

2. 📢 What's New Copy Chapter

⚠️ Any entry that touches skills: bash tools/smart_update.sh --apply pulls it.

• 2026-10-19 — 🔀 Choose reviewers inside the complete Claude Code and Codex skill packs — use — reviewer: or project configuration to select Codex, Gemini/Antigravity, Grok, or Claude Code through your configured reviewer tools. See the routing guide and Codex guide. The Claude Code MCP bridge now respects the requested working directory and records the CLI-reported model, including configured providers such as DeepSeek. Same-family reviews remain provisional. (#473, #472)
• 2026-10-19 — 📚 Catch bibliography field errors with /citation-crosscheck — compare local .bib entries with records freshly fetched from paper sources, then export a side-by-side spreadsheet of author, year, venue, DOI, and arXiv ID discrepancies. Available for Claude Code and Codex, alongside the existing citation audit. (#371; thanks @dty0606)
• 2026-10-19 — 🔬 Bounded parallel work for research workflows — idea generation, literature extraction, and proof checking now share fan-out rules: capped worker batches, coverage records, and sequential fallback when parallel execution is unavailable. Workers collect candidates and evidence; designated reviewers retain final judgments. (#372; thanks @Dennis-Huangm)
• 2026-10-07 — 🧮 From a mathematical statement to a checked Lean proof — new /lean-formalize for Claude Code and Codex. Develop proof routes, connect intermediate lemmas to the original theorem, and deliver reproducible Lean sources with statement and axiom checks. Cross-family reviews target the statement, key arguments, and final assembly. Integrated into five proof/research skills; use it when requested or a concrete proof obligation benefits from formal verification. (#461)
• 2026-10-05 — 🔌 New Grok and Gemini / Antigravity MCP bridges — use your existing CLI login to read files and resume conversations from Claude Code or Codex. (#454)

Earlier updates (2026-03-12 — 2026-09-28, 98 entries)

• 2026-09-28 — 📚 Real papers stop being reported as hallucinated citations (#445, #447, #450; thanks @ilya-pershin and @AfonsoZhang). arXiv sometimes refuses Python's HTTP client with a 406 for minutes while curl gets through; verify_papers.py read that refusal as "paper not found" and one user saw a 47% hallucination rate on 38 real papers. A 406 now goes through curl, and a refusal (406 / 401 / 403) is verify_pending, never unverified. Set SEMANTIC_SCHOLAR_API_KEY and title checks use it. Seen a suspicious hallucination rate recently? Re-run with --no-cache once. Also in this round: five skills can now actually invoke the sub-skills their text tells them to (#440, @Jeremy-xuan); concurrent watchdog registrations no longer overwrite each other (#443, @hiro-nikaitou); xhigh is described as the regular reviewer tier it is (#442, @dreamworld2023).

• 2026-09-16 — 🧩 ARIS is a Claude Code plugin now (#437, thanks @white-drizzle). claude plugin marketplace add wanshuiyin/Auto-claude-code-research-in-sleep → claude plugin install aris@aris → /aris:setup once → restart. Setup registers the Codex reviewer bridge that ships inside the plugin, so the reviewer works on codex-cli 0.154+ out of the box. Plugin skills are typed with the prefix (/aris:idea-discovery); they call each other by short name internally. Codex CLI reads the same repo as a plugin too (codex plugin marketplace add … → codex plugin add aris@aris) and gets the Codex-native mirror. Cursor, Trae and DeepSeek Harness keep their own routes.

• 2026-09-10 — 🔌 codex-cli 0.154 removed codex mcp-server — re-register the codex MCP server. Every ARIS reviewer call went through that entry point; on 0.154+ it now opens the interactive TUI and the MCP handshake fails. ARIS ships its own stand-in, mcp-servers/codex-exec/server.py, same tool names and result shape, driving codex exec underneath — skills unchanged. Run once: git pull in your ARIS clone (older clones do not have the file), then claude mcp remove codex -s user && claude mcp add codex -s user -- python3 "$HOME/aris_repo/mcp-servers/codex-exec/server.py" (absolute path of your clone), then restart Claude Code. Step-by-step for new and existing installs in Quick Start. Works on 0.153 too, so do it before you update. OpenAI's own replacement, the Claude Code plugin, has no ultra effort and no per-thread resume, which the deep-audit skills need. Cursor / Trae / Antigravity / Copilot CLI configs: same key, python3 + that path — see the adaptation docs.

• 2026-09-07 — 🧠 Default reviewer is now gpt-6-astra. Every reviewer call that pinned gpt-5.6-sol now pins gpt-6-astra; the two effort tiers (ultra for the seven deep audits, xhigh everywhere else) are unchanged, and so is the executor — whatever agent you run ARIS in. No access to the model yet? The capability fallback tries gpt-5.6-sol, then gpt-5.5, both at xhigh — nothing to configure.

• 2026-09-06 — 🧹 The installer stops dropping Copilot profiles into every project (#431, thanks @oblivion-1521). Since 2026-08 every run symlinked two Copilot reviewer profiles into your .github/agents/ whether or not anything used them — dead files for Claude Code and Codex users, broken links if you committed them. Now they are deployed only while auto-review-loop is installed; --no-agent-profiles switches them off for good (undo with --agent-profiles). Your next re-run removes the links the installer created earlier; files you wrote yourself are never touched.

• 2026-09-03 — 📣 Papers are launches, not progress reports (rules adopted from anti-defensive-writing-Skill by @Adkid-Zephyr — 🌟 it). The writing contract gains four rules: organize the narrative around the strongest genuine advantage; pick the contest the paper wins; unfavorable numbers stay in the tables, explained as a tradeoff where the evidence supports that and stated neutrally where it does not — never narrated as a defeat; every experiment carries an argumentative duty or leaves the main line; abstract and introduction open with problem → gap → idea → strongest result, and the conclusion never ends on new self-negation. /auto-paper-improvement-loop flags the same defects. Indexed under Awesome Community Skills.

• 2026-08-26 — 🧯 Two over-defense leftovers (#425). /research-review — the one reviewer prompt that never got the scope-limits block — now carries it, and its brief ends with "if the work holds up, say so clearly" instead of bare brutality; the adversarial stance itself is untouched. /research-pipeline no longer dies overnight on a missing VENUE: ideas, experiments, analysis and the narrative report are venue-independent and run to completion — only paper formatting defers, stamped clearly for a later resume. It had also been declaring VENUE = ICLR while forbidding silent defaults; the default is gone.

• 2026-08-26 — ✍️ Papers stop reading like confession letters (#423, #424; several rules adopted from humanize-paper). Claims are stated at the strength the evidence earns; generic caveats ("further research is needed") live in Limitations only; "don't mention X" means X is absent — never "we do not address X" in print; results are ordered by argument, not by the order experiments ran.

• 2026-08-26 — 💡 The idea pipeline stops killing ideas for having neighbors (#419–#422; community reports). ABANDON now has to name the published paper that already contains your result, and concurrent work is a race — your call, not a veto. Brainstorming runs two generator models (gpt-5.6-sol + gpt-5.5) and unions their ideas, aiming for creative direct attacks instead of corner-case stacks. Search digs as hard as ever.

• 2026-08-21 — 🔌 Optional HTTP reviewer fallback for when Codex MCP is unreachable (#413; by @TheFlashForge). Off by default; fires only when Codex provably never got the request — a timeout doesn't count, that could pay twice for two conflicting verdicts. The fallback reads your actual files and gets less trust than Codex, never more.

• 2026-08-21 — 🧹 Four community fixes in one day (#406–#410; by @ZLZLGe and @JasmineLCY). AUTO_PROCEED=true now actually continues on its own; the idea-discovery gate demands a real reviewer receipt, not a checkbox; cached wiki context is scanned right before /idea-creator reads it; Codex users with Claude as reviewer get their three paper skills back.

• 2026-08-09 — 🦆 Copilot CLI defaults /auto-review-loop to its native rubber-duck reviewer (#360, closes #258). Active only inside Copilot CLI sessions; review evidence is revalidated from host events, and same/unknown-family fails closed. The standard Claude Code + Codex setup is untouched.

• 2026-08-09 — 🚧 /idea-discovery can no longer silently skip a stage (#383, closes #285; by @3mom3). Each of the five stages needs recorded evidence, or the report says BLOCKED instead of looking complete.

• 2026-08-05 — 🈶 The research wiki handles non-ASCII (#386, #387; reported by @LIMMIL7). cp936-written wikis were unreadable on other machines, and Chinese-only titles collapsed to <year>_untitled and got deduped away. Existing UTF-8 wikis unaffected.

• 2026-08-04 — 🖼️ Upstream spotlight: posterly — the engine behind /paper-poster-html — shipped a major design upgrade (MIT, by @Chenruishuo; ~50 posters at this year's ICML). GitHub · Blog.

• 2026-08-03 — 🧭 /proof-orchestrator — Workflow 7: proof campaigns with a memory (#381; by @shenmuxing, from their EtaSkill). Stateful local-first proof runs that continue across sessions, with a ready-to-paste GPT Pro handoff when a proof stalls. /proof-checker remains the submission gate.

• 2026-07-15 — 🔗 Double-blind citation field audit (#371). New /citation-crosscheck: two agents work blind — one reads each cited entry from the local .bib, one re-fetches it from the web — and a deterministic gate diffs them field by field (author set+order, year, venue, arXiv-id/DOI), emitting a side-by-side .xlsx with MATCH/MINOR/MISMATCH. Complements /citation-audit (context-fit); this owns field accuracy.

• 2026-07-14 — 🐞 /web-debug-search (Issue #211). Adds a focused debugging/discovery workflow for GitHub Issues and Discussions: exact and normalized error-string matching, version compatibility tracking, and explicit failure handling. Results are labeled for debugging only and are not paper-citation evidence.

• 2026-07-14 — 🧩 Selective install + global helper pointer (#366). The 81 skills are no longer all-or-nothing — all four installers support group/skill-level picks (--list-groups, --groups X,Y, --skills X, --exclude Y, or a bare-TTY checkbox picker), with hard pipeline deps auto-included. Updates now confirm each NEW upstream skill individually (--add-new / --skip-new for scripting; declines are remembered and never re-asked). Also fixes copy installs (~/.claude/skills) losing helper-script resolution, via a new ~/.aris/repo pointer file. ⚠️ Backward compatible — --quiet fresh installs still install everything; run any installer/updater once to pick up the pointer file. Selective install →

• 2026-07-12 — 🛡️ Your paper now gets the reviewer-side forensics treatment before you submit (#357). New /integrity-forensics skill: a SHA-pinned thin launcher runs Anti-Autoresearch's hostile-reviewer sweep (evidence ledger, nine auditor dimensions, numeric core, rules-only adjudicator) on your paper first. The verdict feeds a typed gate — flags can block a submission, a clean sweep is recorded as "no new blocker" (never an acquittal) — and findings close only with typed, hashed evidence or a recorded human waiver (rewording the flagged sentence doesn't count; the ledger notices). /paper-writing runs it by default at submission assurance (— self_forensics: false opts out; the Codex mirror is opt-in and limited to upstream's deterministic slice, which can flag but never say CLEAN). ⚠️ First run clones and validates the pinned upstream (needs network); run bash tools/smart_update.sh --apply.

• 2026-07-10 — 🧠 Reviewer default is now GPT-5.6-Sol; deep audits think at the new ultra level (#354). codex-cli 0.144.1 added max/ultra reasoning above xhigh; ARIS reviews now default to gpt-5.6-sol, with the seven heavyweight verdicts (/proof-checker, /kill-argument, /research-review, /experiment-audit, /paper-claim-audit, /result-to-claim, /meta-apply) at ultra and everything else at xhigh. Older codex-cli or no model access steps down automatically (5.6-sol → 5.5, both xhigh) — never below xhigh, never on a mere timeout. Also fixed: /result-to-claim now stops honestly instead of judging its own results when the reviewer is unreachable. ⚠️ Upgrade codex-cli to ≥ 0.144.1, restart the session (MCP reloads only then), and run bash tools/smart_update.sh --apply.

• 2026-07-03 — 🧬 Three small updates adapted from Anthropic's Claude Science skills (#339, #340, #341; Apache-2.0). ARIS now has one shared way to describe GPU environments, so the same setup can be reused across SSH machines, Modal, and clusters, then checked by a fresh agent following the setup notes. We also added a small tool that tests whether a skill description actually makes the right skill get picked. Finally, figure and writing checks now separate facts from style: truth checks must pass, style advice stays optional. ⚠️ Run bash tools/smart_update.sh --apply to pull.

• 2026-07-02 — 🔁 Ideas from Karpathy's LOOPS.md, brought into ARIS (#333–#337). Reviewers now start by looking for what may be wrong, not by giving a polite score. If a review result looks strange, ARIS points you to the saved reviewer transcript before you ask the model again. A failed build can be restarted from the plan instead of endlessly patched, while plans, logs, and results are kept. Scoring can now use real good and bad examples, /meta-optimize asks what can be removed, and /paper-writing agrees on a clear "done" checklist before drafting starts. ⚠️ Run bash tools/smart_update.sh --apply to pull.

• 2026-06-20 — 📚 Research wiki: all four node layers now have deterministic writers — fixes "re-generated ideas not recorded" (#305, #306, #307, #308). A user hit a real bug — ideas recorded on the first /idea-creator run vanished on re-generation — because wiki pages were written freehand, a prose step the model skips on a re-prompt. Each layer now has a dedicated research_wiki.py writer joining ingest_paper: add_claim (claims born at /proof-checker), upsert_idea (/idea-creator), add_experiment (/result-to-claim) — each guarded by a drift-check so it can't silently regress to dead code. A claim's status is now a strict proof axis (verified/refuted/unproven/…) while experiment support is carried by supports/invalidates edges (closing a latent contradiction the shared validator rejected), and the Codex-CLI skill mirror is synced to match. Zero behavior change when no research-wiki/ is present.

• 2026-06-19 — 🛰 Overnight loops can now notice when they die or get stuck (#300, #301, #302; adapted from operational patterns in Deli Chen's AutoResearch). A new watchdog checks whether an unattended loop is still updating its state file and writes an alert when it goes quiet; it only reports the problem, never restarts a verdict-bearing run. A separate iteration log watches for rounds that stop finding anything new: two empty rounds force a change of direction, four call in a human, and the cross-model jury still decides whether the result is actually good enough.

• 2026-06-07 — 🖼️ /paper-poster-html is now the default poster pipeline; the old LaTeX /paper-poster is retired. It builds the poster as one HTML/CSS file at the venue's real print size, then runs measured layout and asset checks before a content reviewer sees it, so review time goes to the science instead of crooked columns. It also ships templates, reusable poster components, and venue token packs; the core gate machinery was adapted from posterly (MIT, by @Chenruishuo). ⚠️ /paper-poster now redirects to /paper-poster-html; the LaTeX pipeline lives only in git history.

• 2026-05-31 — 🤝 Two community tools worth a look. Claude Fleet (@tianyilt) is a local read-only dashboard for keeping track of many Claude Code / Codex windows at once. posterly (@Chenruishuo) builds conference posters as a single HTML/CSS file and exports a print-ready PDF through headless Chromium, no LaTeX needed. Both are listed under Awesome Community. 🌟 if they help you.

• 2026-05-31 — 🛰 Fourth reviewer backend: Gemini via Antigravity CLI (#267 by @ZGJY95). — reviewer: agy routes review through the Antigravity CLI for users without Codex MCP / Oracle — fail-closed on the cross-model invariant (recovers + verifies the real Gemini-family model, refuses non-Gemini, binds the recovered transcript to the call via a user-event nonce). Wired into reviewer-routing.md.

• 2026-05-29 — ⚙️ ultracode-native convention layer — fan out for breadth on any runtime tier, keep the cross-model jury sacred. Three new shared-references docs decouple breadth from verdict: fan-out-pattern.md (skills generate candidates across same-family Claude subagents — Tier-1 Workflow / Tier-2 Agent / Tier-3 sequential — all ending in the identical cross-model jury), acceptance-gate.md ("a loop can DRIVE, it cannot ACQUIT" — self-judge execution-completeness, never quality/correctness), and external-cadence.md (/loop & CronCreate are fire-control, never a jury). Wired into /idea-creator, /research-lit, /proof-checker, /kill-argument (fan-out) plus 16 skills (cadence fence/affordance). Also stripped 48 vestigial Agent grants (least-privilege + a drift-check guard), fixed /idea-creator's same-family idea pre-filter, and reconciled an /auto-review-loop OR→AND stop-condition inconsistency. Non-ultracode users benefit immediately — fan-out degrades to sequential with the same final jury.

• 2026-05-28 — 📝 First blog shipped: A Survey on Continuous DLM (2026 H1, 6 papers) — long-form bilingual technical survey by Ruofeng Yang (SJTU), written end-to-end through the ARIS-in-AI-Offer workflow (Claude Opus 4.7 + Codex GPT-5.5 xhigh + Gemini auto-gemini-3 cross-model discussion). Compares ELF, ByteDance Cola-DLM, and Flow-Matching family across discrete-DLM problems, the "known-unknown" continuous space idea, training pipeline, architecture / params / shapes, inference grids + Tab 6/7 numerical results, denoising trajectories, and a Field Landscape against Cola-DLM. A 1.7 MB self-contained HTML (no build) — demonstrates the kind of long-form analysis the /render-html toolchain can produce.

• 2026-05-26 — 🌐 HTML auto-emission activated at 8 workflow checkpoints. /idea-discovery, /auto-review-loop, /research-pipeline, /kill-argument, /proof-checker, /paper-claim-audit, /citation-audit, /rebuttal now auto-render their primary MD artifact to a single-file HTML view via /render-html. Cost-tiered: interim views use --no-review, audit-class / reviewer-facing deliverables keep the full Codex render-fidelity gate. Default on (RENDER_HTML = true); per-skill opt-out. Failures non-blocking — source MD stays canonical.

• 2026-05-26 — 🤝 Community PR wave — 5 merges this week. /wiki-enrich (#247 by @hungchun0201) fills paper TODOs ingest_paper leaves as scaffolds — Karpathy LLM-wiki principle, fetch chain alphaxiv→deepxiv→arXiv. Mirror drift checker + CI (#241 by @VeraPyuyi) keeps main↔mirror in sync. /research-pipeline Stage 2/3 unified into /experiment-bridge delegation (#243 by @ZBigFish) — old inline was a strict subset of the bridge. Windows PowerShell installer parity with reparse-chain inside-repo guard + -FromOld legacy migration + Windows CI matrix (#242 by @VeraPyuyi). Plus manual-review MCP (#246 by @ZBigFish) — third reviewer backend — reviewer: manual for zero-cost cross-model review (paste prompt to any non-Claude model: DeepSeek / Kimi / ChatGPT / Gemini / local llama); cross-model invariant guarded by bilingual UI banner + per-session token auth + fail-closed when MCP unavailable.

• 2026-05-17 — 🐙 GitHub Copilot CLI adaptation — native SKILL.md + MCP support, no skill mirror needed. Installer (install_aris_copilot.sh) + smart-updater + 13-test suite. Community contribution by @EarendelH (#229, closes #214 / #227 / #203).

• 2026-05-17 — 🛠 Tools-stability roadmap (Phase 1+2+3) complete (closes #176 / #177 / #178). Community reported that helper scripts weren't propagating into user projects after install_aris.sh. Phase 1 — every SKILL.md caller of the 10 canonical helpers now resolves via the strict-safe 3-layer chain .aris/tools/ → tools/ → $ARIS_REPO/tools/ documented in integration-contract.md §2 (which also defines 5 failure policies A/B/C/D1/D2/E). Phase 2 — new advisory CI lint catches hardcoded python3 tools/foo.py patterns in PR-modified SKILL.md (advisory only, never fails CI). Phase 3 — three single-owner helpers (figure-spec, paper-illustration-image2, experiment-queue) moved into their SKILL's scripts/ subdirectory; owner SKILLs use Layer 0 ${CLAUDE_SKILL_DIR}/scripts/ ahead of the canonical chain; legacy tools/ paths retained as os.execv Python forwarding shims. ⚠️ Existing users: no action needed — legacy tools/ entries are now shims. If you haven't run install_aris.sh since 2026-04-30, one idempotent rerun catches everything up.

• 2026-05-14 — 🩹 /paper-plan + /paper-write learn GAP_REPORT.md + `` discipline (#217). When — style-ref: is set and the user's project has structural assets (figures/, results/, NARRATIVE_REPORT.md, etc.), /paper-plan emits a Gap Report mapping the exemplar's section topology + density (from style_profile.md) against your actual assets — surfacing slots you have no evidence to fill (e.g., "exemplar has 3×4 ablation table, you have no ablation data"). Then /paper-write writes `` HTML comments instead of fabricating content at missing slots — invisible in the compiled PDF, grep-friendly for human triage / /experiment-bridge follow-up. Narrow carve-out from the "no placeholders" rule, scoped to GAP_REPORT-listed slots only. Original idea by @zhangpelf.

• 2026-05-14 — ⚙️ Default reviewer model: gpt-5.4 → gpt-5.5 across ~30 SKILL.md REVIEWER_MODEL defaults. Codex MCP has routed gpt-5.5 as the default since 2026-04-24; this catches the docs up to runtime. ⚠️ Behavior changes: (a) .aris/traces/* JSONs from prior runs are not reproducible — re-runs on 5.5 may emit different WARN/FAIL verdicts on borderline cases (reviewer-quality lift, not regression). (b) ChatGPT Plus/Pro monthly quotas drain faster under heavy use. Fallback: pass — reviewer-model: gpt-5.4 per invocation, or pin REVIEWER_MODEL = gpt-5.4 per skill. Oracle Pro tier (routed via — reviewer: oracle-pro) is a separate path and unaffected.

• 2026-05-13 — 🔍 tools/verify_papers.py + Pre-Search Verification Protocol — anti-hallucination filter for literature-facing skills. New helper does 3-layer fallback verification (arXiv batch API up to 40 IDs/request → CrossRef DOI lookup → Semantic Scholar fuzzy title match, default 0.6 word-overlap) and emits 4-state per-paper status (verified / unverified / verify_pending / error) plus a top-level verdict aligning with assurance-contract.md (PASS / WARN / BLOCKED / ERROR). Transient failures (5xx, timeouts, 429) are tagged verify_pending and excluded from the hallucination rate so network blips don't get conflated with fabricated references. Per-project cache at /.aris/cache/verify_papers.json with 30-day TTL; canonical key priority arxiv:{id_without_version} → doi:{lowercase} → title:{sha1[:16]}. New Pre-Search Verification Protocol subsection in shared-references/citation-discipline.md makes the split explicit: this protocol is the fast filter between SEARCH (Step 1) and full VERIFY (Step 2); /citation-audit and /paper-claim-audit remain the submission-time audit gates and are not replaced. /research-lit gets a mandatory Step 1.5: Verify Candidate Papers calling the helper; /idea-creator and /novelty-check add a Key Rule reference for cited Closest Prior Work / landscape entries. Unverified papers are retained in output tagged [UNVERIFIED] (retention-over-silent-removal) so search-quality issues stay visible. Set ARIS_VERIFY_EMAIL in your shell to lift CrossRef to the polite-pool rate. Original signal from @YiwenZhu77 in #120 — landed via clean reimplementation rather than direct merge (PR was 5 weeks old + scope creep into figure-style).

• 2026-05-06 — 🎤 /paper-talk workflow + /slides-polish skill — end-to-end conference talk pipeline. /paper-talk orchestrates paper → slide outline → Beamer + PPTX → per-page polish → assurance audits → final report (sister to /paper-writing, /paper-poster); composes /paper-slides, /slides-polish, plus /paper-claim-audit + /citation-audit when assurance: conference-ready. /slides-polish is the post-generation visual pass: per-page Codex review against a reference PDF + a fix-pattern catalog (PPTX font scaling 1.5-1.8× for projector-readable size, text-frame resize after font bump, banner-as-tcolorbox, italic style leak guard, em-dash spacing, Chinese EA font hint via PingFang SC, anonymity placeholder discipline). Assurance ladder draft / polished (default) / conference-ready is independent from the effort axis; effort: lite, assurance: conference-ready is legal and means "fast pipeline, every audit must emit verdict before final". Phase 4 staging adapter materializes slide text + speaker notes + talk script as a synthetic paper directory (.aris/paper-talk/audit-input/sections/*.tex + symlinked .bib / results/ / figures/) so the existing audits run with their paper-shaped contracts and emit 6-state JSON verdicts per shared-references/assurance-contract.md.

• 2026-05-05 — 🔁 /resubmit-pipeline — Workflow 5: text-only resubmit across venues (#208). Port a polished paper from one venue to another under hard constraints (no new experiments, no bib edits, no framework changes, never overwrite prior submissions). 5 phases: physical isolation → 5-layer anonymity check → audits (proof / claim / citation --soft-only) → microedits via /auto-paper-improvement-loop --edit-whitelist with per-round diff gate → adversarial gate via /kill-argument → final compile + Overleaf push via /overleaf-sync. Two prerequisite SKILL upgrades shipped in the same PR: /auto-paper-improvement-loop --edit-whitelist (YAML schema with allowed/forbidden paths + forbidden_operations like new_cite / new_theorem_env / numerical_claim, forbidden_deletions, requires_user_approval_for, max_edits_per_round) and /citation-audit --soft-only (translates KEEP/FIX/REPLACE/REMOVE verdicts to text-rewrite proposals when bib is frozen; hallucinated citations get drop_cite_in_body_only action). Master RESUBMIT_REPORT.json ledger per shared-references/assurance-contract.md; 7-verdict failure mode table including USER_DECISION runtime state.

• 2026-05-05 — 🗡 /kill-argument — adversarial Attack-Adjudication review for theory papers (#206). Two fresh codex 5.5 + xhigh threads: Thread 1 writes the strongest 200-word rejection memo a senior area chair would produce; Thread 2 (independent adjudicator, NOT defender) reads the current paper and classifies each rejection point as answered_by_current_text / partially_answered / still_unresolved with file:line evidence. Output: KILL_ARGUMENT.{md,json}, detect-only. Integrated as Phase 5.6 of /paper-writing (between claim-audit and citation-audit) and as the canonical implementation called from /auto-paper-improvement-loop Step 5.5 — replaces inline prompt in both places. Mandatory at assurance: submission for theory-heavy / scope-heavy papers; emits NOT_APPLICABLE for empirical papers without scope claims. Audit JSON is verify_paper_audits.sh-compatible (full schema per shared-references/assurance-contract.md, 6-state verdict). Catches the failure mode score-based reviews miss: when every local component is correct (numbers match, cites resolve, theorems prove) but the paper still oversells what it actually establishes.

• 2026-05-04 — 🪲 /research-wiki and 8 caller skills now resolve helper via fallback chain (#204). Bug: after bash tools/install_aris.sh the helper lives at .aris/tools/research_wiki.py (symlink), but skills hard-coded tools/research_wiki.py and silently failed when invoked — research-wiki/ stayed empty across full W1 runs. Fix: 3-layer chain (.aris/tools/ → tools/ → $ARIS_REPO/tools/) codified in shared-references/wiki-helper-resolution.md. The manual-copy workaround at /tools/research_wiki.py is layer 2, so users who cp-installed the helper as a temporary fix continue to work. ⚠️ Existing users: rerun bash tools/install_aris.sh once — also picks up a separate Python 3.9 ImportError fix in the helper.

• 2026-05-03 — 🎨 Opt-in — style-ref: for writer-side skills (#202). /paper-{plan,write,writing,illustration,poster,slides}, /grant-proposal, and /auto-paper-improvement-loop accept an optional — style-ref: argument that mimics a reference paper's structural style (section ordering, theorem/figure density, sentence cadence, citation style) without copying its prose, claims, or terminology. Sources: local .tex dir/file, local PDF, arXiv id (2501.12345 or arxiv:2501.12345), HTTP/HTTPS URL. Overleaf URLs/IDs are rejected — clone via /overleaf-sync setup first. Default OFF; existing behavior unchanged when the flag is absent. Reviewer / auditor sub-skills (/proof-checker, /paper-claim-audit, /citation-audit, the improvement-loop reviewer) never see the style ref — cross-model review independence preserved. ⚠️ Existing ARIS users: the helper ships at tools/extract_paper_style.py, distributed via the .aris/tools symlink (install_aris.sh Phase 0, added in #192). Re-run bash tools/install_aris.sh once to refresh the symlink and pick up the helper. Manual fallback: cp <ARIS-repo>/tools/extract_paper_style.py <your-project>/tools/. Without either, the writer skill aborts with a clear error pointing here.

• 2026-05-02 — 🪨 Community spotlight: rosetta by @SyntaxSmith. Programmatic access to ChatGPT Pro / gpt-5.5-pro / DeepResearch from Node, via Chrome CDP Fetch interception + WebSocket second-leg streaming; ships an MCP server for Claude Code / Codex / Cline. Alternative implementation path to Oracle MCP for ARIS users invoking — reviewer: oracle-pro — same target capability (Pro-tier reviewer), different mechanics. Indexed under Awesome Community Skills & Extensions. 🌟 if you're using it!

• 2026-05-02 — 💎🧿 Model & MCP routing updates. (a) /gemini-search default bumped to gemini-3-pro-preview (strongest Gemini, out-of-box). ⚠️ Action required: requires gemini-cli v0.40+ (run gemini --version; upgrade with npm i @google/gemini-cli if older). Legacy override: /gemini-search "topic" — model: gemini-2.5-pro. Other overrides: gemini-3-flash-preview (faster), auto-gemini-3 (load-routed). (b) /idea-discovery Phase 1 now includes Gemini in its literature survey by default (#199) — auto-injects — sources: all, gemini into /research-lit unless the user passed an explicit — sources:; graceful skip if gemini-cli not installed. (c) Oracle MCP upstream PR queue (steipete/oracle/pulls) is the first triage stop when invoking — reviewer: oracle-pro (especially o3-deep-research / gpt-5.5-pro) — ARIS does not vendor Oracle MCP; check upstream first if behavior surprises you (reviewer-routing.md)

• 2026-05-02 — 🛠️🔗 Tools-infrastructure migration started. (a) install_aris.sh creates optional .aris/tools symlink (#192, closes #174) — Phase 0 of the 4-step tools-stability plan (#174 → #176 → #177 → #178); idempotent, zero impact until rerun. (b) /experiment-queue orchestration paths repaired (#193) — first real user of the symlink; 7 cascading bugs fixed via 3 rounds of Codex MCP gpt-5.5 xhigh audit. Pure prose + docstring; queue_manager.py logic untouched. Windows install_aris.ps1 parallel update tracked as follow-up

• 2026-05-02 — 🔬 Three new opt-in audit flags via fast-path delegated-agent workflow (#187, #188, #189). /citation-audit --uncited surfaces bib entries with no \cite{} reference (detect-only). /proof-checker --deep-fix adds a repair-grade plan to the Phase 1 reviewer prompt (corrected statement / patch plan / closure tests + Schur/quadratic-form algebra sanity). /proof-checker --restatement-check adds Phase 3.6 cross-location theorem drift detection (6 drift signatures). Zero behavior change when flags unset. Plus doc PRs #190 (thread-policy) + #191 (auto-loop xref). Delegated-agent + maintainer-fixup pattern; Codex MCP gpt-5.5 xhigh review caught 6+ blockers

• 2026-05-01 — 🔍 Gemini + OpenAlex literature sources for /research-lit (#175, community contribution by @stdAri). Two opt-in sources: /gemini-search (AI-driven discovery via jamubc/gemini-mcp-tool MCP) and /openalex (250M+ work open citation graph, no API key). Triggered via — sources: gemini or — sources: openalex; zero behavior change when default all (both excluded). Maintainer fixups: corrected @google/gemini-cli npm name; added try/except ImportError + bash preflight for graceful OpenAlex skip when requests missing

• 2026-04-30 — 📝 /rebuttal per-reviewer thread mode + transferable patterns (SKILL.md). Adds VENUE_MODE (single_document | per_reviewer_thread) for OpenReview-style venues, reviewer_priority: pivotal routing, structural_distinction response mode, 5 reviewer-defensive heuristics, 2 Phase 5 lints, and severity-scaled stress rounds. Default VENUE_MODE = single_document keeps ICML-style behavior — zero change for existing users. Three rounds of cross-model review before/after merge

• 2026-04-30 — 🪞 Codex skill mirror rebuilt + dedicated install/update chain (#179, community contribution by @No-518). skills/skills-codex/ now mirrors all 67 mainline skills; replaces mcp__codex__codex reviewer path with Codex-native spawn_agent + send_input. New tools/install_aris_codex.sh + tools/smart_update_codex.sh handle project-local symlinks with manifest tracking. Anti-drift: tests/test_codex_skill_mirror.py + tests/test_codex_install_update.py (26 failure paths). Open discussion in #184

• 2026-04-24 — 🎨 /paper-illustration-image2 — Codex-native image generation as Phase 2b illustration backend (#166, community contribution by @kbr19-thu 清华). Uses ChatGPT Plus/Pro quota via local Codex app-server MCP bridge — no GEMINI_API_KEY required. Triggered by /paper-writing — illustration: codex-image2; default stays figurespec (zero behavior change). Async-only API, sandboxed writes to figures/ai_generated/, integration-contract-compliant helper. Marked experimental (Codex debug app-server is unstable upstream)

• 2026-04-21 — 📚 Research Wiki ingest actually works now (research_wiki.py, /research-wiki). Fixes user-reported bug where /research-wiki init left papers/ empty forever (ingest subcommand had no implementation; paper-reading skills had no wiki hook). New canonical python3 tools/research_wiki.py ingest_paper helper owns slugging / metadata fetch / dedup / page render; all 6 paper-reading skills wired to it. Manual backfill via sync --arxiv-ids or sync --from-file. Ships with integration-contract.md formalizing the six-component pattern every cross-skill integration must follow

• 2026-04-21 — 🛡️ Assurance Gate: — effort: beast | max now really runs mandatory audits (assurance-contract.md, tools/verify_paper_audits.sh). Fixes silent-skip of /proof-checker / /paper-claim-audit / /citation-audit at high effort. New assurance axis (draft | submission) independent from effort: lite / balanced → draft (zero behavior change), max / beast → submission. At submission the 3 audits emit a JSON artifact with 6-state verdict; paper-writing Phase 6 runs the external verifier as source of truth (non-zero exit blocks Final Report). SHA256 input hashing catches stale audits. Escape hatch: — effort: beast, assurance: draft

• 2026-04-20 — 🩹 Project install: flat layout + manifest tracking — fixes a real bug where the previous nested install (.claude/skills/aris/) hid skills from Claude Code's slash-command discovery (CC only scans one directory level). Anyone who ran install_aris.sh before this date was silently affected. New install_aris.sh creates one symlink per skill at .claude/skills/<name>, writes a versioned manifest to .aris/installed-skills.txt, and is re-runnable to reconcile new/removed upstream skills. Defense-in-depth: 13 safety rules (no-symlinked-parents, exact-target revalidation, slug regex, atomic same-dir manifest rename, no-overwrite-real-files, mkdir-based portable lock, ADOPT for crash recovery, …). Granular --adopt-existing / --replace-link flags replace the all-or-nothing --force. Migration paths: --from-old for legacy nested symlink, --migrate-copy keep-user|prefer-upstream for legacy nested copy. smart_update.sh --target-subdir .claude/skills/aris is now deprecated with a redirect to install_aris.sh. Stale-file bug in cp -r overlay also fixed (now rm -rf && cp -r for safe-update path)

• 2026-04-19 — 🔗 /overleaf-sync — two-way bridge between local ARIS paper directory and an Overleaf project via the official Overleaf Git bridge (Premium). Lets collaborators keep editing in the Overleaf web UI while ARIS audit/edit pipelines (/paper-claim-audit, /citation-audit, /auto-paper-improvement-loop) keep running locally. Sub-commands: setup (one-time, user-driven so the agent never sees the token) / pull (with diff-protocol — flags half-sentences, typos, claim/cite changes that should re-trigger audits) / push (with confirmation gate before writing to shared Overleaf state) / status (3-way divergence check). Token never touches the agent or any file — primed once into macOS Keychain via the user's terminal, then auth-free for all subsequent agent operations

• 2026-04-19 — 📚 /citation-audit — fourth and final layer of the evidence-and-claim assurance stack (experiment-audit → result-to-claim → paper-claim-audit → citation-audit). Fresh cross-family reviewer (gpt-5.4 via Codex MCP) with web/DBLP/arXiv lookup verifies every \cite{...} along three independent axes: existence (paper resolves at claimed arXiv ID/DOI/venue), metadata correctness (authors/year/venue/title match canonical sources), and context appropriateness (the cited paper actually establishes the claim it supports — the most diagnostic check). Per-entry verdicts: KEEP / FIX / REPLACE / REMOVE. Auto-integrated into Workflow 3 Phase 5.8 as the pre-submission bibliography gate. Empirical motivation: in a real submission run, several real papers were cited in contexts they did not actually support, and at least one entry shipped with author = "Anonymous" — none caught by metadata-only checks

• 2026-04-17 — 🔀 /experiment-queue integrated into Workflow 1.5 + research-pipeline — experiment-bridge Phase 4 Deploy now auto-routes by milestone job count: ≤5 jobs → /run-experiment, ≥10 jobs or phase dependencies → /experiment-queue (with OOM retry, stale-screen cleanup, wave-transition gating, crash-safe state). New --- batch: queue override for global force-queue mode. Large multi-seed sweeps from EXPERIMENT_PLAN.md (e.g., 36-cell N × seed × n_train grids) now get proper orchestration without manual queue invocation

• 2026-04-17 — 🔗 Project-local symlink install (resolves #118) — new recommended default install. bash tools/install_aris.sh auto-detects platform (Claude Code / Codex CLI), creates .claude/skills/aris or .agents/skills/aris symlink to the ARIS repo, adds a managed `` block to CLAUDE.md / AGENTS.md telling the agent to use only project-local skills, and records install metadata in .aris/skill-source.txt. Solves the skill collision problem when ARIS is mixed with Superpowers / OpenHands / other community packs in the same global skill directory. PowerShell version (install_aris.ps1) ships with junction support for Windows. smart_update.sh --target-subdir flag added for .agents/skills/aris (Codex) project-copy installs; symlinked installs now correctly refuse smart_update and direct users to git pull. Global install remains supported for power users

• 2026-04-16 — 🎨 /figure-spec — deterministic JSON→SVG renderer packaged as a first-class skill. Preferred default for architecture/workflow/pipeline/audit-cascade figures in papers. Shape-aware edge clipping (rect/circle/ellipse/diamond), self-loops, curved edges, multi-line labels with CJK width estimation. Editable vector output, reproducible (same spec → same SVG), no external API. Phase 2b in Workflow 3 restored: illustration: figurespec (new default) / gemini / mermaid / false — 4-way illustration selector with complementary strengths

• 2026-04-16 — ⚙️ /experiment-queue — SSH job queue for multi-seed/multi-config ML experiments. Designed from real 36-cell NeurIPS sweep pain points: OOM-aware retry with backoff, stale-screen cleanup, wave-transition race prevention, teacher→student phase dependencies, crash-safe scheduler that resumes from JSON state. Declarative grid specs expand automatically (e.g., N × seed × n_train → 36 jobs). Configurable conda_hook + gpu_free_threshold_mib for non-standard environments. Use for ≥10 jobs; /run-experiment stays for ad-hoc

• 2026-04-15 — 🛡️ Paper Writing Pipeline Hardening — 10 empirically-motivated patches from a real NeurIPS run. REVIEWER_BIAS_GUARD=true: every review round uses a fresh thread (codex-reply inflated 3→8/10). Reviewer Independence Protocol: no fix summaries to reviewer. Step 4.5 Restatement Regression Test: catches theorem drift across fix rounds. Step 5.5 Kill Argument Exercise: final-round adversarial attack/defense for theory papers. Location-aware overfull blocking. Theory Paper Consistency Pass in /paper-write. Enforced Bib Hygiene with DBLP/CrossRef validation. Phase 5.5 Mandatory Final Claim Audit as submission gate. Review Tracing Protocol: full prompt/response pairs saved to .aris/traces/ for reviewer-independence audit (review-tracing.md, save_trace.sh). Inspired by community contribution from @李傲龍

• 2026-04-15 — 🎨 FigureSpec Renderer v2 — deterministic JSON→SVG figure generation for academic papers. Shape-aware edge clipping (rect/circle/ellipse/diamond), self-loops, curved edges, multi-line labels with CJK width estimation, comprehensive validation (type checks, structure, palette). Went through 5 rounds of Codex review (3/10→7/10). All architecture and workflow diagrams in the ARIS tech report were generated with this pipeline. New --- mode: vector for /paper-illustration skill

• 2026-04-14 — 📋 /paper-claim-audit — zero-context paper-to-evidence verification. Fresh reviewer with NO prior context compares every number in the paper against raw result files. Catches rounding inflation, best-seed cherry-pick, config mismatch, delta errors, scope overclaim. Auto-integrated into Workflow 3 (Phase 4.7). Completes the 3-layer audit chain: /experiment-audit (code) → /result-to-claim (science) → /paper-claim-audit (reporting). 👁️ Visual PDF review also added to improvement loop — reviewer now sees compiled PDF, not just LaTeX source. Inspired by Hermes Agent

• 2026-04-13 — 🧿 GPT-5.4 Pro via Oracle — — reviewer: oracle-pro on any skill for the strongest available reviewer. API mode (fast) or browser mode (free). Supported on: /research-review, /auto-review-loop, /experiment-audit, /proof-checker, /rebuttal, /idea-creator, /research-lit. Default stays Codex xhigh. Not installed = zero impact. Setup →

• 2026-04-13 — 🔬 /proof-checker — rigorous mathematical proof verification via cross-model review. 20-category issue taxonomy, two-axis severity, side-condition checklists (DCT/MCT/Fubini/IFT/...), counterexample red team, proof-obligation ledger. Auto-integrated into Workflow 3: detects \begin{theorem} and runs before improvement loop. Complements /proof-writer

• 2026-04-10 — ⚡ Effort Levels — — effort: lite | balanced | max | beast. Controls work intensity across all skills: papers found, ideas generated, review rounds, writing depth. Codex reasoning stays xhigh always. beast = every knob to maximum for top-venue sprints. Default balanced = zero change for existing users. Details →

• 2026-04-10 — 🔎 DeepXiv integration — progressive paper retrieval via DeepXiv CLI. Opt-in: — sources: deepxiv or — sources: all, deepxiv. Staged reading: search → brief → head → section. pip install deepxiv-sdk to enable. Community contribution by @DreamEnding

• 2026-04-10 — 🛡️ /experiment-audit — cross-model experiment integrity verification. GPT-5.4 reads your eval scripts and results directly, checks for fake ground truth, self-normalized scores, phantom results, and scope inflation (#131, #57). Advisory — warns loudly, never blocks. /result-to-claim auto-reads audit if present. New experiment-integrity.md shared reference. The executor must never judge its own integrity.

• 2026-04-10 — 🧠 tools/smart_update.sh — intelligent skill updater. Compares local vs upstream, detects personal customizations (server paths, API keys), only updates safe skills. bash tools/smart_update.sh --apply

• 2026-04-10 — 🏆 Community paper: UAV-CC — first community paper with full PDF archived. UAV change captioning benchmark for IEEE TGRS by @wxx827. Stack: Claude Opus 4.6 + Codex 5.4 xhigh + Cursor. Papers now archived in community_papers/

• 2026-04-08 — 📚 /research-wiki — persistent research knowledge base inspired by Karpathy's LLM Wiki. Accumulates papers, ideas, experiments, and claims across the entire research lifecycle with typed relationships. Wiki-aware hooks in /research-lit (ingest papers), /idea-creator (read wiki + write ideas back), and /result-to-claim (update claim status + trigger re-ideation). Failed ideas become anti-repetition memory. ARIS now learns from its mistakes.

• 2026-04-05 — 🧬 /meta-optimize — outer-loop harness optimization for ARIS. Passively logs skill invocations, tool calls, failures, and parameter overrides via Claude Code hooks. Run /meta-optimize to analyze accumulated usage data and propose SKILL.md improvements — reviewer-gated, user-approved. Inspired by Meta-Harness (Lee et al., 2026). ARIS now optimizes itself.

• 2026-04-04 — 🔧 Codex Plugin deep integration — /codex:rescue now auto-invoked when experiments fail (Workflow 1.5) or LaTeX won't compile (Workflow 3). GPT independently diagnoses the bug before Claude retries — two AI debuggers are better than one. Optional: codex exec powers nightmare review, /codex:rescue powers auto-debug. Setup →

• 2026-04-03 — ☁️ Modal serverless GPU — no GPU? gpu: modal in CLAUDE.md, one command (modal run launcher.py), no SSH, no Docker, auto scale-to-zero. $30/month free tier — enough to try ARIS experiments without any hardware. pip install modal && modal setup and go. Community contribution by @zeyuzhangzyz

• 2026-04-03 — 🎮 Reviewer Difficulty Levels — medium (default, unchanged), hard (reviewer memory + debate protocol), nightmare (GPT reads repo directly via codex exec — Claude can't hide anything). — difficulty: nightmare for maximum stress test before submission

• 2026-03-30 — 🔥 Auto-debug & exhaust-before-surrender — experiment-bridge auto-diagnoses failures (OOM, import, CUDA, NaN) and retries up to 3×. Inspired by PUA

• 2026-03-30 — ☁️ Vast.ai GPU rental — gpu: vast auto-rents cheapest GPU. By @YIHONG-JIN. 🔧 MiniMax M2.7 upgrade by @octo-patch

• 2026-03-27 — 📄 IEEE venue support (9 families). 🔎 Semantic Scholar. By @ypd666

• 2026-03-26 — 📄 Document-based input — RESEARCH_BRIEF.md auto-detect

• 2026-03-24 — 📝 Workflow 4: /rebuttal — 7-phase pipeline, 3 safety gates

• 2026-03-23 — 🔧 /training-check, /result-to-claim, /ablation-planner integrated. 📦 compact mode. By @JingxuanKang & @couragec

• 2026-03-22 — 📋 Templates — input templates for every workflow. 📄 7 venue templates — CVPR, ACL, AAAI, ACM MM added. 🛡️ Anti-hallucination fix — Workflow 2 enforces DBLP → CrossRef → [VERIFY]. 🔗 base repo — clone a GitHub repo as base codebase (— base repo: https://github.com/org/project)

• 2026-03-22 — 🔍 Codex + Gemini review guide — Codex executes, Gemini reviews via local gemini-review MCP bridge. CN

• 2026-03-20 — 🚀 Antigravity adaptation guide — use ARIS skills in Google Antigravity (agent-first IDE). Community contribution by @PeppaPigw

• 2026-03-20 — 🖥️ Trae adaptation guide — use ARIS skills in Trae (ByteDance AI IDE). Community contribution by @Prometheus-cotigo. 🔢 formula-derivation — Community contribution by @Falling-Flower

• 2026-03-19 — 🖼️ paper-poster — Conference poster. Community contribution by @dengzhe-hou

• 2026-03-19 — 🔗 Workflow 1.5 upgraded — /experiment-bridge GPT-5.4 code review. 📊 W&B fix

• 2026-03-18 — 🎤 paper-slides + 🔁 Codex+Claude bridge + 🖱️ Cursor guide + 🤖 Codex CLI skills + 📝 grant-proposal + 🎨 paper-illustration (Gemini) + 📊 CitationClaw

• 2026-03-17 — 🔧 Git code sync + 🆓 ModelScope guide + parameter pass-through

• 2026-03-16 — 🔬 research-refine + experiment-plan — turn vague ideas into problem-anchored proposals with claim-driven experiment roadmaps. Now integrated into Workflow 1 (/idea-discovery). Community contribution by @zjYao36

• 2026-03-16 — 🇨🇳 Alibaba Coding Plan guide — one API key, 4 models (Kimi-K2.5 + Qwen3.5+ + GLM-5 + MiniMax-M2.7), dual-endpoint setup. Community contribution by @tianhao909

• 2026-03-15 — 🔀 Bring your own model! Any OpenAI-compatible API now works as reviewer via llm-chat MCP server. GLM, MiniMax, Kimi, LongCat, DeepSeek all tested — zero Claude or OpenAI API needed

• 2026-03-15 — 🐾 OpenClaw adaptation guide — use ARIS research workflows in OpenClaw without Claude Code slash skills

• 2026-03-15 — 📐 proof-writer — community skill for rigorous theorem proof drafting. 📚 Anti-hallucination citations — /paper-write now fetches real BibTeX from DBLP/CrossRef instead of LLM-generated entries — on by default, zero install

• 2026-03-14 — 📱 Feishu/Lark integration: three modes (off/push/interactive), mobile notifications for experiments, reviews, and checkpoints

• 2026-03-13 — 🛑 Human-in-the-loop: configurable AUTO_PROCEED checkpoints across all workflows. Full autopilot or step-by-step approval

• 2026-03-12 — 🔗 Zotero + Obsidian + local PDFs + arXiv/Scholar: multi-source literature search with cross-model novelty verification

• 2026-03-12 — 🚀 Three end-to-end workflows complete: one prompt → top-venue-style paper. /research-pipeline chains idea discovery → auto review → paper writing autonomously

• 2026-03-12 — 📝 /paper-writing workflow: narrative report → structured outline → figures → LaTeX → compiled PDF → 2-round auto-improvement (4/10 → 8.5/10)

3. 🚀 Quick Start Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Don't need all 85 skills? See Selective install below for group/skill-level picks.

Optional Grok CLI bridge: grok-exec exposes grok / grok-reply using your existing Grok CLI login, with grok-4.7 + xhigh defaults, persistent sessions, progress and cancellation. It is a separate MCP service; installing it does not change the reviewer routing of existing skills.

Selectable CLI reviewers: antigravity-exec and grok-exec support the complete packs through — reviewer: antigravity / grok; see the backend contract. The legacy — reviewer: agy still uses gemini-review.

📚 Research Wiki (optional) — one-line init for persistent memory across sessions; see full Research Wiki section

Give ARIS persistent memory across sessions. Papers, ideas, failed experiments — nothing is forgotten:

# In Claude Code:
> /research-wiki init                         # creates research-wiki/ in your project
# That's it. From now on, /research-lit auto-ingests papers, /idea-creator reads
# the wiki before brainstorming (and writes ideas back), /result-to-claim updates
# claim status. Failed ideas become anti-repetition memory for future ideation.

🧬 Meta-Optimization (optional) — passive usage logging + /meta-optimize for data-driven SKILL.md improvements; see full Workflow M section

Run these in your normal terminal (not inside Claude Code) to enable passive usage logging:

# One-time setup in your project directory
mkdir -p .claude .aris/meta tools/meta_opt
cp Auto-claude-code-research-in-sleep/templates/claude-hooks/meta_logging.json .claude/settings.json
cp Auto-claude-code-research-in-sleep/tools/meta_opt/*.sh tools/meta_opt/
chmod +x tools/meta_opt/*.sh
# Then start Claude Code — hooks are active immediately
claude

Events are logged to both project-level (.aris/meta/events.jsonl) and global (~/.aris/meta/events.jsonl) logs. After 5+ workflow runs, run /meta-optimize to see data-driven improvement proposals. Use /meta-optimize --global to analyze trends across all your projects.

📝 Templates + 🔎 DeepXiv + 🔎 Exa + 🗑️ Uninstall — input templates, two extra literature sources, and the uninstall command

📝 Templates available! See templates/ for ready-to-use input templates for every workflow — research brief (Workflow 1), experiment plan (Workflow 1.5), narrative report (Workflow 3), paper plan (Workflow 3).

🔎 Optional: DeepXiv progressive retrieval

pip install deepxiv-sdk

Then use /deepxiv directly or opt into it from /research-lit with — sources: deepxiv or — sources: all, deepxiv.

🔎 Optional: Exa AI-powered web search

pip install exa-py
export EXA_API_KEY=your-key-here

Then use /exa-search directly or opt into it from /research-lit with — sources: exa or — sources: all, exa. Covers blogs, docs, news, and research papers with built-in content extraction.

🗑️ Uninstall: To remove ARIS skills without affecting your own personal skills:

cd Auto-claude-code-research-in-sleep && ls skills/ | xargs -I{} rm -rf ~/.claude/skills/{}

Show all 16 inline parameters and 14 override examples — AUTO_PROCEED / sources / arxiv download / DBLP_BIBTEX / code review / wandb / illustration / venue / base repo / gpu / compact / ref paper / effort / reviewer / difficulty (full per-skill defaults live in § Customization)

All pipeline behaviors are configurable via inline overrides — append — key: value to any command:

/* Detailed source-code truncated for AI context efficiency. */

Sandbox behavior and strict mode — control whether tool-call overrides may change the configured sandbox policy

The runtime's sandbox settings provide a configured baseline, while a tool request may also carry sandbox-related overrides. In the legacy compatibility mode, the effective request can therefore differ from the values written in settings.json.

To make the configured policy authoritative, enable strictMode:

{
  "sandbox": {
    "enabled": true,
    "strictMode": true
  }
}

With strictMode: true, the runtime ignores these LLM-supplied overrides: dangerouslyDisableSandbox, namespaceRestrictions, isolateNetwork, filesystemMode, and allowedMounts. The configured sandbox policy remains in effect even when a tool call requests a different value. This is opt-in so existing configurations keep their legacy behavior by default.

Run aris doctor to inspect the currently reported sandbox state. strictMode controls whether tool requests can override the runtime configuration; it does not replace the host operating system's permissions, filesystem protections, or network policy.

Codex MCP config + alternative reviewer routing — pin the model in ~/.codex/config.toml; pointers to Codex+Claude-review, Codex+Gemini-review, and the Codex mirror install chain

Important: ARIS skills pin the reviewer explicitly (model: gpt-6-astra + a per-tier reasoning effort) in every fresh call — your ~/.codex/config.toml no longer silently decides the reviewer. Still set model = "gpt-6-astra" there (recommended): it covers codex-native/mirror sessions and anything that doesn't pin. ultra/max effort needs codex-cli ≥ 0.144.1 + a session restart.

Choose a reviewer in Codex: install the full skills/skills-codex/ pack and select — reviewer: claude-code, antigravity, or grok. See the backend contract for bridge setup and session rules.

The old Claude/Gemini partial overlays are frozen for existing installations; migrate safely to the full pack. The historical Claude and Gemini guides describe those legacy installations.

Want the Codex mirror install chain? Use tools/install_aris_codex.sh for managed project installs and tools/smart_update_codex.sh for copied Codex installs. The Claude scripts remain the mainline entry points for Claude projects.

The base Codex mirror defaults to a fresh Codex reviewer: same-family reviews remain provisional. Other routes require actual model identities and a completed, in-scope review before cross-family acceptance; a backend selection alone is insufficient. Submission and deterministic verification gates still apply.

See full setup guide for details and alternative model combinations if you don't have Claude/OpenAI API.

4. ✨ Features Copy Chapter

ARIS chains 85 composable skills across the whole research lifecycle — literature & novelty → idea discovery → GPU experiments → autonomous review loop → paper writing → peer review — with cross-model adversarial review (Claude executes · GPT-6-Astra xhigh reviews · optional GPT-5.5 Pro via Oracle), anti-hallucination DBLP/CrossRef citations, a persistent Research Wiki, flexible model backends, human-in-the-loop checkpoints, and optional Feishu / Zotero / Obsidian / GPU integrations.

🔥 And it scales to any agent's ultracode-style deep mode — the breadth/firepower pass adapts to the runtime (Claude Code ultracode + workflows on Opus 4.8, Codex spawn_agent, or plain sequential), feeding three roles: breadth · cross-model review → accuracy · research wiki → memory. However a loop is driven, it reports to the same cross-model jury + research wiki — it can drive, never acquit.

Full feature list

• 📊 85 composable skills — mix and match, or chain into full pipelines (/idea-discovery, /auto-review-loop, /paper-writing, /research-pipeline). See full catalog →

• 🔍 Literature & novelty — multi-source paper search (Zotero + Obsidian + local PDFs + arXiv/Scholar) + cross-model novelty verification

• 💡 Idea discovery — literature survey → brainstorm 8-12 ideas → novelty check → GPU pilot experiments → ranked report

• 🔄 Auto review loop — 4-round autonomous review, 5/10 → 7.5/10 overnight with 20+ GPU experiments

• 📝 Paper writing — narrative → outline → figures → LaTeX → PDF → auto-review (4/10 → 8.5/10), one command. Anti-hallucination citations via DBLP/CrossRef

• 🤖 Cross-model collaboration — Claude Code executes and GPT-6-Astra reviews; in Copilot CLI, /auto-review-loop uses the native complementary rubber-duck model and verifies the actual cross-family pair from host events. Optional: — reviewer: oracle-pro → GPT-5.5 Pro via Oracle

• 📝 Peer review — review others' papers as a conference reviewer, with structured scoring and meta-review

• 🖥️ Review-driven experiments — when GPT-6-Astra says "run an ablation", Claude auto-writes the script, rsyncs to GPU, runs in screen, collects results, folds back into the paper. Configure server in CLAUDE.md (setup), or rent from Vast.ai with gpu: vast

• 🔀 Flexible models — default Claude × GPT-6-Astra, also supports GLM, MiniMax, Kimi, LongCat, DeepSeek, etc. — no Claude or OpenAI API required

• 🛑 Human-in-the-loop — configurable selection checkpoints. AUTO_PROCEED=true reports the choice and continues in the same turn; false asks for approval. Explicit Feishu interactive gates remain user-controlled

• 📱 Feishu/Lark notifications — three modes: off (default, recommended), push-only (webhook → mobile), interactive (approve/reject in Feishu). Zero impact when off

  Preview: Push cards (group) & Interactive chat (private)

  Push Only — group chat cards (experiment done, checkpoint, error, pipeline complete):

  Interactive — private chat with Claude Code (approve/reject, custom instructions):

• 📚 Research Wiki — persistent knowledge base across papers/ideas/experiments/claims. Failed ideas become anti-repetition memory — ARIS gets smarter every run. Inspired by Karpathy's LLM Wiki

• 🧩 Extensible — domain-specific skills welcome! Add a SKILL.md and open a PR. See community skills like dse-loop (architecture/EDA)

ARIS ships 85+ skills across literature, ideation, experiments, audit, writing, talks, patents, and meta-utilities — the full catalog (role / category / requirements per skill) lives in docs/SKILLS_CATALOG.md to keep this README scannable.

Start here — common entry points (use case → skill)

→ Browse all 85 skills by category in the full catalog →

5. 📈 Score Progression (Real Run) Copy Chapter

A real overnight 4-round run on an ML research project — the AI reviewer's score climbed 5.0/10 (borderline reject) → 7.5/10 (review-ready) as the loop autonomously ran 20+ GPU experiments, rewrote the narrative framing, and killed claims that didn't hold up, all without human intervention.

Round-by-round breakdown

6. 🏆 Community Showcase — Papers Built with ARIS Copy Chapter

Real projects that used the full ARIS pipeline end-to-end. The scores listed are AI-review signals (CSPaper / Stanford Agentic Reviewer), not venue acceptances — and since ARIS optimizes through AI-review loops, high AI scores are an expected byproduct, not proof of acceptance (human reviewers still bring literature / venue / community judgment an AI reviewer misses). Used ARIS for a paper? Open an issue / PR to be featured!

Papers + their AI-review signals (3)

Reviewer screenshots

7. 🧩 Awesome Community Skills & Extensions Copy Chapter

Domain-specific skills and external projects contributed by the community. PRs welcome — just add a skills/your-skill/SKILL.md and open a PR!

💡 How to use: Community skills are not auto-wired into core workflows. To use one, ask your executor (Claude Code / OpenClaw / etc.) to read the skill's SKILL.md, then plug it into the appropriate workflow stage based on the description below.

🎉 Community Skills (15): research-refine · experiment-plan · research-refine-pipeline · grant-proposal · paper-poster (deprecated → paper-poster-html) · paper-slides · mermaid-diagram · proof-writer · comm-lit-review · dse-loop · idea-discovery-robot · formula-derivation · paper-illustration · writing-systems-papers · skills-codex

🌐 External Projects & Docs (16): rosetta · open-source-hardening-skills · CitationClaw · auto-hparam-tuning · paper-to-course · deep-research-skills · Antigravity Adaptation Guide · OpenClaw Adaptation Guide · Cursor Adaptation Guide · Codex+Claude Review Bridge · Trae Adaptation Guide · MiniMax-AI/cli · posterly · Claude Fleet · anti-defensive-writing-Skill · OrcaReplay

🙌 Thanks to every contributor! We fold the tables below to keep the README readable — but every skill and project here is equally valued. PRs always welcome!

🎉 Community Skills (15) — click to expand

🌐 External Projects & Docs (16) — click to expand

8. 🔄 Workflows Copy Chapter

These skills compose into a full research lifecycle. Each workflow can be used independently or chained together:

• Exploring a new area (e.g., writing a survey)? Start with Workflow 1 → /idea-discovery
• Have a plan, need to implement and run? Workflow 1.5 → /experiment-bridge
• Already have results, need iterative improvement? Workflow 2 → /auto-review-loop
• Ready to write the paper? Workflow 3 → /paper-writing (or step by step: /paper-plan → /paper-figure → /paper-write → /paper-compile → /auto-paper-improvement-loop)
• Got reviews back? Need to rebuttal? Workflow 4 → /rebuttal — parse reviews, draft safe rebuttal, follow-up rounds
• Full pipeline? Workflow 1 → 1.5 → 2 → 3 → submit → 4 → /research-pipeline + /rebuttal — from idea through submission and rebuttal
• Need a multi-session proof campaign? Workflow 7 → /proof-orchestrator — run-directory proof runs, GPT Pro handoff packages, cross-run continuation
• Want ARIS to remember and learn? 📚 /research-wiki init — persistent memory across sessions. Papers, ideas, failed experiments compound over time
• Want ARIS to improve itself? Workflow M → /meta-optimize — analyze usage logs, propose skill improvements, reviewer-gated

⚠️ Important: These tools accelerate research, but they don't replace your own critical thinking. Always review generated ideas with your domain expertise, question the assumptions, and make the final call yourself. The best research comes from human insight + AI execution, not full autopilot.

Full Pipeline 🚀 Copy Section

/research-lit → /idea-creator → /novelty-check → /research-refine → /experiment-bridge → /auto-review-loop → /paper-writing → submit → /rebuttal → accept! 🎉
  (survey)      (brainstorm)    (verify novel)   (refine method)   (implement+deploy)  (review & fix)      (write paper)   (send)   (reply to reviewers)
  ├────────────── Workflow 1: Idea Discovery ──────────────┤ ├ Workflow 1.5 ─┤ ├── Workflow 2 ──┤ ├── Workflow 3 ──┤         ├── Workflow 4 ──┤

                                     📚 research-wiki (persistent memory — papers, ideas, experiments, claims)
                                        ↕ reads before ideation, writes after every stage, failed ideas = anti-repetition memory

                                              /meta-optimize (Workflow M — runs independently, improves ARIS itself)
                                                 ↑ reads .aris/meta/events.jsonl (accumulated from all runs above)

Workflow 1: Idea Discovery & Method Refinement 🔍 Copy Section

"What's the state of the art? Where are the gaps? How do we solve it?"

Don't have a concrete idea yet? Just give a research direction — /idea-discovery handles the rest:

1. 📚 Survey the landscape (recent papers, open problems, recurring limitations)
2. 🧠 Brainstorm 8-12 concrete ideas via GPT-6-Astra xhigh
3. 🔍 Filter by feasibility, compute cost, and quick novelty search
4. 🛡️ Validate top ideas with deep novelty check + devil's advocate review
5. 🧪 Pilot top 2-3 ideas in parallel on different GPUs (30 min - 2 hr each)
6. 🏆 Rank by empirical signal — ideas with positive pilot results rise to the top
7. 🔬 Refine the top idea into a problem-anchored proposal via iterative GPT-6-Astra review
8. 🧪 Plan claim-driven experiments with ablations, budgets, and run order

The output is a ranked IDEA_REPORT.md plus a refined proposal (refine-logs/FINAL_PROPOSAL.md) and experiment plan (refine-logs/EXPERIMENT_PLAN.md) for the top idea. Dead-end ideas are documented too, saving future exploration.

Show W1 flow diagram and example command sequence — research-lit → idea-creator → novelty-check → research-refine → experiment-plan

/* Detailed source-code truncated for AI context efficiency. */

Skills involved: research-lit + idea-creator + novelty-check + research-review + research-refine-pipeline

💡 One-command shortcut: /idea-discovery "your research direction" runs this entire workflow automatically.

🔄 Human-in-the-loop: At each AUTO_PROCEED-controlled selection checkpoint, true reports results and continues in the same turn; false asks for your feedback before continuing. If you request changes, tell it what's missing — it refines the prompt and regenerates. Explicit gates such as Feishu interactive approval remain user-controlled.

⚙️ Pilot experiment budgets (max hours, timeout, GPU budget) are configurable — see Customization.

📝 Blog post: Claude Code 两月 NeurIPS 指北

Workflow 1.5: Experiment Bridge 🔗 Copy Section

"I have a plan. Now implement it, deploy it, and get me initial results."

Already have an experiment plan (from Workflow 1 or your own)? /experiment-bridge turns it into running code:

1. 📋 Parse the experiment plan (refine-logs/EXPERIMENT_PLAN.md)
2. 💻 Implement experiment scripts (reuse existing code, add proper argparse/logging/seeds)
3. 🔍 GPT-6-Astra code review — cross-model review catches logic bugs before wasting GPU hours (code review: true by default)
4. ✅ Sanity check — run the smallest experiment first to catch runtime bugs
5. 🚀 Deploy full experiment suite to GPU via /run-experiment
6. 📊 Collect initial results and update the experiment tracker

Show W1.5 flow diagram — experiment plan → Claude implements → GPT-6-Astra code review → sanity check → GPU deploy → monitor → results

/* Detailed source-code truncated for AI context efficiency. */

Skills involved: experiment-bridge + run-experiment + monitor-experiment

💡 One-command shortcut: /experiment-bridge reads refine-logs/EXPERIMENT_PLAN.md automatically. Or point it to any plan: /experiment-bridge "my_plan.md".

⚙️ CODE_REVIEW, AUTO_DEPLOY, SANITY_FIRST, MAX_PARALLEL_RUNS are configurable — see Customization.

Workflow 2: Auto Research Loop 🔁 (sleep & wake up to results) Copy Section

"Review my paper, fix what's wrong, repeat until it's good."

GPT-6-Astra reviews → identifies weaknesses → suggests experiments → Claude Code writes scripts, deploys to GPU, monitors results, rewrites the paper — all while you sleep. Just add your GPU server config to CLAUDE.md.

1. 🔍 Deep review — GPT-6-Astra xhigh reviews the current paper / claims / experiments and identifies weaknesses
2. 🩹 Fix — Claude implements the fixes (rewrites sections, adds baselines, or runs new experiments via /run-experiment); skips any experiment estimated > 4 GPU-hours and flags it for manual follow-up
3. 📊 Re-evaluate — collect results via /monitor-experiment, update paper, feed back to the reviewer
4. 🔁 Repeat — until score ≥ POSITIVE_THRESHOLD (default 6/10) or MAX_ROUNDS (default 4) is hit; if context window fills mid-loop, the workflow auto-resumes from REVIEW_STATE.json

Show W2 loop diagram — external review → implement fixes / run experiments → monitor results → repeat until threshold

┌─────────────────────────────────────────────────────────────┐
│                    Auto Review Loop                          │
│                                                              │
│   /research-review          /auto-review-loop                │
│   (single deep review)      (autonomous loop)                │
│         │                         │                          │
│         ▼                         ▼                          │
│   ┌──────────┐   ┌──────────┐   ┌──────────┐               │
│   │ External  │──▶│ Implement│──▶│ Monitor  │──▶ repeat     │
│   │ LLM      │   │ fixes    │   │ results  │    until       │
│   │ reviews  │   │ & run    │   │          │    score ≥ 6   │
│   └──────────┘   │ experiments│  └──────────┘               │
│                   └──────────┘                               │
│                                                              │
│   When reviewer suggests a new method direction:             │
│   /novelty-check — verify idea isn't already published       │
│                                                              │
│   Supporting skills:                                         │
│   /run-experiment    — deploy to local/remote/vast.ai GPU     │
│   /analyze-results   — interpret experiment outputs          │
│   /monitor-experiment — check progress, collect results      │
└─────────────────────────────────────────────────────────────┘

Skills involved: auto-review-loop + research-review + novelty-check + run-experiment + analyze-results + monitor-experiment

💡 One-command shortcut: /auto-review-loop "your paper topic" runs this entire workflow automatically.

Show W2 usage examples, reviewer difficulty levels, and full safety guarantees — topic/scope arguments, medium/hard/nightmare, 6 safety rules

What to pass as argument? A short topic or scope is enough — the skill automatically reads your project's narrative docs (NARRATIVE_REPORT.md), memory files, experiment results, and prior reviews to build the full context for GPT-6-Astra. Examples:

• /auto-review-loop "factorized gap in discrete diffusion LMs" — broad topic, skill finds everything
• /auto-review-loop "focus on Section 3-5, our CRF results are weak" — targeted scope with hints
• /auto-review-loop — also works: skill reads project files and infers the topic

🎮 Reviewer Difficulty — control how adversarial the reviewer is:

/auto-review-loop "topic" — difficulty: nightmare    # GPT reads your code and verifies claims itself

🛡️ Key safety features:

• 🔒 MAX_ROUNDS = 4 — prevents infinite loops; stops early if score threshold is met
• ⏱️ > 4 GPU-hour experiments skipped — won't launch massive jobs; flags them for manual follow-up
• 🧠 Prefer reframing over new experiments — when both can address a weakness, chooses the cheaper path
• 🪞 No hiding weaknesses — explicit rule: "Do NOT hide weaknesses to game a positive score"
• 🔧 Fix before re-review — must actually implement fixes before resubmitting; no empty promises
• 💾 Compact recovery — persists state (REVIEW_STATE.json) after each round. If the context window fills up and auto-compacts mid-loop, the workflow reads the state file and resumes from where it left off — no human intervention needed

⚙️ MAX_ROUNDS, score threshold, and GPU limits are configurable — see Customization.

📝 Blog post: 开源 | 睡觉 Claude 自动跑实验改文

Workflow 3: Paper Writing Pipeline 📝 Copy Section

"Turn my research narrative into a submission-ready PDF." Requires a local LaTeX environment — see Prerequisites.

1. 📝 Narrate — write NARRATIVE_REPORT.md (claims, experiments, results, figure descriptions); see templates/NARRATIVE_REPORT_TEMPLATE.md
2. 🧭 Plan — /paper-plan builds the claims-evidence matrix + section plan
3. 📊 Figures — /paper-figure generates data-driven plots and comparison tables from JSON/CSV
4. ✍️ Write — /paper-write produces section-by-section LaTeX
5. 🔧 Compile — /paper-compile builds the PDF, fixes errors, runs the page-limit check
6. ✨ Improve — /auto-paper-improvement-loop runs 2 rounds of GPT-6-Astra content review + final format check

Show W3 architecture diagram and exact writing flow — NARRATIVE_REPORT → /paper-plan → /paper-figure → /paper-write → /paper-compile → improvement loop

/* Detailed source-code truncated for AI context efficiency. */

Skills involved: paper-plan + paper-figure + paper-write + paper-compile + auto-paper-improvement-loop + (post-acceptance) paper-poster-html + paper-slides

One-command shortcut: /paper-writing "NARRATIVE_REPORT.md" runs this entire workflow automatically.

Input: A NARRATIVE_REPORT.md describing the research: claims, experiments, results, figures. The more detailed the narrative (especially figure descriptions and quantitative results), the better the output.

Output: A paper/ directory with LaTeX source, clean .bib (only cited entries), and compiled PDF. The PDF is labelled submission-ready only when run at — effort: max | beast (or explicit — assurance: submission) and tools/verify_paper_audits.sh reports green on the three mandatory audits (proof-checker, paper-claim-audit, citation-audit); see Assurance Gate below. At the default balanced level, the output is a reviewed draft.

Show W3 feature details — Claims-Evidence Matrix, figure modes, clean bib, Gemini API setup, ICLR end-to-end test

Key features:

• 📐 Claims-Evidence Matrix — every claim maps to evidence, every experiment supports a claim
• 📊 Auto figure generation — line plots, bar charts, comparison tables from JSON data
• 🧹 Clean bib — automated filtering removes uncited entries (948→215 lines in testing). Real BibTeX from DBLP/CrossRef instead of LLM-generated entries
• 📄 Flexible sections — 5-8 sections depending on paper type (theory papers often need 7)
• 🔍 GPT-6-Astra review — each step optionally reviewed by external LLM
• ✂️ De-AI polish — removes AI writing patterns (delve, pivotal, landscape...)
• 🎯 Page verification — pdftotext-based precise check that main body fits page limit

⚠️ Figure generation scope: /paper-figure auto-generates data-driven plots (training curves, bar charts, heatmaps) and comparison tables from JSON/CSV. For architecture diagrams and method figures: illustration: gemini (default) uses Claude→Gemini→Nano Banana Pro for publication-quality diagrams; illustration: mermaid generates Mermaid diagrams for free; illustration: false skips AI figures entirely.

Gemini API setup (for illustration: gemini): Get your API key at Google AI Studio, then set it as an environment variable: export GEMINI_API_KEY="your-key". Or add to your shell profile (~/.zshrc / ~/.bashrc). No other dependencies needed.

Tested end-to-end: Generated a 9-page ICLR 2026 theory paper (7 sections, 29 citations, 4 figures, 2 comparison tables) from a single NARRATIVE_REPORT.md — zero compilation errors, zero undefined references.

Auto Paper Improvement Loop ✨

After Workflow 3 generates the paper, /auto-paper-improvement-loop runs 2 rounds of GPT-6-Astra xhigh content review → fix → recompile, plus a final format compliance check, autonomously polishing the paper from rough draft to a reviewer-scored draft. Whether the result is tagged submission-ready is decided separately by the Phase 6 assurance gate (see Assurance Gate).

Show auto-paper-improvement benchmark — Score Progression on a real ICLR 2026 theory paper (4/10 → 8.5/10), plus Round 1/2/3 fix details

Score Progression (Real Test — ICLR 2026 theory paper):

Final: 8 pages main body (ICLR limit: 9), 0 overfull hbox, ICLR-compliant. +4.5 points across 3 rounds.

Round 1 fixes (6 items)

1. CRITICAL — Assumption-model mismatch: A boundedness assumption contradicted the model's distributional family. Replaced with a tail-compatible assumption and added formal truncation bridge.
2. CRITICAL — Theory-practice gap: Theory assumes idealized encoders, experiments use learned nonlinear encoders. Softened "validate" → "demonstrate practical relevance" and added explicit disclaimer.
3. MAJOR — Missing quantitative metrics: Added parameter count table (latent vs total) with honest accounting of system cost.
4. MAJOR — Theorem not self-contained: Added "Interpretation" paragraph listing all dependencies explicitly.
5. MAJOR — Overclaim in novelty statement: Scoped a broad "first convergence guarantee" to precise conditions under which it holds.
6. MAJOR — Notation confusion: Renamed a symbol that clashed with another key variable. Added Notation paragraph.

Round 2 fixes (4 items)

1. MAJOR — Missing theory-aligned experiments: Added a synthetic validation subsection directly testing the two main theoretical predictions under controlled conditions.
2. MAJOR — Overclaim softening: Replaced strong equivalence claims with appropriately hedged language across all files.
3. MAJOR — Informal theoretical argument: Formalized an informal justification into a proper proposition with explicit error bounds.
4. MINOR — Weak limitations: Expanded to explicitly list all assumptions and acknowledge missing standard evaluations.

Round 3 format fixes (8 items)

1. Removed hero figure block (saved ~0.7 pages)
2. Compressed conclusion from 15→9 lines
3. Moved synthetic validation to Appendix A
4. Moved comparison tables to Appendix B
5. Fixed overfull hbox (85pt) with \resizebox
6. Added compact float spacing (\captionsetup, \textfloatsep)
7. Inlined centered question block in introduction
8. Tightened itemize environments

Workflow 4: Rebuttal 📝 (reply to reviewers safely) Copy Section

"Reviews are in. Help me draft a safe, grounded rebuttal."

Got reviews back? /rebuttal parses them, builds a strategy, and drafts a venue-compliant response:

1. 📋 Parse — normalize reviews, validate venue rules (character limit, text-only, etc.)
2. 🔍 Atomize — split each review into issue cards (type, severity, reviewer stance)
3. 🗺️ Strategize — global themes, per-reviewer priorities, character budget, blocked claims
4. 🧪 Evidence sprint — if auto experiment: true, auto-run supplementary experiments via /experiment-bridge
5. ✍️ Draft — global opener + numbered per-reviewer responses + closing for meta-reviewer
6. 🛡️ Safety check — 6 lints: coverage, provenance, commitment, tone, consistency, limit
7. 🔬 GPT-6-Astra stress test — internal skeptical review of the draft
8. 📄 Finalize — two outputs: PASTE_READY.txt (exact character count) + REBUTTAL_DRAFT_rich.md (extended version for manual editing)
9. 🔄 Follow-up rounds — delta replies for reviewer discussions, technically escalating

Show W4 rebuttal flow diagram — parse reviews → strategy → optional evidence sprint → draft → GPT-6-Astra stress test → finalize 2 versions → follow-up rounds

/* Detailed source-code truncated for AI context efficiency. */

Skills involved: rebuttal

💡 Quick mode: /rebuttal — quick mode: true stops after parsing + strategy (Phase 0-3). See what reviewers want before committing to a full draft.

⚙️ VENUE, AUTO_EXPERIMENT, QUICK_MODE, MAX_STRESS_TEST_ROUNDS are configurable — see Customization.

Three safety gates — rebuttal will NOT finalize if any fails:

• 🔒 Provenance — every claim maps to paper/review/user-confirmed result. No fabrication.
• 🔒 Commitment — every promise is user-approved. No overpromising.
• 🔒 Coverage — every reviewer concern is tracked. Nothing disappears.

Workflow 5: Resubmit Pipeline 🔁 (port a paper to a new venue, text-only) Copy Section

Port a polished paper from venue A → B under hard, non-overridable guardrails — no new experiments · no bib edits · no framework changes · never overwrites prior submissions — via physical isolation, a 5-layer anonymity check, soft-only audits, whitelist microedits, and a /kill-argument adversarial gate. Full flow + constraints → docs/RESUBMIT_AND_TALK.md

Workflow 6: Conference Talk Pipeline 🎤 (paper → slides → polish → audits) Copy Section

/paper-talk turns an accepted paper into a talk: outline → /paper-slides (Beamer + PPTX + speaker notes + Q&A) → /slides-polish (per-page Codex visual pass) → optional conference-ready audit gate. Sister to /paper-writing / /paper-poster-html. Full flow → docs/RESUBMIT_AND_TALK.md

Workflow 7: Proof Orchestrator 🧭 (standalone theory track — attack a theorem across days, not turns) Copy Section

"This proof will take a week and three tools. Keep every attempt, audit, and escalation on the record."

Hard theorems are campaigns, not chat turns. /proof-orchestrator runs proof work as a stateful, local-first pipeline — each run gets its own directory, completed runs become append-only evidence, and every new run records which prior claims were proved, conjectural, or rejected:

1. 🎯 Freeze the target — exact theorem, assumptions, quantifiers, allowed sources; new run or continuation
2. 🧱 Maintain local evidence — run directory with task.md / materials.md / stable source snapshots
3. 🧠 Attempt locally — full proof, disproof, counterexample, or diagnosis; a stall isolates the smallest hard obligation
4. 🔍 Audit correctness — every lemma, bound, and quantifier checked against assumptions; claims labeled proved / imported / conjectural / repaired / unsupported
5. ✒️ Edit for exposition — two gates: the 7-line notation scorecard (100% core-object retention, zero undefined symbols, zero collisions) and the top-down derivation-structure gate (acyclic dependency graph, no subgoal silently assuming the target — a bug-catcher in disguise: a proof that resists a clean target-first rewrite is usually hiding a gap, and circular reasoning surfaces the moment you try)
6. 📦 GPT Pro handoff — a stalled proof becomes a package: browser-prompt.md (copy-paste ready), source-manifest.md (source roles), handoff.md (upload order + return instructions)
7. 🧾 Re-audit the returned proof — format repair only, then the full correctness audit and exposition edit produce final.md

Show W7 flow diagram — freeze target → local attempt → audit → notation/structure gates → GPT Pro handoff (when stalled) → re-audit → final.md, plus the optional DeepSeek branch

/* Detailed source-code truncated for AI context efficiency. */

Skills involved: proof-orchestrator (+ llm-chat MCP for the optional DeepSeek branch)

⚖️ Optional DeepSeek second opinion: request it at the audit stage for a verified cross-family adversarial pass — findings are validated locally and recorded as run-local provisional evidence. An installed call-gpt-pro skill can likewise automate the GPT Pro dispatch when you ask for it on a run.

🧭 Standalone by design. Workflow 7 is theory work's own track — no Workflow 1–6 stage calls it, and /proof-checker keeps the submission gate in Workflow 3. Reach for it when a theorem outgrows single-shot /proof-writer drafting: multi-day campaigns, cross-run continuation, or when the strongest available prover lives in a browser tab.

💡 Continuation: point it at a prior run (next.md / redo.md) — it reads final.md / audit.md, reuses only audited claims, and opens a fresh run directory with full provenance.

📚 Research Wiki — Persistent Research Memory Copy Section

"Stop re-deriving. Start compounding." — inspired by Karpathy's LLM Wiki

Without the wiki, ARIS is stateless — every /idea-discovery starts from scratch. With the wiki, ARIS accumulates knowledge across the entire research lifecycle: papers read, ideas tested, experiments run, claims verified or invalidated.

The key insight: failed ideas are the most valuable memory. A researcher who knows what doesn't work generates better ideas than one starting from zero.

Setup:

> /research-wiki init     # one-time, creates research-wiki/ in your project

That's it. Once initialized, the wiki works automatically.

Show the automatic wiki hooks — what fires at /research-lit, /idea-creator, /result-to-claim, plus the re-ideation nudge

Show Research Wiki data model — Paper / Idea / Experiment / Claim entities and the typed graph edges that connect them

Four entity types:

Typed relationships (stored in graph/edges.jsonl):

paper --extends--> paper              idea --inspired_by--> paper
paper --contradicts--> paper          idea --tested_by--> experiment
paper --addresses_gap--> gap          experiment --supports--> claim
paper --supersedes--> paper           experiment --invalidates--> claim

Show Research Wiki spiral-learning example and manual subcommands — failed ideas → better ideas across 3 rounds; ingest / query / update / lint / stats

Spiral learning in action:

Round 1: read 15 papers → wiki remembers → idea A → experiment → FAIL
         wiki records: "A fails because OOM at batch>32, loss diverges"

Round 2: /idea-creator reads wiki → sees A failed → generates idea D (avoids A's trap)
         → experiment → PARTIAL SUCCESS
         wiki records: "D works on small models, fails on large"

Round 3: /idea-creator reads wiki → knows A failed + D partial → generates idea F
         (combines D's success with new approach) → experiment → SUCCESS 🎉

Subcommands:

/research-wiki init                              # initialize wiki
/research-wiki ingest "paper title" — arxiv: xxx  # manually add a paper
/research-wiki query "topic"                      # rebuild query_pack.md
/research-wiki update idea:001 — outcome: negative # update entity
/research-wiki lint                               # health check (orphans, contradictions, stale claims)
/research-wiki stats                              # overview (paper/idea/experiment/claim counts)

🔒 Safe by design: All workflow hooks are guarded by if research-wiki/ exists. No wiki = no impact. Zero dependencies (pure Python stdlib). You choose when to enable it.

Workflow M: Meta-Optimize 🧬 (ARIS optimizes itself) Copy Section

"Analyze my usage patterns and improve your own skills."

Unlike Workflows 1–4 which optimize research artifacts (papers, code, experiments), Workflow M optimizes the harness itself — the SKILL.md instructions, default parameters, and convergence rules that govern how ARIS operates. Inspired by Meta-Harness (Lee et al., 2026).

Show Workflow M one-time setup and usage commands — Claude Code hook install, /meta-optimize variants (project / per-skill / --global / apply)

Setup (one-time, in normal terminal):

mkdir -p .claude .aris/meta tools/meta_opt
cp Auto-claude-code-research-in-sleep/templates/claude-hooks/meta_logging.json .claude/settings.json
cp Auto-claude-code-research-in-sleep/tools/meta_opt/*.sh tools/meta_opt/
chmod +x tools/meta_opt/*.sh
claude   # hooks active immediately

Usage (after 5+ workflow runs):

> /meta-optimize                        # analyze current project
> /meta-optimize "auto-review-loop"     # focus on one skill
> /meta-optimize --global               # analyze trends across ALL projects
> /meta-optimize apply 1                # apply recommended change #1

How it works:

1. 📊 Passive logging — Claude Code hooks silently record every skill invocation, tool call, failure, parameter override, and user prompt. Events are written to both project-level (.aris/meta/events.jsonl) and global (~/.aris/meta/events.jsonl, with a "project" tag) logs. Zero user effort.
2. 🔍 Pattern analysis — /meta-optimize reads the log and identifies:
   • Parameters users override most often (bad defaults)
   • Tools that fail repeatedly in specific skills (missing error handling)
   • Review score plateaus (convergence rules too loose/tight)
   • Manual corrections users make (skill gaps)
3. 🩹 Patch proposal — generates minimal diffs to target SKILL.md files with data-backed justifications
4. 🔬 Reviewer gate — GPT-6-Astra xhigh reviews each patch: does the evidence support it? could it hurt other users?
5. ✅ User approval — only applied with explicit user consent. All changes are logged and reversible.

Show Workflow M diagram and "what gets optimized" component table — event logs → SKILL.md patches → GPT-6-Astra review → user approval; prompts / defaults / convergence / error handling

┌─────────────────────────────────────────────────────────────────┐
│                  Workflow M: Meta-Optimize                        │
│                                                                  │
│   Normal ARIS usage (W1-W4)                                      │
│         │ (hooks log events passively)                           │
│         ▼                                                        │
│   .aris/meta/events.jsonl                                        │
│         │                                                        │
│         ▼                                                        │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐               │
│   │ Analyze  │────▶│ Propose  │────▶│ GPT-6-Astra  │               │
│   │ patterns │     │ SKILL.md │     │ reviews  │               │
│   │          │     │ patches  │     │ patch    │               │
│   └──────────┘     └──────────┘     └──────────┘               │
│                                          │                       │
│                                          ▼                       │
│                                    User approves?                 │
│                                     Yes → Apply                  │
│                                     No  → Skip                   │
└─────────────────────────────────────────────────────────────────┘

What gets optimized (harness components):

What does NOT get optimized: research artifacts (papers, code, experiments) — that's what W1–W4 do.

Skills involved: meta-optimize

💡 This is a maintenance workflow, not part of the W1→W1.5→W2→W3→W4 research pipeline. Run it periodically, like git gc for your research harness.

⚡ Effort Levels Copy Section

Every skill takes — effort: lite | balanced | max | beast — scaling breadth/depth (papers · ideas · pilots · rounds · seeds · audit depth) from ~0.4× to ~5–8×; balanced is the default (zero change for existing users). What never changes at any level: Codex reasoning stays at its tier floor (regular xhigh; deep audits ultra), DBLP/CrossRef citations on, reviewer independence on, experiment integrity on. 📖 Full spec + per-skill counts → effort-contract.md

Assurance Gate (effort: max | beast) Copy Section

A second axis, orthogonal to effort: assurance decides whether mandatory audits are load-bearing. lite/balanced ⇒ draft (audits non-blocking — current behavior, zero change); max/beast ⇒ submission (paper-writing Phase 6 force-runs /proof-checker + /paper-claim-audit + /citation-audit in fresh threads and refuses the Final Report if tools/verify_paper_audits.sh exits non-zero). Escape hatch: — effort: beast, assurance: draft. 📖 Full spec → assurance-contract.md

🧿 Optional: GPT-5.5 Pro via Oracle Copy Section

Add — reviewer: oracle-pro to any reviewer-aware skill (/proof-checker, /research-review, /experiment-audit, /rebuttal, …) to route review through GPT-5.5 Pro — strongest reasoning for deep proof / code / experiment-design critique. Default stays Codex xhigh; Oracle not installed ⇒ graceful fallback + warning (zero impact). 📖 Setup + per-skill examples → reviewer-routing.md

9. ⚙️ Setup Copy Chapter

📖 New to ARIS? SETUP_GUIDE.md (中文) gives a prescriptive 6-step walkthrough for macOS local + remote Linux GPU server with Claude Code + Codex MCP — the recommended path. The section below is a quick reference; deeper GPU / customization / model-combo setup lives in the linked docs.

10.1 Prerequisites Copy Section

1. Claude Code installed
2. (For review skills) Codex CLI installed and configured as MCP server:
   bash Copy

   npm install @openai/codex
   claude mcp add codex -s user -- python3 "$HOME/aris_repo/mcp-servers/codex-exec/server.py"

   The path is mcp-servers/codex-exec/server.py inside your ARIS clone — codex-cli 0.154 removed codex mcp-server, this bridge stands in for it.
3. (For Workflow 3: paper writing) LaTeX environment with latexmk and pdfinfo:
   bash Copy

   # macOS
   brew install --cask mactex    # or: brew install basictex
   brew install poppler          # provides pdfinfo
   
   # Ubuntu/Debian
   sudo apt install texlive-full latexmk poppler-utils
   
   # Verify
   latexmk --version && pdfinfo -v

   Windows (PowerShell): Install a TeX distribution using the MiKTeX Basic Installer or TeX Live for Windows. Install Poppler for Windows separately, add the directory containing pdfinfo.exe to PATH, and open a new PowerShell window. Then verify:

   powershell Copy

   latexmk --version
   pdfinfo -v

   If either command is not found, refresh the TeX distribution's package/path settings and check that the Poppler directory containing pdfinfo.exe is on PATH.
   If you only need Workflow 1 & 2 (idea discovery + auto review), LaTeX is not required.

10.2 Install Skills Copy Section

💡 Recommended: project-local flat symlink install (since 2026-04-20). Each ARIS skill is symlinked individually into .claude/skills/<skill-name>, so Claude Code's slash-command discovery picks them up. A manifest at .aris/installed-skills.txt tracks what ARIS installed — uninstall and reconcile only ever touch managed entries, never your own skills.

🤖 Codex mirror route: keep Claude on install_aris.sh / smart_update.sh. For Codex-native project installs, use install_aris_codex.sh; for copied Codex installs, use smart_update_codex.sh.

🧩 Plugin route (Claude Code only): claude plugin marketplace add wanshuiyin/Auto-claude-code-research-in-sleep, then claude plugin install aris@aris, then /aris:setup once — it registers the Codex reviewer bridge that ships inside the plugin and points helper resolution at it; restart Claude Code afterwards. All skills arrive at once (no clone, no symlinks, no group selection) and are typed with the prefix: /aris:idea-discovery, /aris:paper-writing. Updates: claude plugin update aris@aris. Codex CLI reads the same repo as a plugin and gets the Codex-native mirror instead: codex plugin marketplace add wanshuiyin/Auto-claude-code-research-in-sleep, then codex plugin add aris@aris, then point helper resolution at it once — printf '%s\n' ~/.codex/plugins/cache/aris/aris/local > ~/.aris/repo (the path codex plugin list shows). Use the installers above for selective groups or the .aris/installed-skills.txt manifest.

/* Detailed source-code truncated for AI context efficiency. */

Why "git pull" alone isn't enough for new/removed skills: the flat layout uses one symlink per skill, so upstream additions/deletions don't propagate until the installer is re-run. The trade-off bought us Claude Code's automatic slash-command discovery (which only scans one directory level deep).

Migrating from the old nested install (pre-2026-04-20)

If you previously installed via install_aris.sh (which created .claude/skills/aris/ as a single nested symlink) or via smart_update.sh --target-subdir .claude/skills/aris, your slash commands probably weren't being auto-discovered by Claude Code. Migrate to the flat layout:

# Symlink-style legacy install:
bash ~/aris_repo/tools/install_aris.sh ~/your-project --from-old

# Copy-style legacy install (with possible local edits — chose strategy explicitly):
bash ~/aris_repo/tools/install_aris.sh ~/your-project --from-old --migrate-copy keep-user
#   → keeps your nested .claude/skills/aris/ copy intact alongside the new flat install
bash ~/aris_repo/tools/install_aris.sh ~/your-project --from-old --migrate-copy prefer-upstream
#   → archives nested copy to .aris/legacy-copy-backup-<timestamp>/, then flattens

Alternative installs (advanced)

Project-local copy (no symlinks, useful for per-project skill edits):

mkdir -p ~/your-project/.claude/skills
bash ~/aris_repo/tools/smart_update.sh --project ~/your-project --apply
# Default --target-subdir is .claude/skills (flat), which is what Claude Code expects.
# (The old --target-subdir .claude/skills/aris is now deprecated — see migration block above.)

Global install (one copy in your home dir, available to every project):

mkdir -p ~/.claude/skills
cp -r ~/aris_repo/skills/* ~/.claude/skills/
# Update with: bash tools/smart_update.sh --apply

Global install increases the risk of skill name collisions with other globally-installed packs. Use only if you don't mix ARIS with Superpowers / OpenHands / etc. — otherwise prefer the project-local install above.

💡 New Claude Code versions may not auto-create ~/.claude/skills/. If using global install, create it first: mkdir -p ~/.claude/skills/. The symlink installer handles directory creation automatically.

Optional: Codex Plugin for Code Review

codex-plugin-cc provides additional Codex capabilities that ARIS auto-detects when installed:

# In Claude Code:
/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup

Where ARIS uses the plugin:

All plugin features are optional — if not installed, ARIS falls back to Claude's own diagnosis. The plugin just adds a second pair of eyes.

Note: ARIS's core cross-model review (paper scoring, idea evaluation, rebuttal stress test) still uses Codex MCP, which allows custom prompts. The plugin cannot replace this.

10.3 Update Skills Copy Section

cd Auto-claude-code-research-in-sleep
git pull

# 🧠 Smart update (recommended) — analyzes what's safe to update
bash tools/smart_update.sh          # dry-run: shows what would change
bash tools/smart_update.sh --apply  # apply: updates safe ones; NEW upstream skills prompt
                                     # one-by-one on a TTY, or use --add-new / --skip-new

# Manual options (if you prefer):
# cp -r skills/* ~/.claude/skills/       # Option A: overwrite all
# cp -rn skills/* ~/.claude/skills/      # Option B: only add new, keep yours
# cp -r skills/experiment-bridge ~/.claude/skills/  # Option C: specific skill

💡 Smart update compares your local skills with upstream, detects personal customizations (server paths, API keys, etc.), and only updates skills that are safe to replace. Skills with your personal info are flagged for manual review.

10.4 Usage Copy Section

# Workflow 1: Idea Discovery
> /idea-discovery "your research direction"          # full pipeline
> /research-lit "topic"                              # just literature survey (all sources)
> /research-lit "topic" — sources: zotero, web        # mix and match sources
> /research-lit "topic" — sources: deepxiv            # DeepXiv-only progressive retrieval
> /research-lit "topic" — sources: exa                # Exa AI-powered web search with content extraction
> /research-lit "topic" — arxiv download: true         # also download top arXiv PDFs
> /arxiv "discrete diffusion" — download               # standalone arXiv search + download
> /idea-creator "topic"                              # just brainstorm

# Workflow 2: Auto Research Loop
> /auto-review-loop "your paper topic"               # review → fix → repeat
> /research-review "your paper"                      # single deep review

# Workflow 3: Paper Writing
> /paper-writing "NARRATIVE_REPORT.md"               # full pipeline
> /paper-plan "NARRATIVE_REPORT.md"                  # just outline
> /paper-compile "paper/"                            # just compile

# Full Pipeline
> /research-pipeline "your research direction"       # Workflow 1 → 2 → 3 end-to-end

# Supporting Skills
> /run-experiment train.py --lr 1e-4 --epochs 100
> /analyze-results figures/*.json
> /monitor-experiment server5

10.5 🌙 Auto-Allow for Overnight Runs (Optional) Copy Section

Skip permission prompts on overnight runs — add a snippet to .claude/settings.local.json

To run the auto-review loop without clicking permission prompts, add to .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "mcp__codex__codex",
      "mcp__codex__codex-reply",
      "Write",
      "Edit",
      "Skill(auto-review-loop)"
    ]
  }
}

🖥️ GPU for Auto-Experiments (Optional) Copy Section

When the reviewer says "run an ablation", Claude Code writes the script and runs it on your GPU — you just declare your server in CLAUDE.md. Three modes (Remote SSH · Local GPU · Vast.ai on-demand): config snippets + setup → docs/GPU_SETUP.md (Vast.ai deep-dive → Vast.ai guide). No GPU? Review/rewrite skills still work; experiment fixes are flagged for manual follow-up.

🔌 Integrations (Optional) Copy Section

Plug your library / vault / notifications into ARIS — each auto-skips silently if unconfigured:

• Zotero — collections + annotations + BibTeX in /research-lit (before web search).
• Obsidian + arXiv — search your vault notes; arXiv is built-in, no setup.
• Feishu / Lark — mobile push + interactive approve/reject for overnight runs.

10. 🎛️ Customization Copy Chapter

Skills are plain Markdown — fork and tune them. Per-skill environment variables (GPU target, code review, reviewer routing, human checkpoints, paper-writing knobs) and parameter pass-through live in docs/CUSTOMIZATION.md.

Reviewer quota tight? The defaults are chosen for quality and stay as they are: skills start from natural language, and every review goes to the cross-model reviewer at its full tier. If a casual sentence starting a skill costs you quota, these are yours to opt into:

Start ARIS skills or external reviewers only when I name an ARIS skill or explicitly
request an ARIS workflow. That request includes its child skills and reviewers;
continue under AUTO_PROCEED without asking for confirmation.

11. 🔀 Alternative Model Combinations Copy Chapter

No Claude / OpenAI API? Swap in other providers — same cross-model architecture. ARIS ships 10 alternative routes (Z.ai GLM, Alibaba Kimi/Qwen/MiniMax, free DeepSeek-V3.1 via ModelScope, OpenRouter as a pin-one-of-many reviewer backend, Codex-as-executor with Claude/Gemini reviewers, Google Antigravity). Full routing table + per-route setup in docs/MODEL_COMBINATIONS.md.

12. 💬 Community Copy Chapter

Domain-specific skills welcome! The core skills cover general research workflows, but every field has its own tools and patterns. We welcome PRs that add new skills for your domain — EDA, bioinformatics, robotics, HPC, or anything else. Just add a skills/your-skill/SKILL.md and open a PR. See dse-loop for an example.

Join the WeChat group for discussion on Claude Code + AI-driven research workflows:

13. 📖 Citation Copy Chapter

If you use ARIS in your research, please cite:

@article{yang2026aris,
  title={ARIS: Autonomous Research via Adversarial Multi-Agent Collaboration},
  author={Yang, Ruofeng and Li, Yongcan and Li, Shuai},
  journal={arXiv preprint arXiv:2605.03042},
  year={2026}
}

14. ⭐ Star History Copy Chapter

15. 🙏 Acknowledgements Copy Chapter

Inspired by — 🧪 AI Scientist (Sakana) · 📖 AutoResearch (Karpathy) · 🔭 FARS (Analemma) · 🎨 PaperBanana (PKU).

Core infra — Claude Code (execution backbone) · Codex CLI (cross-model review via MCP).

Integrations — Zotero (guide): zotero-mcp, Zotero. Obsidian (guide): mcpvault, obsidian-skills (by Obsidian CEO Steph Ango). Feishu/Lark (guide): feishu-claude-code, clawdbot-feishu, cc-connect, lark-openapi-mcp.

Paper-writing inspiration — claude-scholar · Research-Paper-Writing-Skills · baoyu-skills. Community — awesome-agent-skills (featured).

Platform adaptation — 🤖 @Falling-Flower (Codex CLI adaptation via spawn_agent) · 🔧 @No-518 (Codex skill maintenance) · 🖱️ @YecanLee (Cursor guide + local GPU docs) · 🏆 @DefanXue & @Monglitay (first ARIS community paper, CS conference 8/10).

Architecture & vision — 💡 @JingxuanKang: beyond code (training-check, result-to-claim, ablation-planner, watchdog, templates, session recovery), deeply shaped ARIS through discussions on compact mode, workflow state management, and the vision of autonomous research — many of today's core features (structured project files, context-aware session recovery) grew out of these conversations.

16. License Copy Chapter

MIT

Overview (`aris-monitor/README.md`) Copy Section

ARIS-Monitor

A tiny, native, always-on-top floating macOS widget that shows, at a glance,
which of your running Claude Code sessions need you — primarily
"needs approval / pending permission", plus a simple working / done status.

No browser. No Chrome extension. No Electron. Pure Python stdlib Tkinter —
zero pip install.

🔒 READ-ONLY monitoring + ONE opt-in focus action Copy Chapter

ARIS-Monitor builds its display by only reading files under ~/.claude —
monitoring is strictly read-only (liveness is inferred from file freshness; it
does not even call os.kill(pid, 0)). The one non-read action is
Focus: clicking a session row raises that session's terminal window. That
path — and only that path — runs ps (to read the pid's tty) and the
raise-only focus-tty.sh (osascript activate / select). Focus is always
user-initiated and never kills, signals, writes, or modifies any session or
process — it can only bring a window to the front. No network calls, ever.

Run Copy Chapter

./run.sh            # start the floating widget (top-right, draggable)
# or directly:
python3 widget.py

A small borderless panel appears top-right, floating above your windows. Drag
it by the dark header. Quit with the ×, or press q / Esc.

Click any session row to jump to (focus) its terminal tab/window — the
triage loop is: panel goes red → click the row → you're at that terminal to
approve. Focus is raise-only (Terminal.app / iTerm2 / tmux); it never touches the
session itself.

Other modes:

./run.sh --check    # read-only smoke test (prints the classified list, no GUI)
./run.sh --ticker   # headless terminal ticker (same scanner, same 2s loop)
python3 scanner.py  # same as --check

What it watches (READ-ONLY) Copy Chapter

The authoritative needs-approval signal is the live session registry, not a
transcript guess:

~/.claude/sessions/<pid>.json     ->  status == "waiting"   (the core signal)
~/.claude/projects/<slug>/<id>.jsonl  (read-only tail, only to refine working/done)

The Claude Code app itself sets status == "waiting" (with an optional
waitingFor string like Bash(npm test) needs approval) while a permission
prompt is on screen, and clears it the instant you answer. So:

• needs-approval is detected with no transcript parsing — straight from the
  live JSON, which is why it is authoritative; and
• it is inherently transient — the widget polls every ~2 s to catch it.
  On a quiescent machine you will only ever see working / done, never
  waiting. That is expected, not a bug.

Sort order: NEEDS YOU → stalled → done → working → stale.

The panel shows the top 5 rows by that order; everything beyond folds behind
a clickable ▸ N more (click to show). needs-approval rows are never folded —
the cut stretches to include every red session. (Tune the cap with MAX_VISIBLE.)

Why not the "unmatched trailing tool call" heuristic? Copy Section

Because a transcript that stops at a tool_use block while the session is
not status=="waiting" only means the run stalled, not that it is
waiting on your approval. Keying needs-approval off that would false-positive on
every mid-tool pause. The live status=="waiting" flag is the only
authoritative pending-permission signal, so that is what the red bucket uses.

Codex is out of scope (for needs-approval) Copy Section

Codex has no on-disk live-status file equivalent to ~/.claude/sessions,
and its approval prompts are not written to the rollout JSONL. So ARIS-Monitor
does not scan Codex at all and will never claim Codex needs approval. The
pending-permission feature is Claude-Code-only by design.

Empty / all-clear state Copy Chapter

With zero active sessions the panel stays visible and shows a calm
ARIS-Monitor — all clear ○ 0 header (green, never red) with a dim
no active Claude sessions line. Zero sessions = "nothing needs you", which is
visually distinct from "needs approval".

Files Copy Chapter

• widget.py — the Tkinter floating panel (UI; imports scanner.scan() for the
  read-only display and focus.focus() for the click-to-raise action).
• scanner.py — the strictly read-only classifier. Public: scan(),
  summary(). python3 scanner.py is a GUI-less smoke test.
• focus.py — the ONE non-read action: raise a session's terminal (ps for
  the tty + focus-tty.sh). Strictly raise-only; never kills/writes/signals.
• focus-tty.sh — bundled raise-only shim (Terminal.app / iTerm2 / tmux pane).
  Always the bundled script (no ~/.claude/focus-tty.sh override is executed),
  so the focus action's command surface stays provably bounded to this reviewed
  shim — osascript activate/select + read-only tmux list-* discovery, never
  kill/send-keys/session mutation.
• ticker.py — headless terminal fallback (same scanner, same 2 s loop), used
  automatically when Tkinter is unavailable.
• run.sh — launcher: verifies Tk, starts the widget, falls back to the
  ticker. Supports --check and --ticker.

Dependencies Copy Chapter

Python 3 standard library only: tkinter, json, os, time, glob,
dataclasses. No pip. No venv. No brew (common case). No browser.

Tkinter ships with macOS's Xcode Command Line Tools /usr/bin/python3 and with
most conda / Homebrew pythons (Tk 8.6 verified present here). If
python3 -c "import tkinter" fails on a minimal interpreter, install Tk for it
(e.g. brew install python-tk) — or just use ./run.sh --ticker, which needs
no Tk.

Note on run.sh and venvs: ARIS-Monitor has no third-party
dependencies, so there is nothing to install and run.sh deliberately does
not create a venv — a fresh venv often lacks the compiled _tkinter
module the base interpreter has, which would break the GUI. The launcher
simply verifies Tk against your existing python3 and runs.

Tunables Copy Chapter

Top-of-file constants in scanner.py / widget.py:

• REFRESH_MS (widget) / REFRESH_S (ticker) — poll cadence (default 2 s).
• MAX_VISIBLE (widget) — rows shown before the rest fold behind ▸ N more (default 5; needs-approval rows are never folded).
• LIVE_WINDOW — seconds before a session is styled dim/stale and sorted to the bottom (1800 = 30 min).
• IDLE_THRESHOLD — busy-but-fresh cutoff for "working" (300).
• TRANSCRIPT_TAIL_BYTES — read-only tail size (256 KiB).

macOS caveats (the documented price of zero-install) Copy Chapter

overrideredirect floating windows are absent from Mission Control, are not
Cmd-Tab-able, and can sit below a true-fullscreen app's Space; the look is
utilitarian (no native rounded corners / vibrancy). Acceptable for an MVP
triage glance. The same scanner.py can later back a PyObjC NSPanel for 10/10
floating polish with zero detection-code changes — at the cost of one
pip install pyobjc-framework-Cocoa.

Overview (`templates/README.md`) Copy Section

Templates

Ready-to-use templates for each ARIS workflow. Copy, fill in your content, and run the corresponding skill.

Workflow Input Templates Copy Section

Chinese Templates (中文模板) Copy Section

Patent Templates (`/patent-pipeline`) Copy Section

Compact Mode Templates (`— compact: true`) Copy Section

Usage Copy Chapter

Research Pipeline Copy Section

cp templates/EXPERIMENT_PLAN_TEMPLATE.md refine-logs/EXPERIMENT_PLAN.md
# Edit with your content, then:
/experiment-bridge

Patent Pipeline Copy Section

cp templates/INVENTION_BRIEF_TEMPLATE.md patent/INVENTION_BRIEF.md
# Edit with your invention details, then:
/patent-pipeline "patent/INVENTION_BRIEF.md -- CN"

Overview (`docs/tutorials/README.md`) Copy Section

ARIS Tutorials

Long-form interview-prep cheat sheets, written in Markdown and rendered to single-file HTML via the /render-html skill (academic-newspaper template, sticky TOC, MathJax + highlight.js, cross-model codex review gate).

📖 Curated collection: github.com/wanshuiyin/ARIS-in-AI-Offer — interview-prep cheat sheets organized into 6 categories with bilingual README.

🧠 General / Foundations Copy Section

🎯 Post-Training & Reasoning Copy Section

🏛️ LLM Architecture & Systems Copy Section

🌊 Generative Models — Theory & Tokenizers Copy Section

🎨 Generation Systems Copy Section

👁️ Multimodal Copy Section

✅ 23 tutorials across 6 categories; each also available in English alongside the Chinese version (e.g. attention_tutorial_en.md / _en.html). Full curated collection: ARIS-in-AI-Offer.

How they were produced Copy Chapter

The two pilots were drafted by hand and rendered via /render-html. Subsequent tutorials use the dedicated workflow skill:

/interview-cheatsheet "<TOPIC>"            # default: 600-line balanced effort
/interview-cheatsheet "<TOPIC>" — effort: max    # ~1000 lines + deeper proofs

/interview-cheatsheet (skills/interview-cheatsheet/SKILL.md) is an ARIS skill that:

1. Plans a 12-14 section structure (TL;DR · intuition · formula+derivation · from-scratch PyTorch · variants · 25 高频面试题 L1/L2/L3)
2. Drafts the MD following the canonical style of the two pilot tutorials (heading conventions, table-pipe escapes, callout-list separation rules — all bugs caught during the pilot reviews are now encoded into the style guide)
3. Cross-model codex gpt-5.5 xhigh review on math / code / interview-answer / citation correctness + personal-info redaction (fresh thread, never codex-reply)
4. Fix-and-loop — trajectory-based (no hard cap; stop if same issue recurs or ~6 rounds without convergence)
5. Renders via /render-html (which itself runs a 13-check codex review on the rendered output)
6. Writes a combined audit trail to *.review.json
7. Stops — never auto-commits. The user reviews and pushes manually.

See skills/interview-cheatsheet/SKILL.md for the full skill protocol and skills/render-html/SKILL.md for the renderer.

Overview (`mcp-servers/antigravity-exec/README.md`) Copy Section

Antigravity CLI → MCP

使用已有 agy 登录，把 Gemini 3.8 Flash 接为独立 MCP。沿用同仓库 codex-exec / grok-exec 的 NDJSON、进度、取消和会话保存设计，Python 3.9+，无需第三方库。

默认模型 gemini-3.8-flash-high，effort high。提供 antigravity 和 antigravity-reply，作为独立工具使用，不修改 ARIS skills 的 reviewer 路由。

现有 gemini-review 已有 API、Gemini CLI 和 agy 后端，提供 review* 工具供正式评审流程使用。本桥接提供显式 model/effort 与 CLI 原生 conversation 续接；工具名和会话契约不同。— reviewer: agy 和 Codex 的 Gemini overlay 仍走现有 gemini-review，不会因安装本桥接而切换。

安装 Copy Chapter

1. 安装 Antigravity CLI，运行 agy 登录；agy models 应包含目标模型。
2. 把同目录 aris-antigravity-review.md 复制到 ~/.gemini/config/agents/。这是专供 MCP 选择的审阅 agent，不改变交互会话的默认 agent。
3. 注册 MCP，绝对路径替换为自己的安装位置：

codex mcp add antigravity --env AGY_BIN=/absolute/path/to/agy -- python3 /absolute/path/to/aris/mcp-servers/antigravity-exec/server.py

在 Codex config.toml 的 [mcp_servers.antigravity] 中设置 tool_timeout_sec = 3660。若本机网络需要代理，在该服务的 env 中显式配置实际可达的 http_proxy / https_proxy；不要依赖 GUI 启动时继承终端环境。

Claude Code 可另行注册：

claude mcp add antigravity -s user -- python3 /absolute/path/to/aris/mcp-servers/antigravity-exec/server.py

重启对应客户端后使用新工具。常驻 MCP 与 shell 内启动的独立探测具有不同的宿主权限；受限 shell 不能写 CLI 状态目录或连接代理，不代表常驻服务也失败，应使用宿主的正常审批流程处理。

调用 Copy Chapter

首轮：

{"prompt":"请读取指定文件，回答这个问题。","cwd":"/absolute/path/to/project","model":"gemini-3.8-flash-high","effort":"high"}

续接 antigravity-reply：

{"threadId":"首轮返回的 UUID","prompt":"请接着解释第二点。"}

续接只接受这两个字段，沿用首轮 model、effort、cwd 和审阅 agent。桥接重启后仍可恢复自己创建的会话；不用 --continue，避免串到其他交互会话。threadId 同时放在文本和 structuredContent 中。

返回的 model 来自 CLI 的 init 事件，selectedModelLabel 来自本轮 CLI 解析模型的日志；effort 从该实际选择的变体标签解析，注明 effortSource=cli_selected_model_variant。缺少记录时返回 null，不把请求值冒充实测值；这也不是独立的服务端型号证明。不支持的模型或 effort 交由 CLI 明确报错，不自动降级。

权限与执行 Copy Chapter

• 选择专用审阅 agent，其提示和工具声明限定文件读取与搜索；保留 CLI 原生权限检查，启用 --sandbox，不传跳过权限参数。CLI 1.2.17 的 init 仍列出完整工具目录，因此这里不宣称已验证所有写入被硬隔离。使用者应按现有 CLI 权限管理敏感工作区。
• 用一条 NDJSON stdin 传提示，避免长提示进入命令行；关闭 stdin 后 CLI 完成本轮并退出。临时输入与本轮日志留在私有目录，调用结束清除；CLI 自己的会话仍按原生方式保存。
• 接受完整 SUCCESS、非空回答和进程退出码0；ERROR、WAITING、取消、非零退出或缺失终态都返回 isError。
• 等待模型时响应 ping、进度与取消；超时或宿主断开会回收本次 CLI 进程组。桥接不自动重试模型调用。
• 每个服务进程顺序执行。CLI 的 num_turns 是累计用户回合，不是 Grok/Claude 的工具轮次上限；本桥接没有编造同名限制参数。

探测用短超时，例如 AGY_EXEC_TIMEOUT_SEC=90；正常审阅保留较长超时。

验证 Copy Chapter

2026-10-05，macOS、Antigravity CLI 1.2.17：直接 headless 首轮与续接成功；真实 MCP 用 view_file 读取测试文件，重启桥接后用同一会话正确复述随机字符串，两轮约40秒，CLI 两轮均选择 Gemini 3.8 Flash (High)。该验证覆盖调用与续接，不代表复杂审阅质量或并发额度测试。

离线协议测试：

python3 -m unittest discover -s tests -p 'test_antigravity_exec_bridge.py' -v

8项用例覆盖协议、长输入、跨进程续接、错误终态、元数据缺失、取消和超时。Ruff、格式与 ty 检查通过。

接口依据：Google headless 文档、自定义 agent、Codex MCP 配置。

Overview (`mcp-servers/claude-review/README.md`) Copy Section

Claude Review MCP

Bridge Codex-first ARIS workflows to the local Claude Code CLI.

What it does Copy Chapter

• Keeps Codex as the executor
• Uses Claude Code CLI as the external reviewer
• Exposes synchronous MCP tools:
  • review
  • review_reply
• Exposes asynchronous MCP tools for long reviewer prompts:
  • review_start
  • review_reply_start
  • review_status

The synchronous tools return a JSON string containing threadId and response.
The asynchronous start tools return a JSON string containing jobId and status, and review_status later returns the final threadId and response.

Claude Code is the CLI transport. The reviewer uses its configured provider,
which may be Anthropic or an API-compatible provider such as DeepSeek. Do not
classify the reviewer's model family from the bridge name alone.

Install into Codex Copy Chapter

mkdir -p ~/.codex/mcp-servers/claude-review
cp mcp-servers/claude-review/server.py ~/.codex/mcp-servers/claude-review/server.py
codex mcp add claude-review -- python3 ~/.codex/mcp-servers/claude-review/server.py

Alternatively, register the absolute path to server.py in an existing ARIS
checkout so repository updates also update the bridge. If Codex cannot find
claude on PATH, pass --env CLAUDE_BIN=/absolute/path/to/claude before --.
The bridge uses Claude Code's existing provider settings and authentication;
there is no need to copy credentials into the MCP configuration. Leaving
CLAUDE_REVIEW_MODEL unset follows the CLI's configured model.

Reopen the Codex session after registering a new server and check its MCP tool
list. An existing interactive Claude Code window can remain open: this bridge
starts a separate non-interactive session and resumes only the supplied
threadId, never the most recent interactive conversation.

If your Claude Code login depends on a shell function such as claude-aws, use the wrapper instead:

mkdir -p ~/.codex/mcp-servers/claude-review
cp mcp-servers/claude-review/server.py ~/.codex/mcp-servers/claude-review/server.py
cp mcp-servers/claude-review/run_with_claude_aws.sh ~/.codex/mcp-servers/claude-review/run_with_claude_aws.sh
chmod +x ~/.codex/mcp-servers/claude-review/run_with_claude_aws.sh
codex mcp add claude-review -- ~/.codex/mcp-servers/claude-review/run_with_claude_aws.sh

Environment Variables Copy Chapter

• CLAUDE_BIN: Claude CLI path, defaults to claude
• CLAUDE_REVIEW_MODEL: optional reviewer model override
• CLAUDE_REVIEW_SYSTEM: optional default system prompt
• CLAUDE_REVIEW_TOOLS: Claude tools override, defaults to empty string
• CLAUDE_REVIEW_TIMEOUT_SEC: subprocess timeout, defaults to 600
• CLAUDE_REVIEW_STATE_DIR: async job storage, defaults to ~/.codex/state/claude-review
• CLAUDE_REVIEW_DEBUG_LOG: local protocol/debug log path; logs include prompts and responses

Notes Copy Chapter

• The bridge runs Claude in non-interactive -p mode.
• It passes --strict-mcp-config with an empty MCP configuration, so the
  reviewer does not inherit MCP servers such as Codex and delegate back to the
  executor. Provider settings remain available. CLI tools and plan permissions
  are not an operating-system sandbox.
• By default the reviewer gets no tools. This matches the original ARIS pattern where the external reviewer only sees the prompt context prepared by the executor.
• A prompt that hands the reviewer artifact paths instead of pasted context must therefore opt in per call, e.g. "tools": "Read,Grep,Glob". Without it the reviewer is asked to read files it has no tool to open, and it answers from your framing alone — exactly what artifact-grounded review is meant to avoid. The skills-codex-claude-review overlay passes this on its artifact-grounded review blocks; the server default stays tool-free, so prompt-only reviews are unchanged.
• The opt-in is per call, not per thread: every call re-sends --tools, so a review_reply / review_reply_start continuing an artifact-grounded thread has to repeat it.
• All four review tools accept cwd. Set it to the project directory when
  passing artifact paths, and repeat the same value on replies. Without it,
  the CLI inherits the MCP server's directory; threadId does not select a
  working directory. Async jobs save the resolved absolute directory before
  launching their worker.
• Keep the opt-in read-only. The bridge already runs Claude with --permission-mode plan, and a reviewer has no reason to hold Bash, Edit, or Write.
• threadId is the native Claude session id and can be passed directly to review_reply.
• jobId is a bridge-local background task id stored on disk under ~/.codex/state/claude-review/jobs/ by default, so status can be resumed across MCP server restarts.

Example file review:

{
  "name": "review",
  "arguments": {
    "prompt": "Read draft.md and identify unsupported claims.",
    "cwd": "/absolute/path/to/project",
    "tools": "Read,Grep,Glob"
  }
}

Results include requestedModel (explicit argument or bridge default, otherwise
null) separately from model. The latter comes from the CLI result's model
field or a single modelUsage entry, with modelSource identifying the source.
reportedModels lists the usage entries when present. If the CLI does not
identify one model unambiguously, model is null; the requested alias is never
substituted as evidence. These are CLI reports, not independent server identity
verification. No context-window size or reasoning effort is inferred from the
model name.

Empty reviews, nonterminal output, CLI errors and explicit unfinished stop
reasons are returned as errors, with no automatic retry. Existing synchronous
calls block the protocol reader until the CLI returns or times out; MCP
cancellation is not a process-tree cancellation guarantee. Use async jobs for
long reviews and poll their status after reconnecting.

When to use sync vs async Copy Chapter

• Use review / review_reply for short prompts that comfortably finish within the host MCP tool timeout.
• Use review_start / review_reply_start + review_status for long paper or project reviews. This avoids the observed Codex -> tools/call timeout around 120 seconds.

Async flow Copy Chapter

Start a long review:

{
  "name": "review_start",
  "arguments": {
    "prompt": "Review this paper draft..."
  }
}

Example response:

{
  "jobId": "5d8d0a9c5a2f4f42ae44f6f0c2d73f6f",
  "status": "queued",
  "done": false
}

Poll later:

{
  "name": "review_status",
  "arguments": {
    "jobId": "5d8d0a9c5a2f4f42ae44f6f0c2d73f6f",
    "waitSeconds": 20
  }
}

When complete, review_status returns the same reviewer payload fields as the synchronous tools, including threadId, response, model, and stop_reason.

Overview (`mcp-servers/codex-exec/README.md`) Copy Section

codex-exec — the `codex` MCP server, over `codex exec`

codex-cli 0.154.0 removed the codex mcp-server entry point that ARIS
registered as the codex MCP server. This bridge speaks the same contract —
tools codex and codex-reply, results {threadId, content} — and runs each
call as a codex exec subprocess. Nothing in the skills changes.

Register Copy Chapter

cd ~/aris_repo && git pull                  # existing install: older clones do not have this directory
claude mcp remove codex -s user             # only if the old `codex mcp-server` registration exists
claude mcp add codex -s user -- python3 "$(pwd)/mcp-servers/codex-exec/server.py"

Use the absolute path of your ARIS clone ($(pwd) from inside it). Restart
Claude Code; claude mcp list should show codex … ✓ Connected. Verified on
codex-cli 0.153.4 and 0.154.0; needs a version with codex exec resume, so there
is no reason to keep the old registration on 0.153 either. Skills need no change.

Installed by copying skills/ without keeping a clone? Clone the repo anywhere
and point at its server.py; the file is self-contained.

Other MCP hosts (Cursor, Trae, Antigravity, Copilot CLI) use the same key with
"command": "python3", "args": ["/absolute/path/to/aris_repo/mcp-servers/codex-exec/server.py"].

Requirements: codex on PATH and logged in; Python 3.9+ (macOS system python is fine); no packages.

What a call becomes Copy Chapter

Per-thread settings live in ~/.codex/state/codex-exec/threads/.json, one file each.

A failed turn (unknown model, auth, API error) comes back as isError: true
with codex's own error text, so the capability fallback in
skills/shared-references/reviewer-routing.md keys on the same wording as before.

While a review runs the bridge streams codex/event notifications and, when the
host passes a progressToken, a notifications/progress heartbeat every 15 s
(CODEX_EXEC_PROGRESS_INTERVAL_SEC), answers ping, and honours
notifications/cancelled. Notifications cannot override a host's hard tool
timeout — deep-audit reviews at ultra can run 30+ minutes.

Not offered, because codex exec cannot honour them: approval-policy,
base-instructions, developer-instructions, compact-prompt. No ARIS skill
passed them.

Debugging: CODEX_EXEC_DEBUG_LOG=/path/to/log records every request and the
exact codex exec command line; CODEX_BIN points at a specific codex binary.

Overview (`mcp-servers/codex-image2/README.md`) Copy Section

codex-image2 MCP Bridge

Experimental bridge that lets Claude Code ask the local Codex desktop app
to generate an image through Codex's native app-server image-generation path.

This bridge is intentionally narrow:

• it accepts text prompts
• it waits for a native imageGeneration event from Codex
• it rejects runs that fall back to shell/Python-based image creation
• it copies the generated image only into cwd/figures/ai_generated/

Requirements Copy Chapter

• Codex desktop app installed and signed in
• codex CLI available on PATH
• codex debug app-server send-message-v2 "ping" works on your machine

Install for Claude Code Copy Chapter

mkdir -p ~/.claude/mcp-servers/codex-image2
cp mcp-servers/codex-image2/server.py ~/.claude/mcp-servers/codex-image2/server.py
chmod +x ~/.claude/mcp-servers/codex-image2/server.py

claude mcp add codex-image2 -s user -- python3 ~/.claude/mcp-servers/codex-image2/server.py

Exposed Tools Copy Chapter

• generate_start
• generate_status

The bridge is intentionally async-first. Call generate_start, then poll
generate_status.

Smoke Test Copy Chapter

After registering the server in Claude Code, ask Claude to call:

mcp__codex-image2__generate_start

with a prompt like:

Generate a clean blue circle on white background.

Then poll mcp__codex-image2__generate_status until done=true.

outputPath must stay under figures/ai_generated/ inside the provided cwd.
The server rejects writes outside that workspace root.

Current Limitations Copy Chapter

• The bridge uses the current Codex app-server path and is experimental
• It is optimized for one-shot generation rather than conversational thread replay
• Reference images are passed as path hints in the prompt; if Codex exposes local image viewing in that session, it may inspect them

Logging Copy Chapter

• Debug logging is opt-in via CODEX_IMAGE2_DEBUG_LOG=/path/to/debug.log
• Raw Codex stdout/stderr run logs are off by default; enable only when needed with CODEX_IMAGE2_SAVE_RUN_LOGS=1

Overview (`mcp-servers/gemini-review/README.md`) Copy Section

Gemini Review MCP

Bridge Codex-first ARIS workflows to Gemini, using the direct Gemini API by default.

What it does Copy Chapter

• Keeps Codex as the executor
• Uses Gemini as the external reviewer
• Exposes synchronous MCP tools:
  • review
  • review_reply
• Exposes asynchronous MCP tools for long reviewer prompts:
  • review_start
  • review_reply_start
  • review_status

The synchronous tools return a JSON string containing threadId and response.
The asynchronous start tools return a JSON string containing jobId and status, and review_status later returns the final threadId and response.
When using the direct API backend, the tools also accept optional imagePaths / image_paths so Gemini can review local PNG/JPG/WebP files, which is used by the poster visual-review overlay.

Install into Codex Copy Chapter

mkdir -p ~/.codex/mcp-servers/gemini-review
cp mcp-servers/gemini-review/server.py ~/.codex/mcp-servers/gemini-review/server.py
codex mcp add gemini-review --env GEMINI_REVIEW_BACKEND=api -- python3 ~/.codex/mcp-servers/gemini-review/server.py

Prerequisites Copy Chapter

Prepare the direct Gemini API path before use:

• Gemini API: set GEMINI_API_KEY or GOOGLE_API_KEY

Optional fallback only:

• Gemini CLI: install gemini and complete CLI login/auth if you explicitly want GEMINI_REVIEW_BACKEND=cli
• Antigravity CLI: install/authenticate agy if you explicitly want GEMINI_REVIEW_BACKEND=agy

The server also auto-loads ~/.gemini/.env if it exists, so a local file such as:

export GEMINI_API_KEY=...

is enough for API mode without exporting the variable in every shell.

Environment Variables Copy Chapter

• GEMINI_BIN: Gemini CLI path, defaults to gemini
• AGY_BIN: Antigravity CLI path, defaults to agy
• GEMINI_REVIEW_MODEL: optional reviewer model override used by API/Gemini CLI backends; agy model selection is controlled by Antigravity settings, so the bridge reports the actual model recovered from the current log/transcript and records any requested model as provenance only
• GEMINI_REVIEW_API_MODEL: API-only default when GEMINI_REVIEW_MODEL is unset, defaults to gemini-2.5-flash
• GEMINI_REVIEW_SYSTEM: optional default system prompt
• GEMINI_REVIEW_BACKEND: reviewer backend override, one of api, auto, cli, or agy; defaults to api
• GEMINI_REVIEW_TIMEOUT_SEC: HTTP / subprocess timeout, defaults to 600
• GEMINI_REVIEW_MAX_STATUS_WAIT_SECONDS: maximum blocking wait for review_status, defaults to 30
• GEMINI_REVIEW_AGY_PRINT_TIMEOUT: Antigravity --print-timeout value, defaults to ${GEMINI_REVIEW_TIMEOUT_SEC}s
• GEMINI_REVIEW_AGY_APP_DATA_DIR: Antigravity CLI app data directory, defaults to ~/.gemini/antigravity-cli
• GEMINI_REVIEW_AGY_ARTIFACT_MAX_CHARS: max characters read from an AGY-generated text artifact, defaults to 200000
• GEMINI_REVIEW_WORKSPACE_ROOT: workspace root for local imagePaths, defaults to the server process current working directory
• GEMINI_REVIEW_STATE_DIR: bridge state directory, defaults to ~/.codex/state/gemini-review
• GEMINI_REVIEW_DEBUG_LOG: debug log path, defaults to ~/.codex/state/gemini-review/debug.log; custom paths must resolve under GEMINI_REVIEW_STATE_DIR
• GEMINI_API_KEY: Gemini API key
• GOOGLE_API_KEY: alternate Gemini API key env var

Notes Copy Chapter

• The bridge defaults to the direct Gemini API path. This is the intended reviewer backend for the ARIS skill overlay.
• The server auto-loads only GEMINI_API_KEY and GOOGLE_API_KEY from ~/.gemini/.env; the file is ignored if it is a symlink, not owned by the current user, not a regular file, or group/world-writable.
• GEMINI_REVIEW_BACKEND=auto is still supported if you want API-first auto-selection; it uses the API when a Gemini API key is configured and otherwise falls back to the Gemini CLI. Antigravity is never selected by auto; use GEMINI_REVIEW_BACKEND=agy explicitly.
• GEMINI_REVIEW_BACKEND=agy routes review prompts through agy --print, which is useful when you want Codex to keep the MCP contract but use Antigravity CLI authentication/model routing. Because agy --print can exit successfully after writing a conversation transcript or generated artifact without printing the final text to stdout, the bridge passes a per-call --log-file and can recover from the Antigravity transcript for that same invocation only.
• The agy backend is fail-closed for ARIS's cross-model invariant: the bridge cannot choose the Antigravity model per call, so it treats Antigravity's selected model as external configuration. After each call it must recover an actual Gemini-family model id from the current invocation's log/transcript and returns that id as model. If a caller passes a model value, the response also includes requested_model and a warning because the current agy CLI does not expose per-call model selection. If Antigravity routes the request to a non-Gemini model, or the log/transcript does not expose a model id, the call fails instead of returning an unauditable "agy-cli" placeholder.
• Antigravity transcript recovery validates conversation ids with ^[0-9A-Za-z_-]+$, caps ids at 128 characters, requires the per-call invocation nonce, and accepts the nonce only from user/bridge-written transcript events before considering later transcript lines. Generated text artifacts are read only from the final planner response, only as a fallback when that response has no substantive inline text, only if their resolved file:// path stays under GEMINI_REVIEW_AGY_APP_DATA_DIR/brain/<conversation>/, and only if the artifact was updated during the current invocation window.
• If the default API model is temporarily rate-limited on your current free-tier window, keep the same bridge and set GEMINI_REVIEW_MODEL=gemini-flash-latest as a model override.
• The tools argument is accepted for compatibility with existing skills, but is ignored. This matches the original pattern where the external reviewer only sees the prompt context prepared by Codex.
• imagePaths / image_paths are supported only by the direct Gemini API backend in this bridge. Paths must resolve under GEMINI_REVIEW_WORKSPACE_ROOT and are opened with no-symlink safeguards; platforms where the opened fd cannot be re-verified fail closed. CLI and agy fallback paths remain text-only.
• threadId is a bridge-local conversation id persisted under ~/.codex/state/gemini-review/threads/ by default and can be passed to review_reply.
• jobId is a bridge-local background task id stored under ~/.codex/state/gemini-review/jobs/ by default, so status can be resumed across MCP server restarts.
• State files contain review prompts/responses so async jobs and threads can resume. The bridge creates state, thread, job, debug-log, and per-call agy log directories with owner-only permissions where possible; agy per-call log directories are temporary and are removed after the call. Delete GEMINI_REVIEW_STATE_DIR when you no longer need resumability. If you override GEMINI_REVIEW_STATE_DIR, choose a private directory rather than a shared /tmp path.
• This is intentionally a narrow, repo-local adapter. We did not directly vendor a generic Gemini MCP server, because the ARIS reviewer-aware skills expect the specific review / review_reply / review_start / review_reply_start / review_status interface and resumable review-thread semantics.

Validation Copy Chapter

This bridge was validated against the ARIS reviewer workflow in a privacy-safe way:

• direct bridge smoke tests passed for:
  • review
  • review_start -> review_status
  • review_reply_start -> review_status
  • local-image multimodal review through imagePaths
• the overlayed reviewer-aware Codex skills were checked to ensure all 15 predefined overrides point at this bridge contract
• representative Codex-side executions on a private, non-public research repository confirmed that real skill runs can enter the gemini-review path from research-review, idea-generation, and paper-planning style workflows

Important nuance from testing:

• Gemini free tier was sufficient for development-style validation, but bursty back-to-back runs could still trigger temporary 429 responses
• on the same setup, a later retry completed sync review, async review_start -> review_status, and threaded review_reply_start -> review_status successfully with GEMINI_REVIEW_MODEL=gemini-flash-latest
• long synchronous reviewer calls can still hit host-side MCP tool timeouts before Gemini responds
• because of that, the async path is not just an implementation detail; it is the recommended operational path for long reviews

When to use sync vs async Copy Chapter

• Use review / review_reply for short prompts that comfortably finish within the host MCP tool timeout.
• Use review_start / review_reply_start + review_status for long paper or project reviews. This avoids the observed Codex -> tools/call timeout around 120 seconds.

Async flow Copy Chapter

Start a long review:

{
  "name": "review_start",
  "arguments": {
    "prompt": "Review this paper draft..."
  }
}

Multimodal example:

{
  "name": "review_start",
  "arguments": {
    "prompt": "Review this poster PNG for readability and clipping.",
    "imagePaths": ["poster/poster_v1.png"]
  }
}

Example response:

{
  "jobId": "5d8d0a9c5a2f4f42ae44f6f0c2d73f6f",
  "status": "queued",
  "done": false
}

Poll later:

{
  "name": "review_status",
  "arguments": {
    "jobId": "5d8d0a9c5a2f4f42ae44f6f0c2d73f6f",
    "waitSeconds": 20
  }
}

When complete, review_status returns the same reviewer payload fields as the synchronous tools, including threadId, response, model, backend, and stop_reason. For agy calls, the payload also includes model_provenance; if a model was requested, it also includes requested_model and warning.

Provenance and References Copy Chapter

• Upstream interaction pattern: ARIS claude-review bridge and skills-codex-claude-review in Auto-claude-code-research-in-sleep
  • https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep/tree/main/mcp-servers/claude-review
  • https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep/tree/main/skills/skills-codex-claude-review
• Gemini backends used by this bridge:
  • Official Gemini API docs: https://ai.google.dev/api
  • Official Gemini CLI: https://github.com/google-gemini/gemini-cli
• Gemini API access and pricing:
  • API key / AI Studio entry: https://aistudio.google.com/apikey
  • Gemini API pricing: https://ai.google.dev/gemini-api/docs/pricing
• MCP protocol reference:
  • https://modelcontextprotocol.info/specification/
• Related generic Gemini MCP server example:
  • eLyiN/gemini-bridge: https://github.com/eLyiN/gemini-bridge
  • We inspected this class of generic Gemini MCP servers, but kept a thin compatibility adapter here because their tool schema and session model do not match the ARIS review-only bridge directly.

Overview (`mcp-servers/grok-exec/README.md`) Copy Section

Grok CLI → MCP 桥接

这个桥接沿用相邻 codex-exec/server.py 的 stdio、进度通知、取消和会话记录设计，改用 Grok CLI 的 headless 模式。提供 grok 和 grok-reply，返回结构保留 threadId / content。Python 3.9+，无需第三方 Python 依赖。

默认模型为 grok-4.7、推理强度为 xhigh。在 Grok CLI 1.0.46 上实测，服务返回的模型名是 grok-4.7-build，首次调用和续接的会话摘要均记录 reasoning_effort: xhigh。CLI 显示名、请求名和服务返回名可能不同，因此返回值分别记录请求值与实际值。

注册 Copy Chapter

先安装 Grok CLI 并完成 grok login。桥接使用 CLI 已有的登录状态，不复制认证 token，也不需要另外填 API key。

Claude Code（将路径换成自己的 ARIS 仓库绝对路径）：

claude mcp add grok -s user -- python3 /absolute/path/to/aris/mcp-servers/grok-exec/server.py

Codex：

codex mcp add grok --env GROK_BIN=/absolute/path/to/grok -- python3 /absolute/path/to/aris/mcp-servers/grok-exec/server.py

在 Codex 的 ~/.codex/config.toml 中给已有的 [mcp_servers.grok] 表补上 tool_timeout_sec = 3660。桥接自身默认 3600 秒超时，宿主需要留出取消与清理时间；进度通知不保证延长宿主期限。Codex MCP 配置说明。其他客户端也应设置相应的工具调用超时。

重新启动 MCP 客户端后检查工具列表。这个独立服务不自动修改 ARIS skills 的 reviewer 路由；需要使用 Grok 时显式调用它。一次连通性测试不等于一次研究评审通过。

调用 Copy Chapter

首次调用：

{
  "name": "grok",
  "arguments": {
    "prompt": "请读取指定文件并审阅，指出有证据支持的问题。",
    "cwd": "/absolute/path/to/project",
    "model": "grok-4.7",
    "effort": "xhigh"
  }
}

续接同一会话：

{
  "name": "grok-reply",
  "arguments": {
    "threadId": "首次调用返回的 UUID",
    "prompt": "我修改了这些文件，请继续检查。"
  }
}

grok-reply 使用 Grok 的原生 --resume，并显式重传首次调用的模型、effort、cwd、sandbox、工具集合和轮次上限。桥接重启后仍从保存的会话设置恢复；续接调用不能改这些参数。未知会话 ID 会报错，需要新建会话。

默认是文件审阅用途：内置工具只开读取、搜索、列目录；关闭子代理、网页搜索和计划模式，禁止 MCP meta-tools。权限模式为 dontAsk，无需等待交互确认。sandbox 由 Grok CLI 实施，其操作系统支持和网络限制以 CLI 文档为准；不能把这个参数视为所有平台都具备同等强度的隔离保证。

成功结果的 structuredContent 包含：

{
  "threadId": "...",
  "content": "最终回复",
  "model": "grok-4.7-build",
  "effort": "xhigh",
  "stopReason": "end_turn",
  "requestedModel": "grok-4.7",
  "requestedEffort": "xhigh"
}

effort 从该 Grok 会话的 summary.json 读取；摘要不可用时返回 null，不会拿请求值冒充实际值。实际 effort 与请求不一致时，调用标为错误。model 取 CLI 返回的模型信息。

执行与失败处理 Copy Chapter

• 长提示词通过权限为 0600 的临时文件传入，调用结束后删除；不经过 shell 插值。
• 转发原生事件为 grok/event。客户端提供 progress token 时，默认每 15 秒发送心跳；等待模型期间仍可响应 ping 和取消。
• CLI 失败、结果截断、轮次用完、缺失最终结果或非零退出码均返回 isError: true，不把半截回答当成正常审阅。
• 超时、客户端取消或 stdin 关闭时，回收子进程；POSIX 上清理进程组。取消后仍不退出的子进程会被强制终止。
• 桥接不自动重新发起工具调用。底层 Grok CLI 可能进行内部网络重试（已观察到最多15次）；连通性探测建议用 GROK_EXEC_TIMEOUT_SEC=75 限制时长。会话设置记录与 Grok 原生会话共同用于续接。
• 每个服务进程顺序执行调用。此版本只验证了单会话首轮、续接及故障处理，未做高并发或长时间配额测试。

环境变量：

桥接沿用 CLI 的 GROK_HOME 来定位会话摘要；未设置时是 ~/.grok。调试日志记录 RPC 方法与命令参数，不记录提示词正文；原生 Grok 会话仍按 CLI 自己的策略落盘。

验证 Copy Chapter

无需网络或 Grok 账号的协议回归测试：

python3 -m unittest discover -s tests -p 'test_grok_exec_bridge.py' -v

2026-10-05 在 macOS、Grok CLI 1.0.46 上完成真实验证：直接 headless 调用成功；通过 MCP 读取合成文件，再用 grok-reply 回忆其中随机 token 成功，两个回合实际均为 grok-4.7-build / xhigh，两轮合计约 21 秒。没有据此宣称 headless 已启用 500k 上下文，或已验证复杂研究审阅质量。

排查模型列表获取失败 Copy Chapter

2026-10-05 另一次调用出现 unknown model id，当时只列出 grok-4.6 / grok-4.5。本机 CLI 日志同时记录 had_real_catalog=false、model_count=2 和 model catalog refresh failed；之后模型目录刷新成功，恢复4项（包含4.7），同一桥接再次返回真实的 grok-4.7-build / xhigh 回复。

因此，这种报错需要先核对 grok models、~/.grok/models_cache.json 的更新时间、~/.grok/logs/unified.jsonl 中的目录刷新结果，以及 CLI 路径、GROK_HOME 和宿主网络权限。后续同机对照确认，旧 MCP 子进程没有继承代理变量，直接连接报 No route to host，经本机已有代理可到达服务；这解释了该机器上的主要连接失败。遵循宿主审批流程取得所需访问，不关闭权限保护；不静默改用其他模型，不自动重试推理请求。日志与配置排查时不输出认证 token。

MCP 启动环境与代理 Copy Section

从应用启动的 MCP 服务不一定继承终端登录 shell 的代理。2026-10-05 的故障通过给本机 Codex 注册项显式补入 http_proxy / https_proxy 修复；清除 shell 继承代理、只使用注册 env 的首轮与续接均返回 grok-4.7-build / xhigh。如果你的网络依赖代理，在 [mcp_servers.grok.env] 使用你实际可达的代理地址，并重启 MCP 服务；不要把本机地址硬编码到共享桥接源码。

另一个受限会话连本地代理也被阻断，且宿主拒绝提权/停止进程。配置代理不能解除宿主沙箱限制，应按宿主权限流程处理；不能通过关闭隔离或换模型绕过。探测设置短超时；清理时核对准确的 session ID 与独立进程组，不误杀用户的 Grok 交互窗口。

Overview (`mcp-servers/manual-review/README.md`) Copy Section

Manual Review MCP Server

English | 中文

What it does Copy Chapter

A human-in-the-loop MCP server for ARIS cross-model review. Instead of calling Codex/GPT API automatically, it opens a browser page where you copy the review prompt to a different model family and paste the response back.

Zero API cost. Works with any text model ARIS can classify by family (OpenAI, Anthropic, Google, DeepSeek, Moonshot/Kimi, Qwen) — a name outside those cannot be shown to differ from the executor's, so it cannot acquit.

When to use Copy Chapter

• You don't have a Codex/GPT Plus subscription
• You want to use free models (ChatGPT free tier, DeepSeek, Kimi, Gemini, etc.)
• You prefer to choose which model reviews each time
• You're on a budget but still want cross-model review quality

Installation Copy Chapter

# Register with Claude Code
claude mcp add manual-review -s user -- python3 /path/to/mcp-servers/manual-review/server.py

# Then use in any skill:
/auto-review-loop "topic" — reviewer: manual
/research-review "paper/" — reviewer: manual

Modes Copy Chapter

Browser mode (default) Copy Section

Opens a local web page. Works on Windows, macOS, and Linux with a desktop environment.

File mode (headless Linux) Copy Section

For SSH/headless environments without a browser:

export MANUAL_REVIEW_MODE=file

The server writes the prompt to a per-thread directory with a cross-model warning at the top of prompt.md. Read .aris/pending_review/pending_review.json — the prompt_file field tells you where to read the prompt, the response_file field tells you where to write the model's response. The file must be non-empty and stable (unchanged across two reads) before it's accepted.

Environment Variables Copy Chapter

Recovery Copy Chapter

If you accidentally close the browser tab, open .aris/pending_review/pending_review.json and reopen the exact url value. It includes a one-session token — copy it in full (e.g., http://127.0.0.1:17900?token=abc123). Do not type the bare http://127.0.0.1:17900 as it will return 403.

Future Work Copy Chapter

• Image generation support (manual alternative to codex-image2)
• Image review loop for paper illustrations

功能说明 Copy Chapter

ARIS 跨模型评审的人工中转 MCP 服务器。不自动调用 Codex/GPT API，而是打开浏览器页面，让你将评审提示词复制到不同模型家族，再将回复粘贴回来。

零 API 成本。支持任何文本模型。

适用场景 Copy Chapter

• 没有 Codex/GPT Plus 订阅
• 想使用免费模型（ChatGPT 免费版、DeepSeek、Kimi、Gemini 等）
• 希望每次自行选择评审模型
• 预算有限但仍想获得跨模型评审质量

安装 Copy Chapter

# 注册到 Claude Code
claude mcp add manual-review -s user -- python3 /path/to/mcp-servers/manual-review/server.py

# 在任意技能中使用：
/auto-review-loop "topic" — reviewer: manual
/research-review "paper/" — reviewer: manual

模式 Copy Chapter

浏览器模式（默认） Copy Section

打开本地网页。适用于 Windows、macOS 和有桌面环境的 Linux。

文件模式（无桌面 Linux） Copy Section

适用于 SSH/无桌面环境：

export MANUAL_REVIEW_MODE=file

服务器将提示词写入按线程隔离的子目录，prompt.md 顶部包含跨模型警告。读取 .aris/pending_review/pending_review.json — prompt_file 字段指向提示词文件，response_file 字段指向你应写入回复的位置。文件必须非空且稳定（两次读取内容不变）才会被接受。

环境变量 Copy Chapter

恢复 Copy Chapter

如果不小心关闭了浏览器标签，打开 .aris/pending_review/pending_review.json，复制完整的 url 值（包含一次性 token，如 http://127.0.0.1:17900?token=abc123）重新打开。不要手动输入裸地址 http://127.0.0.1:17900，会返回 403。

后续计划 Copy Chapter

• 图片生成支持（codex-image2 的手动替代方案）
• 论文插图的图片评审循环

Overview (`skills/skills-codex-claude-review/README.md`) Copy Section

skills-codex-claude-review

Frozen legacy partial overlay. Kept for existing installations and links; no new workflow features or regeneration from the base pack. Use the full skills-codex pack with reviewer selection for new installs and migration: safe migration. The historical installation and protocol notes below remain for existing users; transport names and old assurance statements do not establish actual model identity, review completion, or acceptance.

This package is a thin override layer for users who want:

• Codex as the main executor
• Claude Code as the reviewer
• the local claude-review MCP bridge instead of a second Codex reviewer

It is designed to sit on top of the upstream Codex-native package at skills/skills-codex/.

Because the executor is Codex and the reviewer is Claude, overlay traces and
audit artifacts record review_independence: cross-family and
acceptance_status: accepted. The verifier still decides whether all required
audits reached accepted assurance.

What this package contains Copy Chapter

• Only the review-heavy skill overrides that need a different reviewer backend
• No duplicate templates or resource directories
• No replacement for the base skills/skills-codex/ installation

Current overrides:

• research-review
• novelty-check
• research-refine
• auto-review-loop
• paper-plan
• paper-figure
• paper-write
• auto-paper-improvement-loop

Install Copy Chapter

1. Install the base Codex-native mirror first:

bash ~/aris_repo/tools/install_aris_codex.sh ~/your-project

2. Re-run with the Claude overlay enabled:

bash ~/aris_repo/tools/install_aris_codex.sh ~/your-project --reconcile --with-claude-review-overlay

3. Register the local reviewer bridge:

mkdir -p ~/.codex/mcp-servers/claude-review
cp mcp-servers/claude-review/server.py ~/.codex/mcp-servers/claude-review/server.py
codex mcp add claude-review -- python3 ~/.codex/mcp-servers/claude-review/server.py

If your Claude setup depends on a shell helper such as claude-aws, use the wrapper instead:

cp mcp-servers/claude-review/run_with_claude_aws.sh ~/.codex/mcp-servers/claude-review/run_with_claude_aws.sh
chmod +x ~/.codex/mcp-servers/claude-review/run_with_claude_aws.sh
codex mcp add claude-review -- ~/.codex/mcp-servers/claude-review/run_with_claude_aws.sh

Why this exists Copy Chapter

The upstream skills/skills-codex/ path already supports Codex-native execution with a second Codex reviewer via spawn_agent.

This package adds a different split:

• executor: Codex
• reviewer: Claude Code CLI
• transport: claude-review MCP

For long paper and review prompts, the reviewer path uses:

• review_start
• review_reply_start
• review_status

This avoids the observed Codex-hosted timeout issue when Claude is invoked synchronously through a local bridge.

Overview (`skills/skills-codex-gemini-review/README.md`) Copy Section

skills-codex-gemini-review

Frozen legacy partial overlay. Kept for existing installations and links; no new workflow features or regeneration from the base pack. Use the full skills-codex pack with reviewer selection for new installs and migration: safe migration. The historical installation and protocol notes below remain for existing users; transport names and old assurance statements do not establish actual model identity, review completion, or acceptance.

This package is a thin override layer for users who want:

• Codex as the main executor
• Gemini as the reviewer
• the local gemini-review MCP bridge instead of a second Codex reviewer

It is designed to sit on top of the upstream Codex-native package at skills/skills-codex/.

Because the executor is Codex and the reviewer is Gemini, overlay traces and
audit artifacts record review_independence: cross-family and
acceptance_status: accepted. The verifier still decides whether all required
audits reached accepted assurance.

What this package contains Copy Chapter

• Only the reviewer-aware skill overrides that need a different reviewer backend
• No duplicate templates or resource directories
• No replacement for the base skills/skills-codex/ installation

Current overrides:

• idea-creator
• idea-discovery
• idea-discovery-robot
• research-review
• novelty-check
• research-refine
• auto-review-loop
• grant-proposal
• paper-plan
• paper-figure
• paper-poster-html
• paper-slides
• paper-write
• paper-writing
• auto-paper-improvement-loop

Core 8 vs Full 15 Copy Chapter

To avoid confusion, there are two useful ways to describe this overlay:

• Core 8: the direct reviewer-heavy overlay set that maps one-to-one to the earlier Claude-review route
• Full 15: the current reviewer-aware Codex skill surface routed to Gemini in this repository

The core 8 are:

• research-review
• novelty-check
• research-refine
• auto-review-loop
• paper-plan
• paper-figure
• paper-write
• auto-paper-improvement-loop

The additional 7 routed reviewer-aware entry points are:

• idea-creator
• idea-discovery
• idea-discovery-robot
• grant-proposal
• paper-writing
• paper-slides
• paper-poster-html

So when comparing against the Claude overlay, the cleanest statement is:

The Gemini route preserves the same core 8-skill reviewer overlay shape, but expands the practical reviewer-facing surface to 15 skills in the current repo.

Direct Consumers vs Wrappers Copy Chapter

• 12 direct consumers call mcp__gemini-review__review_start / review_reply_start / review_status themselves:
  • research-review
  • novelty-check
  • research-refine
  • auto-review-loop
  • paper-plan
  • paper-figure
  • paper-write
  • auto-paper-improvement-loop
  • idea-creator
  • grant-proposal
  • paper-slides
  • paper-poster-html
• 3 wrappers mostly orchestrate downstream reviewer-aware skills and pass REVIEWER_MODEL=gemini-review through:
  • idea-discovery
  • idea-discovery-robot
  • paper-writing

Install Copy Chapter

Before registering the bridge, prepare the direct Gemini API path:

• Gemini API: set GEMINI_API_KEY or GOOGLE_API_KEY (for example in ~/.gemini/.env)

Optional fallback only:

• Gemini CLI: install gemini and complete login/auth if you explicitly want GEMINI_REVIEW_BACKEND=cli

1. Install the base Codex-native mirror first:

bash ~/aris_repo/tools/install_aris_codex.sh ~/your-project

2. Re-run with the Gemini overlay enabled:

bash ~/aris_repo/tools/install_aris_codex.sh ~/your-project --reconcile --with-gemini-review-overlay

3. Register the local reviewer bridge:

mkdir -p ~/.codex/mcp-servers/gemini-review
cp mcp-servers/gemini-review/server.py ~/.codex/mcp-servers/gemini-review/server.py
codex mcp add gemini-review --env GEMINI_REVIEW_BACKEND=api -- python3 ~/.codex/mcp-servers/gemini-review/server.py

The bridge defaults to the direct Gemini API path. This is the intended reviewer backend for this overlay.

If the default API model is temporarily rate-limited on your current free-tier window, keep the same overlay and bridge, and override only the reviewer model:

codex mcp remove gemini-review
codex mcp add gemini-review --env GEMINI_REVIEW_BACKEND=api --env GEMINI_REVIEW_MODEL=gemini-flash-latest -- python3 ~/.codex/mcp-servers/gemini-review/server.py

Why this exists Copy Chapter

The upstream skills/skills-codex/ path already supports Codex-native execution with a second Codex reviewer via spawn_agent.

This package adds a different split:

• executor: Codex
• reviewer: Gemini direct API
• transport: gemini-review MCP

For long paper and review prompts, the reviewer path uses:

• review_start
• review_reply_start
• review_status

This avoids the observed Codex-hosted timeout issue when Gemini is invoked synchronously through a local bridge.

Validation Summary Copy Chapter

This overlay was validated in two ways:

• Coverage check: all 15 predefined reviewer-aware skill overrides in this package were checked to confirm they target gemini-review
• Runtime check:
  • the underlying bridge completed sync, async, threaded follow-up, and multimodal local-image review tests
  • representative Codex-side runs on a private, non-public research repository confirmed that real skill executions could reach the Gemini reviewer path for research-review, idea-generation, and paper-planning style tasks

Operational note:

• Gemini free tier was usable for this workflow in practice, but bursty stress tests could still produce temporary 429 responses
• on the same setup, a later retry completed sync review, async review_start -> review_status, and threaded review_reply_start -> review_status successfully with GEMINI_REVIEW_MODEL=gemini-flash-latest
• for long prompts, prefer the async review_start / review_reply_start + review_status path

References Copy Chapter

• Upstream overlay pattern from ARIS:
  • https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep/tree/main/skills/skills-codex-claude-review
  • https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep/tree/main/mcp-servers/claude-review
• Local Gemini reviewer bridge in this repo:
  • mcp-servers/gemini-review/README.md
• Gemini backends referenced by this overlay:
  • Official Gemini API: https://ai.google.dev/api
  • Official Gemini CLI: https://github.com/google-gemini/gemini-cli
  • AI Studio API key entry: https://aistudio.google.com/apikey

This package keeps the upstream ARIS skill shape, but swaps the reviewer transport to the local gemini-review bridge. It now covers every predefined Codex skill in this repo that previously depended on a secondary Codex reviewer or mcp__codex__codex review step. We intentionally did not directly depend on a generic Gemini MCP server package because the ARIS review skills rely on the narrow review* tool contract, resumable review-thread behavior, and now optional local-image review for poster PNGs.

Overview (`skills/skills-codex/README.md`) Copy Section

`skills-codex`

Codex-native mirror and adaptation layer for the main ARIS skills/ package.

Scope Copy Chapter

• Base mirror coverage: all 85 mainline skills under skills/
• Support directory: shared-references/, with all 30/30 mainline reference names mirrored
• Default reviewer contract for reviewer-heavy skills:
  • round 1: spawn_agent
  • follow-up: send_input
  • model: gpt-6-astra; deep reviews: ultra, regular reviews: xhigh
  • base Codex self-review: review_independence: same-family,
    acceptance_status: provisional
  • other reviewers: select a backend in the full pack; acceptance depends on actual model identities, completed review scope, and the applicable gate

This package is still an appendage to the Claude mainline, not a separate Codex-first product line.

Recommended Install Copy Chapter

Project-local install is the default path for Codex:

git clone https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep.git ~/aris_repo
cd ~/your-project

bash ~/aris_repo/tools/install_aris_codex.sh .

This creates a flat managed layout:

.agents/skills/<skill-name> -> ~/aris_repo/skills/skills-codex/<skill-name>
.aris/installed-skills-codex.txt
AGENTS.md   # managed Codex block

Reconcile after upstream changes:

cd ~/aris_repo && git pull
bash ~/aris_repo/tools/install_aris_codex.sh ~/your-project --reconcile

Uninstall only managed Codex entries:

bash ~/aris_repo/tools/install_aris_codex.sh ~/your-project --uninstall

Select a Reviewer Copy Chapter

Use the complete pack with selectable reviewers.
For one invocation, add — reviewer: antigravity (or grok, claude-code,
codex). For a project default, create .aris/reviewer.json yourself:

{"backend": "antigravity", "model": "gemini-4-argon-high", "effort": "high"}

Register the selected backend's MCP separately as described in the linked
contract. claude-code uses the CLI's configured provider and accepts no effort
override. Selecting a transport does not by itself establish cross-family review
or acceptance. The legacy agy route still uses gemini-review; it is distinct
from antigravity.

Migrate Frozen Partial Overlays Copy Chapter

skills-codex-claude-review/ and skills-codex-gemini-review/ are frozen legacy
snapshots. Their directories and existing links remain available, but base skill
changes no longer regenerate them. New installations should use the full pack.
The old overlay install flags remain for compatibility, not ongoing feature sync.

For managed project symlinks, first inspect .agents/skills/<name> with
readlink and save .aris/installed-skills-codex.txt plus any customized source
files. Editing a symlinked skill edits its repository target; preserve those
changes before switching. Preview reconciliation without either overlay flag:

bash ~/aris_repo/tools/install_aris_codex.sh ~/your-project --reconcile --dry-run

Check that the planned retargets point to skills/skills-codex/, then run the same
command without --dry-run. Real directories are conflicts and are not replaced.
For an unmanaged overlay link, inspect it and use --replace-link <skill-name>
only for that specific link, previewing first. Keep the overlay directories;
merge relevant personal edits into your chosen full-pack source deliberately.

For global copied skills in ~/.codex/skills/, back up the affected skill
directories outside that discovery directory. Compare each installed overlay
skill with its frozen source and the corresponding full-pack skill, preserving
personal edits separately. Stage the full-pack replacements in a temporary
directory, reapply those edits, and inspect the result before replacing only the
reviewed installed directories. Do not copy an entire overlay over the full pack
or bulk overwrite existing skills. Then set the project reviewer configuration
and register its bridge. No migration command here writes global settings
automatically; restart Codex after installation changes so it reloads the pack.

Copy Install and Update Copy Chapter

If you intentionally use a copied Codex install instead of managed project symlinks:

mkdir -p ~/.codex/skills
cp -a ~/aris_repo/skills/skills-codex/. ~/.codex/skills/

Update copied installs with:

bash ~/aris_repo/tools/smart_update_codex.sh
bash ~/aris_repo/tools/smart_update_codex.sh --apply

For a copied project-local Codex install:

bash ~/aris_repo/tools/smart_update_codex.sh --project ~/your-project
bash ~/aris_repo/tools/smart_update_codex.sh --project ~/your-project --apply

smart_update_codex.sh refuses symlink-managed installs and redirects them to install_aris_codex.sh --reconcile.

Non-Degrading Skills Copy Chapter

The following Codex skills must not silently degrade when their required capability is missing:

• comm-lit-review
• research-lit
• paper-poster-html
• pixel-art

If the required source, reviewer, or local preview capability is unavailable, the skill should stop and tell the user what to configure.

Overview (`tools/experiment_queue/README.md`) Copy Section

experiment-queue Tools

Scheduler and manifest builder for /experiment-queue skill.

Files Copy Chapter

• build_manifest.py — Expands grid spec (YAML/JSON) into explicit job manifest
• queue_manager.py — Scheduler that runs on the remote host; polls, launches, retries, cleans

Install on Remote Copy Chapter

The /experiment-queue skill auto-installs these on the SSH host under ~/.aris_queue/ per invocation (idempotent). The skill resolves the local helpers via a fallback chain (.aris/tools/experiment_queue/ → tools/experiment_queue/ → $ARIS_REPO/tools/experiment_queue/ → same, resolved via the global pointer file ~/.aris/repo, #366) so it works from any project layout.

For manual install (run from anywhere; $ARIS_REPO points at the cloned ARIS repo root):

ssh <server> 'mkdir -p ~/.aris_queue'
scp "$ARIS_REPO/tools/experiment_queue/queue_manager.py" \
    "$ARIS_REPO/tools/experiment_queue/build_manifest.py" \
    <server>:~/.aris_queue/

Example Copy Chapter

1. Write grid spec (on local or remote) Copy Section

grid_spec.yaml:

project: my_grid_experiment
cwd: /home/user/your_project
conda: my_env
gpus: [0, 1, 2, 3, 4, 5, 6, 7]
max_parallel: 8
oom_retry: {delay: 120, max_attempts: 3}

phases:
  - name: distill
    grid:
      N: [64, 128, 256]
      seed: [42, 200, 201]
      n_train_subset: [50000, 150000, 500000, 652000]
    template:
      id: "s${seed}_N${N}_n${n_train_subset}"
      cmd: >
        python run_distill.py --backbone softmax --lam 0.5
        --t_max_distill 0 --K 500 --L 96 --W 16 --n_steps 30000
        --batch_size 128 --lr 1e-4 --seed ${seed} --subset_seed 2024
        --n_hidden ${N} --n_train_subset ${n_train_subset}
      expected_output: "figures/distill_sw_N${N}_*_seed${seed}.json"

2. Build manifest Copy Section

python3 build_manifest.py --config grid_spec.yaml --output manifest.json

3. Launch scheduler Copy Section

Use a per-run directory under ~/.aris_queue/runs/ so concurrent queues don't collide and crash-resume is reproducible. Note that scp runs in SFTP mode in modern OpenSSH and does NOT reliably expand $HOME in destination paths — use remote-relative paths for scp destinations and $HOME-prefixed paths only inside ssh command strings (where remote bash expands them):

RUN_TS=$(date -u +%Y%m%dT%H%M%SZ)
REMOTE_RUN_REL=".aris_queue/runs/$RUN_TS"          # for scp (relative to remote home)
REMOTE_RUN_DIR="\$HOME/$REMOTE_RUN_REL"            # for ssh commands (expanded remotely)

ssh <server> "mkdir -p \"$REMOTE_RUN_DIR/logs\" \"\$HOME/.aris_queue\""
scp manifest.json <server>:"$REMOTE_RUN_REL/manifest.json"

ssh <server> "nohup python3 \"\$HOME/.aris_queue/queue_manager.py\" \\
    --manifest \"$REMOTE_RUN_DIR/manifest.json\" \\
    --state    \"$REMOTE_RUN_DIR/queue_state.json\" \\
    --log-dir  \"$REMOTE_RUN_DIR/logs\" \\
    > \"$REMOTE_RUN_DIR/queue_mgr.log\" 2>&1 &"

Note: --log-dir is the per-job log directory the scheduler reads for OOM detection. The flag --log is declared by argparse but unused; do not pass it.

4. Monitor Copy Section

ssh <server> "jq '.jobs | group_by(.status) | map({(.[0].status): length}) | add' \"$REMOTE_RUN_DIR/queue_state.json\""

Returns:

{"completed": 30, "running": 6, "pending": 0}

State Machine Copy Chapter

pending → running → completed
                  ↘ failed_oom → pending (after delay, up to max_attempts)
                               ↘ stuck (after max_attempts)
                  ↘ failed_other → stuck

Dependencies Copy Chapter

• Python 3.8+
• nvidia-smi on remote
• screen on remote
• Optional: pyyaml (only if using YAML grid specs)

Invariants Copy Chapter

• No GPU overlap: scheduler only assigns GPU with memory.used < 500 MiB
• State is source of truth: queue_state.json is written atomically every step
• Idempotent: safe to kill and restart the scheduler; picks up from state
• Output-based completion: completion is verified by expected_output existing, not just by screen/process exit

Not Yet Supported Copy Chapter

• Mid-run GPU reshuffling (if GPU becomes unavailable mid-job)
• Automatic GPU-per-job count (all jobs assumed single-GPU)
• Distributed multi-node queues
• Auto-sync results back to local

Overview (`skills/paper-poster-html/templates/README.md`) Copy Section

Template gallery — paper-poster-html

Three neutral HTML scaffolds, forked from the posterly templates (MIT, © 2026 Ruishuo Chen —
see ../NOTICE.md) and adapted for ARIS: flat de-gradient, --fs-* token scale, zero
inline-style utility classes, and the data-source / data-color-exempt contracts. Class
names are unchanged, so COMPONENTS.md (the component contract catalog) applies to all three.

Each template is self-contained and neutral: no lab branding, no paper content — only
TODO placeholders. The authoring loop is: copy one to your working dir as poster.html →
apply a token pack → fill TODOs with paper content + real figures → run the gates
(run_gates.py) and balance until they pass.

Every layout-critical element carries data-measure-role so the measurement gate can locate
columns / hero / footer regions across templates. Do not remove these attributes — the
measure gate depends on them.

Picking a template Copy Chapter

(File names follow DESIGN_FINAL §1: the ARIS forks drop the posterly _neutral suffix.)

Scaffolds, not finished posters Copy Chapter

A template is a scaffold, not a poster. Figures are commented out and copy is TODO
stubs, so each column only fills the top of the canvas. That has gate consequences you should
expect — do not "fix" them on a fresh scaffold:

• preflight passes out of the box. It checks structure (valid data-measure-role values,
  no LaTeX residue, no bare < inside $…$ math, the root data-measure-role="poster"),
  which the scaffold already satisfies.
• style_check source rules (1–3, 5–11) pass on the forked scaffold. The ARIS fork has
  no inline styles, no linear-gradient, no stray hex outside the token block — so the static
  source gate is green on the empty template. (The upstream posterly originals keep inline
  styles and would FAIL style_check — that is expected; the fork exists precisely to fix
  that.)
• measure and polish are gates for your finished poster. They check that columns
  bottom-align to within 5 px, that the gap to the footer sits in a tight band (30–50), that
  intercard gaps stay in [12, 50], and that the canvas fills 95–101% — properties only a
  filled poster can have. An unfilled scaffold is expected to fail them (huge
  column-bottom spread, a large gap to the footer). That is the gate telling you the poster is
  not finished, not a bug in the template.
• asset_check fails until you embed ≥2 real paper figures. A scaffold has none.

So the loop is: copy → apply token pack → fill content + drop in real figures → run
run_gates.py and balance until measure/polish/asset go green. See DESIGN_FINAL §8 for
the full phase structure and the worked ICLR 2026 acceptance case (§13).

Applying a token pack (`tokens/*.json` → `:root`) Copy Chapter

The palette lives in two synchronized places: the tokens/*.json packs (machine-readable, what
style_check/run_gates read for the accent/gold hue_centers) and the :root DESIGN TOKENS
block in each template's <style> (what the browser renders). generic.json is the default
for every venue. Venue packs are opt-in (— venue-colors: true).

To apply a pack, manually copy its values into the template's :root token block (the
block fenced by /* ===== DESIGN TOKENS ===== */ … /* ===== END DESIGN TOKENS ===== */ —
style_check locates the token block by exactly this comment pair, so keep it intact). The
JSON-to-CSS field mapping:

--bg-emphasis: var(--accent-light) and --border-strong: var(--accent) are derived tokens —
leave them as var(--…) references; they follow the accent automatically.

When you pass a pack to the gates (run_gates.py --tokens tokens/<venue>.json,
style_check.py --tokens …), the hue_centers in the JSON are the source of truth for the
hue-cluster check (style rule 4): the two allowed non-neutral hue families are
hue_centers.accent ± 22° and hue_centers.gold ± 22°. If you copied the JSON values into
:root correctly, the rendered hues will land inside those windows. (If you omit --tokens,
style_check derives the centers from the :root --accent / --gold instead.)

Available packs (all share the generic gold family #C9A24A / #FFF7E0; all venue accents
satisfy S ≤ 0.55, L ∈ [0.25, 0.45], hue ∉ [250, 285]):

Venue packs are opt-in identity, not a license to deviate from the discipline: a single
accent family + the shared gold, deep and desaturated, never purple. The default text
venue-badge (COMPONENTS.md) is the primary venue cue; the color pack is secondary.

Retargeting the canvas Copy Chapter

A template ships with a default @page size and a matching .poster size. To change the
canvas you must edit both in the template (each in exactly one place), keeping them
identical — measure's canvas-fill / position-align gate compares the rendered .poster
bounding box against the @page viewport, so a mismatch fails the gate.

1. @page in the <style> block — e.g. @page { size: 185cm 90cm; margin: 0; }.
2. .poster print dimensions in @media print { .poster { … width: 185cm; height: 90cm; } }.
   (The screen .poster uses calc(N * var(--u)) with --u: 1.6px; print uses --u: 1mm, so
   the screen preview scales automatically — you only hardcode the print width/height.)

The canvas parser accepts in / mm / cm / pt units. ICLR 2026 main conference example
(the §13 acceptance case): the official print service spec is 185 × 90 cm landscape, so
start from landscape_4col.html and set both @page and the print .poster to
185cm 90cm / width: 185cm; height: 90cm;.

Safe-area / margin design belongs as internal padding on a full-bleed .poster, never as a
smaller poster — a smaller poster fails the position-align gate (the .poster bbox must align
to (0,0)–(viewport_w, viewport_h)).

Zero inline-style + utility-class policy Copy Chapter

The templates and any finished poster carry no style= attribute (zero tolerance —
style_check rule 2; IMPLEMENTATION_CONVENTIONS §B). To make that possible the templates ship
their own utility classes in the <style> block, replacing every inline style the posterly
originals used:

.fs-1 … .fs-9        font-size: var(--fs-N)
.mt-1 … .mt-6        margin-top: calc(N * var(--u))
.mb-1 … .mb-4        margin-bottom: calc(N * var(--u))
.w-45 .w-50 … .w-100 figure <img> width 45%…100% (5% steps)
.text-secondary .text-muted .nowrap .text-center

The only sanctioned style= survivors:

• the internal markup of a data-color-exempt="logo" element (a logo / seal SVG), and
• style="width: NN%" on a data-source="paper" `` for aspect-ratio width tuning when the
  value is off the 5% grid (prefer the .w-NN class when it lands on a step).

Likewise: no linear-gradient anywhere; the only gradient allowed is the .poster
background radial-gradient tint with all color stops at alpha ≤ 0.06 (style rule 5). All
font-sizes go through the --fs-* scale; calc(var(--fs-N) * k) is allowed only for the
predefined component variants catalogued in COMPONENTS.md (e.g. .eqn--large). All colors
are tokens — no hex literal outside the :root token block (and the exempted logo SVG).

Adding a new template Copy Chapter

A new template MUST:

1. Set @page { size: <W> <H> } (in / mm / cm / pt) inside a <style> block — the
   canvas parser fails if absent — and a matching print .poster size.
2. Carry data-measure-role="poster" on the root poster element.
3. Use the roles consistently: header, banner (optional), body, column, card,
   hero (mutually exclusive with banner), footer-strip (optional), footer.
4. Use the --u unit system (1.6px screen, 1mm print) for ALL sizing via
   calc(N * var(--u)) — never bare px except hairlines (≤ 2px).
5. Carry the :root DESIGN TOKENS block fenced by the
   /* ===== DESIGN TOKENS ===== */ … /* ===== END DESIGN TOKENS ===== */ comment pair,
   the full --fs-1 … --fs-9 scale, and the §B utility classes.
6. Use only components from COMPONENTS.md; no inline style=, no linear-gradient,
   no hex outside the token block.
7. Keep all paper-specific content as TODO placeholders — neutral templates only.

Then add a row to the gallery table above, a catalog note if it introduces any new component
(which requires the COMPONENTS.md new-component checkpoint), and link it in SKILL.md Phase 3.

ARIS INTRO (`docs/ARIS_INTRO.md`) Copy Section

ARIS — Autonomous Research via Adversarial Multi-Agent Collaboration

Let Claude Code do research while you sleep. Wake up to find your paper scored, weaknesses identified, experiments run, and narrative rewritten — autonomously. Repo: github.com/wanshuiyin/Auto-claude-code-research-in-sleep.

TL;DR Copy Chapter

ARIS is a collection of 85 composable Claude Code skills that orchestrate cross-model collaboration: Claude Code drives the research (reads files, writes code, deploys experiments) while an external LLM (GPT-6-Astra via Codex MCP) acts as a critical reviewer. The two models disagree, debate, and force each other to do better — adversarial, not self-play.

Seven workflows (W1 / W1.5 / W2 / W3 / W4 / W5 / W6) compose into a full research lifecycle: idea discovery → experiment bridge → auto-review → paper writing → rebuttal → resubmit → conference talk. Tested end-to-end on real ICLR/NeurIPS submissions. Score progression on a real overnight run: 5/10 → 7.5/10 with 20+ GPU experiments.

💡 The ARIS bet. Markdown is for writers. HTML is for readers. Every workflow artifact stays in Markdown (auditable, machine-parseable, future-proof). When a human needs to actually read one, /render-html produces this view — gated by a fresh cross-model Codex review (the same ARIS invariant every other audit-class skill follows).

The Problem Copy Chapter

Every ML researcher reading this knows the rhythm:

1. Spend 3 weeks reading 80 papers.
2. Brainstorm 12 ideas, kill 9 in your head, fail to validate the remaining 3 quickly.
3. Pick one, lose a week to a bug, miss the GPU window.
4. Submit, get a 5/10 review with "lacks ablation against XYZ".
5. Rebuttal week is 72 hours; you have 2 days of teaching duty.

The bottleneck isn't ideas. It's the end-to-end orchestration between literature → ideation → experiments → writing → rebuttal. AI can compress every individual step, but the integration is fragile — and worse, a single model reviewing its own work falls into local minima.

🚨 Why not self-play with one model? Using Claude Code subagents (or any homogeneous agent team) for both execution and review tends to fall into local minima — the same model reviewing its own patterns creates blind spots. ARIS forces cross-family disagreement: Claude executes, GPT reviews. They don't share lineage, they don't share training data, they don't share blind spots.

Core Architecture Copy Chapter

The system is, in one sentence:

$$
\text{Research} = \arg\max_{\theta}; \mathbb{E}{x \sim \mathcal{D}{\text{ideas}}}\bigl[, U_{\text{exec}}(\theta,;,x) - \lambda \cdot R_{\text{review}}(\theta,;,x) ,\bigr]
$$

where $U_{\text{exec}}$ is the utility of an executor model writing code / running experiments, and $R_{\text{review}}$ is an adversarial regularizer from a cross-family reviewer that penalizes overclaims, fabricated citations, unjustified theorem extensions, and self-flattery. The regularizer is non-differentiable — it's a fresh LLM thread reading the artifact cold.

The reviewer-independence protocol Copy Section

Every review round uses a fresh codex thread. We never use codex-reply to continue a previous review conversation. This is a hard rule, learned from a real NeurIPS run where codex-reply chains inflated scores from 3/10 → 8/10 through narrative accumulation (the reviewer started defending its earlier criticism instead of evaluating the current artifact). The protocol is codified at skills/shared-references/reviewer-independence.md.

┌──────────────────────┐
│  ARIS — execution    │     ┌───────────────────────┐
│  (Claude Code)       │────▶│  Codex MCP (GPT-6-Astra)  │
│  — reads files       │     │  — reads paper cold   │
│  — writes code       │     │  — fresh thread       │
│  — deploys to GPU    │     │  — scores 1-10        │
└──────────────────────┘     │  — suggests fixes     │
         ▲                   └───────────────────────┘
         │                              │
         │                              ▼
         │              ┌─────────────────────────┐
         └──────────────│  weakness list (.md)    │
                        │  fix list (with budget) │
                        └─────────────────────────┘

🔒 Cross-family invariant. The executor and reviewer must be different model families (Claude × GPT, GLM × DeepSeek, Antigravity × Gemini, …). Same-family review is a non-feature; if you only have one provider, the cheapest fix is to add a free DeepSeek or Gemini reviewer via llm-chat MCP.

The Workflows Copy Chapter

Workflow 1 — Idea Discovery & Method Refinement Copy Section

"I have a research direction. What should I actually work on?"

/idea-discovery takes a vague research direction and outputs a ranked, pilot-validated proposal:

1. 📚 Survey — multi-source literature search (Zotero / Obsidian / arXiv / Semantic Scholar / DeepXiv / Exa) builds a landscape map
2. 🧠 Brainstorm — GPT-6-Astra xhigh generates 8-12 concrete ideas anchored to identified gaps
3. 🔍 Novelty check — each top idea cross-checked against arXiv + DBLP for prior work; failed ideas killed early
4. 🧪 Pilot — 2-3 surviving ideas get 1-2-hour single-GPU pilot runs (a real signal, not just LLM opinion)
5. 🏆 Refine — top pilot result fed to /research-refine which anchors the problem, tightens the method, and emits an experiment plan ready for Workflow 1.5

/idea-discovery "factorized gap in discrete diffusion LMs" \
    --- effort: max \
    --- sources: zotero, web, deepxiv

💡 The bet here: a 1-hour GPU pilot tells you more than 1 hour of LLM-only reasoning. Failed pilots also get written to Research Wiki so they become anti-repetition memory.

Workflow 1.5 — Experiment Bridge Copy Section

"I have a plan. Make it run."

/experiment-bridge closes the gap between paper plan and running code:

1. 📋 Read EXPERIMENT_PLAN.md (from W1 or hand-written)
2. 💻 Implement experiment scripts — reuses your existing codebase, adds argparse / logging / seeds where missing
3. 🔬 GPT-6-Astra code review — fresh-thread cross-model review of the generated code BEFORE any GPU time is spent (catches ~80% of bugs that would otherwise burn 8-GPU-hour runs)
4. ✅ Sanity check — smallest config runs first; checks for OOM, NaN, runtime errors
5. 🚀 Deploy — SSH to your GPU server (per CLAUDE.md), launch in screen, capture stdout/stderr
6. 📊 Collect — /monitor-experiment polls until completion, fetches results, formats for downstream skills

/experiment-bridge --- base repo: https://github.com/anthropic-experimental/some-baseline

🔒 Hard rule: code review is cross-model (Claude wrote it, GPT reviews it). Same-family review on your own code is a non-feature — the model that wrote a bug usually can't see it.

Workflow 2 — Auto Review Loop Copy Section

"Review my paper, fix what's wrong, repeat until it passes."

/auto-review-loop is the most-cited workflow. Run it the night before a deadline; wake up to a polished paper.

1. 🔍 Deep review — GPT-6-Astra xhigh reviews the paper, identifies weaknesses (severity tagged)
2. 🩹 Fix — Claude implements the fixes (rewrite, add baselines, run experiments); skips any experiment > 4 GPU-hours, flags for manual follow-up
3. 📊 Re-evaluate — collect results, update paper, feed back to the reviewer (fresh thread)
4. 🔁 Repeat — until score ≥ POSITIVE_THRESHOLD (default 6/10) or MAX_ROUNDS (default 4); if the context window fills mid-loop, auto-resume from REVIEW_STATE.json

/auto-review-loop "focus on Section 3-5, our CRF results are weak" \
    --- difficulty: nightmare \
    --- effort: max

The difficulty: nightmare flag lets GPT-6-Astra read your repo directly via codex exec — Claude can't filter what it sees. Maximum stress test before submission.