Practical overview
When it fits
Use Mechanist when a question about an LLM's internal mechanisms needs a coordinated path from literature and hypotheses through experiments and robustness checks. Its documented workflow begins with /mguide in a Claude Code working directory.
Who it is for
- Researchers studying mechanistic interpretability of large language models
- Researchers who want to explore a model behavior, reproduce a paper, test a suspected phenomenon or pursue open-ended discovery
Documented uses
- Search interpretability literature and web sources for a research question
- Formulate or capture a hypothesis and produce an experiment plan
- Generate and run experiments to investigate an LLM mechanism
- Check findings across different models, datasets and methods
- Track claims and refine conclusions through external review
Requirements & limits
The project is publicly available on GitHub under the MIT license. It runs as a Claude Code plugin and requires an external model API key for review.
- The primary interface is the Claude Code CLI, not a standalone research application.
- External model review is required and must use a non-Claude-series model, according to the README.
- The project lists Python 3.11 or later and uses uv to manage Python environments for its MCP servers.
- Experiment execution uses the user's own machine and GPU resources, according to the README.
- The README recommends an Opus-series Claude model for the pipeline.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Set up Mechanist in Claude Code
Install the plugin and configure the external model review connection.
Before you start
- Claude Code CLI
- uv for the MCP server Python environments
- An API key for an external review model; the README says not to use a Claude-series model for this role
Steps
Install Claude Code CLI and uv, then check their versions.
In a Claude Code session, add the zjunlp/Mechanist marketplace and install mechanist@mechanist.
Reload plugins and check that the listed Mechanist commands appear and the llm-chat and mechanic-db MCP servers report connected.
Set LLM_API_KEY and, if needed, LLM_MODEL and LLM_BASE_URL in your shell configuration.
Expected outcome
The Mechanist plugin is installed and its MCP services can connect, with external model review configured.
Guide limitations
- This covers installation and configuration, not running a research task.
- The external reviewer must be independent of Claude; the README specifically says not to use a Claude-series model.
- The README describes experiment Python environment preparation as optional at this setup stage.
Start a Mechanist research task
Prepare a task specification and initiate the documented autonomous research workflow.
Before you start
- Mechanist installed in Claude Code
- A working directory for the research task
- An external review model configured
- An Opus-series Claude model is recommended by the README
Steps
Create a working directory and start Claude Code from its root.
Enter /mguide followed by a plain-language research question or task.
Work with the guide to refine the requirements into task.md.
Review and confirm the task specification to start the pipeline.
Expected outcome
Mechanist begins the claim, experiment, verification and iteration stages; the README identifies CLAIMS_LEDGER.md and AUTO_PIPELINE_REPORT.md as outputs.
Guide limitations
- The README recommends an Opus-series model and warns that weaker models degrade the pipeline.
- Experiments run in the user's environment; the README's setup separately describes preparing a Python environment for them.
- The guide covers starting a run, not guaranteeing a particular research result.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 12 October 2026
- Original website title
- zjunlp/Mechanist · Official homepage title · retained in its source language