projtool

Pre-alpha. Designs are complete; code is not yet implemented. See docs/development/M1-M5-roadmap.md for the milestone plan.

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. The core design is:

• Code repo (this kind of repo) holds the model code on exp/<topic> branches, each with its own git worktree.
• Outputs (training products: metrics, figures, manifests) live on the local filesystem outside the worktrees, under ~/proj-outputs/. Synced from the remote via mutagen, large binary artifacts filtered out.
• Docs repo is an independent git repository at ~/proj-docs/<project>/ that holds analysis reports. Reports are organized by code-repo branch namespace; cross-branch summaries go in summary/.

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.

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.

Project structure

src/projtool/
├── assets/                 # data shipped to user projects (templates, skills, hooks)
├── setup_cli.py            # `projtool setup` entry point (M1)
├── mcp/                    # MCP server + tool handlers (M1+)
├── retrofit/               # detect + write_template + check_upgrade (M3)
├── autodl/                 # AutoDL API client and instance lifecycle (M0)
├── git_ops/                # subprocess wrappers for git + worktrees (M2)
├── exp/                    # experiment / training / manifest logic (M2, M4)
├── reports/                # docs repo operations + cross-repo validation (M4)
├── images/                 # image build orchestration (M5)
└── state.py                # state.json + project.toml schemas

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	minimum installable + MCP server skeleton	⏳
M2	new_experiment + start_training + manifest	⏳
M3	retrofit (detect + write_template + check_upgrade)	⏳
M4	reports (start_report + commit_report)	⏳
M5	image build + production polish	⏳

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

License

MIT (placeholder — set to whatever you prefer before public release).