ARC
Advanced Research Compass (ARC) is a cache-first research toolkit for
theoretical-physics papers and paper-centered research workflows. It gives an
agent, or a human using the command line, structured access to arXiv full text,
INSPIRE metadata, references, citers, paper summaries, research-domain graphs,
and multi-agent idea/calculation workflows.
ARC is built around five Python command line tools; arc-mcp also runs the
optional MCP server:
arc-paper: paper metadata, references, citers, ar5iv sections, equation
context, full-text search, LLM paper summaries, and paper-summary batches.arc-domain: builds a cached research-domain package from a seed paper and
optional scientific intent.arc-llm: reusable host LLM execution, provider selection, and
proposers-reviewer workflows.arc-typeset: deterministic typesetting utilities, including Markdown to PDF
conversion through Pandoc and XeLaTeX.arc-mcp: exposes ARC tools to MCP clients and manages background jobs.plugins/arc/skills/arc: agent-facing workflow instructions for domain
building, idea generation, and research calculations.
Who This Is For
Use ARC when you want to:
- Look up reliable paper metadata, references, citers, sections, or equations.
- Summarize a paper from cached ar5iv/INSPIRE data.
- Build a research-domain overview from a seed paper.
- Generate ideas using domain context and reviewer scoring.
- Plan and execute a careful symbolic or numerical research calculation with
explicit provenance and checks.
Deterministic paper queries do not need an LLM. Paper summaries, domain
briefings, idea loops, and calculation workflow runners need a host LLM
provider.
Install
Remarks:
-
Permission: the same as many heavy skills/plugins, ARC will need permissions to run Python scripts. Accepting permissions could be annoying. We recommend installing ARC within docker or a virtual machine, and allow all permissions in that virtual environment. As always for working with AI agents, be aware of risk to your data and system.
-
Token usage. As measured using Claude + DeepSeek, a typical run of domain build + idea generation consumes about 1M uncached input tokens, and 0.5M output tokens, in about an hour's running time. The token usage may vary depending on the specific tasks and LLM used. Be aware of token usage and costs.
-
If ARC has played a role in your research, please consider citing the ARC manual: ARC: An LLM-Native Agent Workflow for Theoretical Physics Research, Yanjiao Ma, Yi Wang, Xingkai Zhang (to appear).
Requirements:
- Python 3.11 or newer.
uv for first-time plugin MCP runtime setup.- Network access for first-time INSPIRE/ar5iv fetches.
- Codex or Claude Code for host LLM work; unknown hosts fall back to manual
prompt handoff.
- Optional for
arc-typeset md2pdf: pandoc, xelatex, and a CJK-capable
font such as Noto Sans CJK SC.
Agent Plugin Setup
ARC can be installed as a host plugin from this repository. plugins/arc/ is
the plugin root for both Codex and Claude Code, and
plugins/arc/skills/arc/ is the single canonical skill source.
Install for Codex (run in shell, or in Codex with ! prefix):
codex plugin marketplace add tririver/arc --ref stable
codex plugin add arc@arc
Install for Claude Code (run in Claude Code):
/plugin marketplace add tririver/arc@stable
/plugin install arc
The plugin starts the ARC MCP server with a bundled launcher:
./bin/arc-mcp
On first MCP or CLI use, the launcher installs ARC into a cache-local runtime
and reuses it for later MCP calls and plugin CLI shims. After install.ok
exists, the launcher directly execs the cached runtime command; later MCP starts
do not need uv, pip, or other installer tools. The plugin exposes
arc-paper, arc-domain, arc-llm, arc-typeset, and arc-mcp from
plugins/arc/bin/; the Python packages are installed inside the private
runtime, so pip show arc-paper in the host shell is not expected to find them.
First install uses uv when available and falls back to python3 -m venv plus
pip when uv is not on the MCP process PATH.
If that install fails, later starts fail fast with the saved log path and a
short log tail instead of retrying a broken partial install. To retry after
fixing the cause, set ARC_MCP_INSTALL_RETRY=1 or remove the failure marker
named in the error. Marketplace installs fetch ARC packages from
https://github.com/tririver/arc.git; ARC_MCP_INSTALL_REF overrides the ref,
otherwise the launcher uses a packaged install ref or Claude Code's installed
plugin gitCommitSha when available, then falls back to main. Source checkouts
use local packages/ automatically. For a plugin copy that should install from a
separate local checkout, set ARC_MCP_REPO_ROOT to that checkout root and
ARC_MCP_INSTALL_SOURCE=local.
Check the launcher directly from a source checkout:
