ml-intern

ML Intern

An ML intern that autonomously researches, writes, and ships good-quality ML code on the Hugging Face ecosystem — papers, datasets, training, evaluation, sandbox-driven development, and HF Jobs orchestration.

This repo ships three frontends on top of the same tools:

1. Claude Code plugin (recommended) — install once, use /ml-intern, /research, /finetune, etc. in any repo.
2. Claude Code project — clone this repo, run claude from the root, get the same experience plus full-fidelity context.
3. Standalone ml-intern CLI — the original, self-contained command-line agent.

All three share the same tool implementations under agent/tools/ (the plugin vendors a slim copy under plugin/lib/ml_intern_lib/).

---

Quick start: Claude Code plugin (recommended)

From any repo, inside Claude Code:

/plugin marketplace add guynachshon/claude-code-ml-intern
/plugin install ml-intern@ml-intern

That's it. Set HF_TOKEN and GITHUB_TOKEN in your shell so the MCP server can use them, then start a session and try:

/ml-intern fine-tune llama-3-8b on HuggingFaceH4/ultrachat_200k
/research best DPO recipe for instruction tuning, 7B-13B range
/inspect-dataset HuggingFaceH4/ultrachat_200k

Full plugin docs (slash commands, approval policy, env knobs, troubleshooting): plugin/README.md.

---

Quick start: Claude Code project

If you want to hack on ml-intern itself or run it as a project (not a plugin), clone the repo and use it as a Claude Code workspace:

git clone [email protected]:guynachshon/claude-code-ml-intern.git
cd claude-code-ml-intern
uv sync
claude

Claude Code picks up:

• CLAUDE.md — persona and methodology (research-first, dataset audit, pre-flight checklist for jobs, error-recovery rules).
• .mcp.json — auto-starts two MCP servers:
  • ml-intern-tools (stdio) — hf_papers, hf_inspect_dataset, hf_jobs, hf_repo_files, hf_repo_git, explore_hf_docs, fetch_hf_docs, github_*, sandbox bash/read/write/edit.
  • hf-mcp-server (HTTP, hosted at huggingface.co/mcp) — official HF tools.
• .claude/agents/research.md — the parallel research subagent (read-only HF tools).
• .claude/commands/*.md — /ml-intern, /research, /inspect-dataset, /finetune, /run-job.
• .claude/hooks/*.py — content-aware approval, session redaction+upload, dynamic context injection.

Full project-mode guide: CLAUDE_CODE_GUIDE.md.

---

Quick start: standalone CLI

The original ml-intern CLI, for use without Claude Code:

git clone [email protected]:guynachshon/claude-code-ml-intern.git
cd claude-code-ml-intern
uv sync
uv tool install -e .

Then ml-intern works from any directory:

ml-intern                                # interactive
ml-intern "fine-tune llama on my dataset"  # headless
ml-intern --model anthropic/claude-opus-4-6 "your prompt"
ml-intern --max-iterations 100 "your prompt"
ml-intern --no-stream "your prompt"

Create a .env in the project root (or export in your shell):

ANTHROPIC_API_KEY=<your-anthropic-api-key>   # if using anthropic models
HF_TOKEN=<your-hugging-face-token>
GITHUB_TOKEN=<github-personal-access-token>

Without HF_TOKEN, the CLI prompts on first launch. To get a GITHUB_TOKEN, follow the GitHub PAT tutorial.

---

Repo layout