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. ```