Get Physics Done (GPD): an agentic physics workflow for Claude Code, Codex and OpenCode

What problem GPD is trying to solve, and for whom

A physics research question rarely fails because the model cannot write equations. It fails because the path from question to defensible result is unstructured: scope drifts, derivations go unverified, and the output is a chat log rather than something citable. GPD's stated purpose is to turn a research question into a structured workflow that scopes the problem, plans the work, derives results, verifies them, and packages the output. The README frames the audience directly: built by physicists, for physicists, released as a community contribution by Physical Superintelligence PBC.

The narrower answer is that GPD is for people who already use an agentic coding runtime. It is not a chatbot and not a notebook replacement. If you do not have Claude Code, Codex, Gemini CLI, GitHub Copilot CLI or OpenCode installed, there is nothing for GPD to attach to, and the README says so plainly: GPD is not a standalone app.

How GPD hooks into a runtime instead of running its own agent

The repository layout makes the architecture legible. There is a Node bootstrap in bin/install.js, a Python package under src/gpd/, an adapters directory containing runtime_catalog.json and runtime_catalog_schema.json, and a core directory with public_surface_contract.json and a matching schema. That is a two-language split: Node handles installation and runtime detection, Python handles the actual research machinery.

The adapters layer is the interesting part. Rather than shipping one agent loop, GPD describes each supported runtime in a catalog and adapts its commands to that runtime's conventions. The public surface contract suggests the set of commands exposed to the host runtime is itself declared and validated against a schema, which is a reasonable way to keep five different hosts from drifting apart. The cost is that GPD's capabilities are bounded by what each runtime exposes. When a runtime changes its command format, the adapter is what breaks, and the fix lands in this repository rather than upstream.

The Python dependency list is modest and mostly about presentation and structure: typer for the CLI, rich for terminal output, pydantic for validation, PyYAML, mcp for the Model Context Protocol, plus pybtex, Pillow and jinja2. Optional extras exist for paper handling (cairosvg, pypdf) and for arXiv work (arxiv-mcp-server, arxiv, httpx). Notably, the arXiv extra pins arxiv>=2.4.1 explicitly even though arxiv-mcp-server already depends on it, and a comment in pyproject.toml explains why: to avoid a transitive resolution silently dropping to a known-broken older version. That is a small detail, but it tells you the maintainers have been bitten by dependency drift.

Installing GPD and running your first research task

The README gives a single bootstrap command for the system terminal. It requires Node.js, and package.json sets engines.node to >=20.

# Requires Node.js.
npx -y get-physics-done

Running that should install GPD's physics-research commands into whichever supported runtime it finds. The README warns that the project is not a standalone app, so expect the install to modify your runtime's command surface rather than produce a new binary you launch on its own.

The Python side requires 3.11 or newer, and pyproject.toml declares support for 3.11, 3.12 and 3.13. The optional paper and arXiv dependencies are declared as extras in pyproject.toml under the names paper and arxiv, so they are installed separately from the base package rather than pulled in automatically.

The README also documents a source-checkout path for people developing the repository itself, rather than installing the published bootstrap package. The exact command sequence for that path is not reproduced here, so treat the npx route as the documented one and read the full README section if you intend to work from a clone.

The verification step is where GPD's design gets opinionated

The five-stage description in the README (scope, plan, derive, verify, package) puts verification before packaging, which is the ordering that matters. Most agentic research tooling stops at generation and leaves validation to the human. GPD's claim is that verification is a named stage in the workflow.

What the README does not describe is the mechanism. There is no explanation of what verification means in practice: whether it re-derives a result by a second route, checks dimensional consistency, cross-references a source, or simply asks a second model to review the first. The public_surface_contract.json file may define this, but its contents are not part of what the README shows. Until you read that file or the docs directory, treat verification as a declared stage rather than a demonstrated guarantee. That distinction matters if you plan to cite GPD-assisted output in a paper.

Where GPD is the wrong tool

Two limitations stand out from the repository itself.

First, the runtime dependency is total. GPD installs into a host; it does not replace one. If your institution blocks third-party CLI agents, or if you work in an environment where the only approved interface is a browser, GPD has no path to you. Five supported runtimes is broad coverage, but it is coverage of a specific category of tool.

Second, the licence metadata is inconsistent. GitHub reports the licence as NOASSERTION, while package.json declares Apache-2.0 and pyproject.toml carries the Apache Software License classifier plus a license file reference. The LICENSE file in the repository root is the authoritative artifact, and the badge in the README also says Apache 2.0. The mismatch is likely a detection artifact rather than a real dispute, but if you are adopting this inside a company with licence scanning, expect the scanner to flag it and be ready to point at the LICENSE file.

A third, softer limitation: the project is a workflow scaffold. If your research is exploratory in a way that resists a five-stage pipeline, the structure may cost you more than it returns.

GPD against a general-purpose coding agent used directly

The obvious alternative is to open Claude Code, Codex or Gemini CLI and just ask your physics question. That is genuinely cheaper to start: no install, no adapter layer, no new command surface to learn.

The difference is in what gets carried between steps. A coding agent holds context in a conversation; GPD's premise is that the research process has named stages with defined handoffs, and that the output of the derive stage is a distinct artifact from the output of the verify stage. Whether that structure helps depends on whether your work is long enough to lose the thread. For a one-off calculation, the raw agent wins. For a multi-week derivation with a paper at the end, the argument for a declared pipeline is stronger.

GPD also adds domain-specific optional dependencies (pybtex for bibliography handling, arXiv tooling, PDF and SVG rendering) that a generic coding agent has no reason to bundle. Those extras are where the physics-specific value sits, and they are opt-in.

Maintenance, versioning and what an upgrade costs you

The last push to the repository was on 2026-07-23, and the most recent release listed is v1.2.2 from 2026-05-07, preceded by v1.2.1 and v1.2.0 in late April 2026. The repository is not archived.

Versioning is kept in lockstep across three files: package.json reports version 1.2.2 and a separate gpdPythonVersion field also set to 1.2.2, and pyproject.toml reports 1.2.2. That is a deliberate choice to keep the Node bootstrap and the Python package aligned, and it removes a class of "which half is stale" bugs. It also means an upgrade touches both halves at once, so a partial upgrade is not a supported state.

The practical upgrade cost is the adapter surface. GPD sits between your runtime and your research, so a runtime update that changes command conventions may require a GPD release before your workflow works again. Pinning a known-good GPD version alongside a known-good runtime version is the conservative approach; the README does not document a rollback procedure, so plan your own.

On licensing: the repository ships a LICENSE file and a CLA directory, and both package manifests declare Apache-2.0. Apache-2.0 includes an explicit patent grant, which is generally friendlier for commercial and institutional adoption than a bare permissive licence, but the NOASSERTION label on GitHub means automated compliance tooling may not resolve it cleanly. This is not legal advice; check the LICENSE file yourself.

Editorial conclusion

Adopt GPD if you already work inside one of the supported runtimes and want a repeatable path from research question to verified result; skip it if you need a self-contained application or a GUI. Before committing, check the LICENSE file, since the repository metadata reports NOASSERTION while package.json and pyproject.toml both declare Apache-2.0, and confirm that your installed runtime is one the runtime_catalog.json actually lists.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. psi-oss/get-physics-done on GitHub
4. README
5. Releases