# 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`](docs/product-spec.md) — what projtool is, design
  decisions, scope.
- [`docs/workflow.md`](docs/workflow.md) — the workflow this tool exists
  to automate.
- [`docs/architecture.md`](docs/architecture.md) — implementation design.
- [`docs/handbook.md`](docs/handbook.md) — development handbook,
  conventions, anti-patterns.
- [`docs/development/M1-M5-roadmap.md`](docs/development/M1-M5-roadmap.md)
  — milestone breakdown.
- [`docs/development/retrofit-design.md`](docs/development/retrofit-design.md)
  — M3 detailed design.
- [`docs/development/autodl-module-plan.md`](docs/development/autodl-module-plan.md)
  — M0 detailed design.
- [`docs/development/v3-to-v4-changelog.md`](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+.

```sh
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](LICENSE).
```