Mechanist plugin
A Claude Code plugin that runs research on language model internals: papers, hypotheses, experiments, verification, a report
- 79 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Agents write and run experiment code on your machine and GPUs on their own until you stop the pipeline
- Hypothesis, plan and result texts go to the external reviewer model under your API key and spend paid tokens
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/mechanistDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Agents write and run experiment code on your machine and GPUs on their own until you stop the pipeline
- Hypothesis, plan and result texts go to the external reviewer model under your API key and spend paid tokens
This is third-party code. Review the repository files before installing.
What it does
Mechanist is a Claude Code plugin for large language model interpretability. You pose a research question and the plugin turns it into verifiable findings. Four stages run in order, each driven by a separate subagent: claim, experiment, verify and iteration. It searches the literature, formulates hypotheses with a novelty check, writes and runs experiment code on your machine and GPUs and checks robustness across other models, datasets and methods. At every step an external reviewer model outside the Claude series cross-checks the result, with up to six iteration rounds. All claims go into the `CLAIMS_LEDGER.md` ledger and the outcome is assembled in `AUTO_PIPELINE_REPORT.md`. The entry point is the `/mguide` command: it clarifies the task and writes `task.md`.
Who it is for. AI interpretability researchers, graduate students and labs that want to automate the loop from idea to a verified result on their own GPUs.
Good fit when
- You look for the internal model component responsible for a known behavior
- You need to reproduce a paper, for example on separate encoding of harmfulness and refusal
- You have an unconfirmed hypothesis to test across several models and datasets
- You search the 14k-paper interpretability corpus for literature on a topic
- You want to see how a field developed: key papers, turning points and open problems
Not a fit when
- You cannot send experiment texts to an external reviewer model over an API
- You have no GPUs or Python environment for experiments: the plugin runs code locally
- The task is not about model mechanisms: the pipeline is built for interpretability
- You want Claude as the reviewer: the README requires a model from another series
Example request
/mguide Reproduce this paper: LLMs encode harmfulness and refusal separatelyLimitations
The plugin runs inside Claude Code and uses `uv` for temporary environments of its `llm-chat` and `mechanic-db` MCP servers. The reviewer needs the `LLM_API_KEY` variable, with `gpt-5.4` and `https://api.openai.com/v1` as defaults, and a compatible service can be substituted: Azure, DeepSeek, Qwen or a proxy. A Claude-series model must not be used for this role. Variables are read at Claude Code start, so the client is restarted after editing `~/.bashrc`. Experiments run in the Python environment the session started in, and PyTorch and NumPy are installed separately if needed. Codex support is announced as coming.
How to disable. Remove the plugin through `/plugin` and delete `LLM_API_KEY`, `LLM_MODEL` and `LLM_BASE_URL` from your shell startup file. The working folder with `CLAIMS_LEDGER.md` and reports is separate and deleted by hand.
FAQ
How do I install Mechanist in Claude Code?
In a session run `/plugin marketplace add zjunlp/Mechanist` and `/plugin install mechanist@mechanist`, then `/reload-plugins`. `/mcp` should show `llm-chat` and `mechanic-db` as connected. If commands are missing, restart the client.
Why an external reviewer?
So the same model does not grade itself: a second model cross-checks ideas, plans and conclusions at every stage. GPT-5.4 on an OpenAI key fits, and Claude must not be used for the role.
What does `/mguide` do?
It is the plugin entry point. It works out the task with you, writes `task.md` and starts the pipeline once you confirm. It also searches literature and builds a field timeline with no experiments.
Where do I follow the research?
Each stage writes documents to disk: `idea-stage/IDEA_REPORT.md`, `refine-logs/FINAL_PROPOSAL.md`, `refine-logs/EXPERIMENT_PLAN.md`, with the outcome in `CLAIMS_LEDGER.md` and `AUTO_PIPELINE_REPORT.md`.
Do I need PyTorch and GPUs?
Experiments run in the Python environment the session started in, on your machine. The README gives a conda environment example `scientist` and `pip install -r requirements.txt` for PyTorch, NumPy and scikit-learn.
Discussion
No questions or reviews yet.
Related
PluginsGrainulator keeps an evidence ledger for research and engineering work and checks a model answer for conflicts and gaps.
A Claude Code plugin that makes the model finish the job: result verification, evidence and systematic investigation enforced as procedure
A Claude Code plugin with hooks and 26 skills: measures what the agent knows, blocks edits until code is read, keeps memory
A Claude Code plugin for autonomous research: from a topic to ideas, proposals and running experiments in closed agent loops.
A Claude Code plugin where the main model plans and signs off while search, edits and verification go to roles running on cheaper models
A Claude Code plugin that hands coding tasks to Codex agents, monitors them and verifies the results independently
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Mechanist (this card) | no | 79 | |
| Autoresearch for skills | no | 982 | a loop of autonomous experiments improving code; Mechanist runs research on model mechanisms with claim verification |
| Research Agent Skills | no | 124 | general research skills; here a narrow interpretability pipeline with an external reviewer |
README in short
The README presents Mechanist as an autonomous research agent for interpretability and describes a four-stage pipeline with a claim ledger. It then covers installing Claude Code, uv and the plugin, configuring the external reviewer model, a quick start with `/mguide` and the output documents.