Projtool

Status: M0–M5 complete, plus the post-M5 v3→v4 container-layout refactor. 34 MCP tools shipped; ~1970 unit + ~110 integration tests. The full MNIST workflow (retrofit → experiment → train → report → image build) runs end to end. See docs/development/M1-M5-roadmap.md for milestone detail.

projtool is a Python package + Claude Code MCP server that supports a single ML researcher running experiments across a local development machine and remote AutoDL GPU containers.

A retrofitted project lives under a single container directory (v4 layout):

• <container>/code/main/ — the git repo holding model code. Each experiment gets an exp/<topic> branch in a sibling worktree under <container>/code/.
• <container>/output/ — training products (metrics, figures, manifests). Synced from the remote via mutagen, large binary artifacts filtered out.
• <container>/docs/ — an independent git repository holding analysis reports, organized by code-repo branch namespace; cross-branch summaries go in summary/.
• <container>/data/ — datasets (may be a symlink to a NAS path).

Day zero: the user runs projtool setup once. From then on, every action goes through mcp__projtool__* tool calls in Claude Code: experiment creation, training launch, run polling, report writing, AutoDL instance lifecycle, and project-image builds.

Documentation

• docs/product-spec.md — what projtool is, design decisions, scope.
• docs/workflow.md — the workflow this tool exists to automate.
• docs/architecture.md — implementation design.
• docs/handbook.md — development handbook, conventions, anti-patterns.
• docs/development/M1-M5-roadmap.md — milestone breakdown.
• docs/development/retrofit-design.md — M3 detailed design.
• docs/development/autodl-module-plan.md — M0 detailed design.
• docs/development/v3-to-v4-changelog.md — the v3→v4 container-layout refactor.

Project structure

src/projtool/
├── assets/            # data shipped to user projects (templates, skills, hooks)
├── setup_cli.py       # `projtool setup` entry point
├── project_layout.py  # ProjectLayout — single source of truth for container paths (v4)
├── project_config.py  # .proj-tool/project.toml reader/writer
├── state.py           # state.json + shared pydantic schemas
├── errors.py          # ProjtoolError hierarchy
├── mcp/               # MCP server + 34 tool handlers (mcp/tools/), manifest + report templates
├── retrofit/          # detect + write_template + check/apply upgrade
├── autodl/            # AutoDL API client + instance lifecycle
├── git_ops/           # subprocess wrappers for git, worktrees, docs repo
├── mutagen/           # subprocess wrappers for mutagen code/output/data sync sessions
├── ssh/               # subprocess wrappers for ssh / remote exec
└── diagnose/          # health-check helpers (stale-state detection)

The assets/ tree is data, not code. It gets packaged with the wheel and read at runtime via importlib.resources, then copied into user projects during retrofit. See CLAUDE.md for the asset/code boundary.

Development

Requires Python 3.11+.

git clone <this-repo>
cd projtool
python -m venv .venv
source .venv/bin/activate                   # Linux/macOS
# .venv\Scripts\activate                    # Windows
pip install -e ".[dev]"
pytest

Status

Milestone	Scope	Status
M0	autodl/ subpackage	✅ Done — see examples/m0_demo.py
M1	setup CLI + MCP server skeleton + instance lifecycle	✅ Done
M2	start_training + manifest + sync tools	✅ Done
M3	retrofit (detect + write_template + check/apply upgrade)	✅ Done
M4	reports + worktree management (new_experiment, start_report, commit_report)	✅ Done
M5	image build + remote exec + full MNIST e2e	✅ Done
post-M5	v3 → v4 container-layout refactor (template_version 0.5.0+)	✅ Done

See docs/development/M1-M5-roadmap.md for what each milestone covers.

License

MIT.