GPD's npm package is six files and a shim, not the system it installs

GPD installs into someone else's runtime, so two surfaces have to work

GPD is not a standalone app. It installs physics-research commands into Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, or OpenCode, which means the system you end up with spans two places you type commands.

The normal system terminal handles installs, local gpd diagnostics, and runtime launchers such as claude, gemini, codex, opencode, and gh copilot. The opened runtime handles the installed command ladder itself. That split is not cosmetic: an install can leave one surface working and the other broken, so success is defined as two separate checks. gpd --help has to work in your terminal, and the runtime-specific GPD help command has to work inside the runtime.

For a tool sold as a research assistant, that is the load-bearing fact about the architecture. There is no GPD process to supervise, no port to bind, no service to keep alive. What gets supervised is an assistant that happens to have GPD's commands installed into it.

The same first command has three different spellings, one per runtime

The entry point differs by runtime in a way that is easy to get wrong. Claude Code and Gemini CLI use /gpd:help. Codex uses $gpd-help. GitHub Copilot CLI and OpenCode use /gpd-help.

Three different invocations for one command, differing in both the sigil and the hyphenation, and the runtime prefixes apply to the rest of the ladder as well: start, tour, new-project, map-research, and resume-work all need the prefix your runtime expects. The command names in the documentation are canonical names without prefixes, so anyone reading a snippet has to add one.

The badge block at the top of the README repeats the same target four times in a row, each link pointing at the supported-runtimes anchor. Whatever produced those links treats the runtime list as four separate entries that happen to share a destination. Harmless when it renders, but it is a signal that the runtime list is assembled rather than written once, and the prefix table is the place where an assembled list would drift.

The startup ladder is a fixed order, and the new-work choice is one-way

The canonical post-install order is a ladder: help, then start, then tour, then new-project or map-research, then resume-work. The fast path says to run the help command first, then branch on what you are looking at: start if you are unsure what fits the folder, tour for a read-only walkthrough, new-project --minimal for new work, map-research for existing work, resume-work when you come back later.

The one rule the documentation is firm about is that new work and existing work are distinct choices. Pick one, then follow it through. That is an instruction about not mixing two project states in one folder, and it is the kind of thing that is cheap to respect on day one and expensive to untangle later.

The starting point table that maps situations to commands is cut off partway through. Its last visible row is the new research project entry, and the command cell stops after the letters new. The rows for the situations after it are not visible, so the branch list above comes from the fast path text, which is complete.

The installer needs Node, Python and a runtime, and supplies none of the first two

The bootstrap installer requires three things: Node.js 20 or newer, Python 3.11 or newer with venv, and one supported runtime, which is claude, gemini, codex, gh copilot, or opencode. None of the first two is installed for you, and the onboarding material states the point plainly: GPD does not install your runtime and does not provide model access, billing, or API credits.

That puts the cost of adoption on the machine, not the package. Node comes from the system package manager or from a manual install, and on Linux the guidance adds a version check: distribution nodejs and npm packages are useful only if node --version reports v20 or newer.

Two further dependencies sit behind the first command. Model access is whatever your runtime and its own account arrangement already give you, so the token and billing decisions stay where they are. And the documentation carries a models section with optional model profiles and tier overrides plus a system requirements section, which means the profile and budget choices are configuration rather than defaults.

A source checkout resolves from uv, and the published installer stays out of reach on purpose

Installing the published bootstrap package is one command:

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

Developing the repository itself is a different path, and the documentation is explicit that it is a different resolution root:

uv sync --dev
uv run gpd --help

The reason given is that uv resolves the environment from pyproject.toml and uv.lock, and after uv sync --dev you can source .venv/bin/activate and run gpd directly if you prefer an activated shell. The important detail is what comes next: to exercise the public installer flow from a source checkout, you are told to go back to the matching npx -y get-physics-done bootstrap command.

So the environment where you develop and the environment where the installer is tested are separate by design. That is a sensible boundary, since one resolves from a lock file and the other resolves from the registry, but it means a green development run is not evidence about the install path.

The npm artifact is six files, one bin shim, and a second version field

The published package is smaller than the name suggests. package.json declares version 1.2.2, engines node >=20, and a single binary named get-physics-done that points at bin/install.js. Its files list has six entries: bin/install.js, src/gpd/bootstrap/installer_metadata.json, src/gpd/adapters/runtime_catalog.json, src/gpd/adapters/runtime_catalog_schema.json, src/gpd/core/public_surface_contract_schema.json, and src/gpd/core/public_surface_contract.json.

Every entry after the shim is data or a schema. The runtime catalog and its schema, plus a public surface contract and its schema, mean the set of runtime adapters and the set of commands GPD exposes are declared as files that can be validated rather than hard-coded in the installer. That is how five runtimes stay consistent without the shim knowing about each of them.

There is also a second version field, gpdPythonVersion, set to 1.2.2 to match. Two version numbers that have to be kept in step across two language ecosystems is the detail to watch when a release lands: the npm side and the Python side are versioned separately, and the bootstrap that joins them carries both.

Optional extras pin transitive floors the comments say are unsafe to inherit

The core dependencies are typer, rich, pydantic, PyYAML, and mcp, with pybtex, Pillow, and jinja2 as utilities. Everything domain-specific sits in optional groups, and the two visible ones are shaped by entrypoints rather than by library taste.

The paper group adds cairosvg and pypdf. The arxiv group adds arxiv-mcp-server with pdf extras, arxiv, httpx, cairosvg, and pypdf, and its comments explain each floor. arxiv already arrives transitively, because the server's tools/search.py and tools/download.py import it directly, and the GPD bridge itself does not import it. The tighter floor is declared anyway so a transitive bump cannot silently fall back to a known-broken older version. httpx is declared for the same class of reason: the OpenAlex translator and the GCS PDF fetcher use it directly, so the gpd-mcp-arxiv entrypoint should not depend on a transitive resolve to find it.

That is a package describing its own failure history. Both floors exist because something broke when a transitive dependency moved, and the entrypoint naming tells you the runtime surface is wider than the CLI.

Python classifiers stop at 3.13, and the license is declared in three places

pyproject.toml sets requires-python to 3.11 or newer, and the classifier list names 3.11, 3.12, and 3.13. There is no 3.14 entry, so a 3.14 interpreter satisfies the resolver while no classifier claims it. The floor and the declared support are two different numbers, and the gap only becomes visible when someone runs a newer interpreter than the project has listed.

The license has its own spread. package.json declares Apache-2.0, the Python side uses the file form that points at the LICENSE file in the repository root, and a classifier names the Apache Software License. The repository's own license field, meanwhile, reports no assertion, so the license is declared three consistent ways inside the project and one non-committal way outside it. Nothing in the tree suggests a second license, and the README links to the same LICENSE file.

For a research tool the practical reading is: the code terms are settled, and the Python version support statement is one release behind the floor.

Editorial conclusion

GPD is a reasonable fit for a physics group already inside one of the supported AI runtimes and willing to supervise each turn, since the value it adds is structure and verification rather than a new interface. Before installing, confirm four things: that your runtime prefix matches the one you will type, that Node reports v20 or newer and Python 3.11 or newer with venv, which optional extra group you actually need, and how the Python side resolves when the npm version and gpdPythonVersion drift apart. Teams wanting a self-contained application, bundled model access, or a classifier-backed statement of Python 3.14 support should wait.

Frequently asked questions

Official sources

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