GitHub - psi-oss/get-physics-done: The first open-source agentic AI physicist, by Physical Superintelligence PBC (PSI).

Built by physicists, for physicists

Get Physics Done is an open-source AI copilot for physics research from Physical Superintelligence PBC (PSI), released as a community contribution. GPD helps turn a research question into a structured workflow: scope the problem, plan the work, derive results, verify them, and package the output.

Quick Start · Supported Runtimes · Workflow · Commands · Models · Advanced CLI · System Requirements

Who This Is For

GPD is for hard physics research problems that cannot be handled reliably with manual prompting.

It is designed for long-horizon projects that require rigorous verification, structured research memory, multi-step analytical work, complex numerical studies, and manuscript writing or review.

We welcome contributions and feedback via GitHub issues or pull requests; if GPD is useful in your work, please star the repo, and share it with colleagues who might benefit.

Quick Start

Install GPD:

Next steps after install

The installer adds GPD to your runtime config, but it does not launch the runtime for you.

1. Open your chosen runtime from your normal system terminal (claude for Claude Code, gemini for Gemini CLI, codex for Codex, opencode for OpenCode).
2. Run its help command first: Claude Code / Gemini CLI use /gpd:help, Codex uses $gpd-help, and OpenCode uses /gpd-help.
3. Start with new-project for a fresh research project or map-research for an existing folder or project.

For best performance, run both this install step and your chosen runtime from your normal system terminal, not inside the VS Code, Cursor, or other AI runtime command/chat interface.

Then choose the path that matches your starting point:

Use the runtime-specific command syntax shown in Supported Runtimes, for example /gpd:settings or /gpd:set-profile review.

If you are starting from existing work, run map-research first to map the formalism, computations, conventions, validation status, and open questions before new-project.

Typical new-project workflow:

new-project -> plan-phase 1 -> execute-phase 1 -> verify-work 1

npx -y github:psi-oss/get-physics-done --upgrade

Supported Runtimes

GPD currently installs into four AI runtimes. To preselect one during install, use the matching npx flag, or use --all to install everything in one pass:

Each runtime uses its own command prefix, but the workflow is the same across all four. After installing GPD, open your chosen runtime normally from your system terminal and use the commands shown above.

Notes:

• Claude Code-specific note: GPD writes .claude/settings.json for hooks and statusline. MCP servers are added to project .mcp.json for local installs or ~/.claude.json for global installs.
• Codex-specific note: GPD writes .codex/config.toml during install, enables features.multi_agent = true, configures the required notify hook and built-in MCP servers, registers GPD agent roles in [agents.*], and for local installs exposes only public gpd-* agents there as discoverable skills in repo-scoped .agents/skills/; the full agent catalog still installs under .codex/agents/ for direct invocation.
• Codex global skills use CODEX_SKILLS_DIR when set, or ~/.agents/skills/ by default.
• Gemini-specific note: GPD writes .gemini/settings.json during install, enables experimental.enableAgents, configures the required hooks and built-in MCP servers, and installs policies/gpd-auto-edit.toml for Gemini auto-edit shell approvals.
• OpenCode-specific note: GPD writes .opencode/opencode.json for local installs or ~/.config/opencode/opencode.json for global installs, installs flat command/gpd-*.md files, configures built-in MCP servers under the mcp key, and manages GPD-owned permission.read / permission.external_directory entries.

What GPD Does

GPD guides research in four stages:

1. Formulate: asks targeted questions to pin down scope, assumptions, notation, and verification targets.
2. Plan: creates a phased roadmap with concrete tasks, dependencies, and success criteria.
3. Execute: runs specialist agents for derivations, numerical checks, literature work, and writing.
4. Verify: checks dimensional consistency, limiting cases, symmetry constraints, conservation laws, and numerical stability.

Each phase produces real artifacts such as PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, .tex derivations, .py verification scripts, and figures.

GPD also locks conventions for up to 18 physics fields across a project so notation, sign choices, and verification assumptions stay consistent as phases accumulate.

How Work Is Structured

GPD's main workflow in .gpd/ is organized like this:

Project
└── Milestone (v1.0, v1.1, v2.0, ...)
    └── Phase (1, 2, 2.1, 3, ...)
        └── Plan (01-01, 01-02, ...)
            └── Task

During execution, plans are grouped into waves:

Wave 1: plans with no unmet dependencies
Wave 2: plans that depend on wave 1 outputs
Wave 3: plans that depend on earlier waves

• Project: the overall research workspace and its persistent context.
• Milestone: a major research checkpoint such as a paper submission, revision cycle, or result package. One project can have multiple milestones.
• Phase: one coherent chunk of work inside a milestone. Integer phases are planned work; decimal phases like 2.1 are inserted later when urgent work appears.
• Plan: the detailed execution breakdown for a phase, created by the runtime-specific plan-phase N command.
• Wave: not a separate top-level planning object, but the execution order inside a phase. Plans in the same wave can run in parallel; later waves depend on earlier ones.

Phase numbers continue across the whole project, so a new milestone may start at Phase 6 rather than resetting to Phase 1.

Worked Example

/gpd:new-project
> Use crossing symmetry and the numerical conformal bootstrap to bound low-lying operator dimensions in the 3D Ising CFT.

/gpd:plan-phase 1
/gpd:execute-phase 1
/gpd:verify-work 1

/gpd:write-paper "3D Ising bootstrap bounds"
/gpd:arxiv-submission
/gpd:peer-review
/gpd:respond-to-referees

Key In-Runtime Commands

These commands run inside your installed AI runtime after GPD has been installed there. The examples below use Claude Code / Gemini CLI syntax.

Common Starting Points

Typical research loop: /gpd:new-project -> /gpd:plan-phase -> /gpd:execute-phase -> /gpd:verify-work -> repeat -> /gpd:complete-milestone

Typical publication loop: /gpd:write-paper -> /gpd:peer-review -> /gpd:respond-to-referees -> /gpd:arxiv-submission

Command Context

Not every GPD command needs the same amount of project state.

Passing a manuscript path to a project-required command such as /gpd:peer-review paper/ selects the manuscript target, but does not bypass project initialization.

The full command reference below uses Claude Code / Gemini CLI syntax. Codex uses $gpd-... and OpenCode uses /gpd-....

Optional: Model Profiles And Tier Overrides

GPD maps runtime-specific model names onto three capability tiers. Most users can leave this at the runtime default and only adjust it if they want to tune planning, execution, or verification behavior.

Available profiles are deep-theory, numerical, exploratory, review, and paper-writing.

{
  "model_profile": "review",
  "model_overrides": {
    "codex": {
      "tier-1": "your-tier-1-codex-model",
      "tier-2": "your-tier-2-codex-model",
      "tier-3": "your-tier-3-codex-model"
    },
    "claude-code": {
      "tier-1": "opus",
      "tier-2": "sonnet",
      "tier-3": "haiku"
    },
    "gemini": {
      "tier-1": "your-tier-1-gemini-model",
      "tier-2": "your-tier-2-gemini-model",
      "tier-3": "your-tier-3-gemini-model"
    }
  }
}

Advanced CLI Utilities

The gpd CLI also includes machine-readable validation, observability, and tracing commands for automation, review-grade checks, and debugging.

System Requirements

• Node.js with npm/npx
• Python 3.11+ with the standard venv module (install a newer version with brew install python@3.13 on macOS, pyenv install 3.13 on Linux, or from python.org on Windows)
• Network access to npm and GitHub for the bootstrap installer
• One of: Claude Code, Gemini CLI, Codex, or OpenCode
• API access for the model provider used by your selected runtime

Known Limitations

• Runtime-internal tool and subagent detail is limited by what the active provider/runtime exposes. GPD records the workflow, session, and trace events it can emit locally, but it does not fabricate opaque provider internals.

Uninstall

Run npx -y get-physics-done --uninstall for interactive uninstall. The equivalent subcommand form npx -y get-physics-done uninstall also works, and you can add the runtime and scope flags above for a non-interactive uninstall.

Uninstall removes GPD from the selected runtime config only. It does not delete project .gpd/ artifacts or shared files under ~/.gpd; remove ~/.gpd/ manually, or GPD_HOME if you used it, for a full wipe after uninstalling from all runtimes.

Inspiration

GPD takes its name in explicit analogy with GSD (Get Shit Done), whose adoption demonstrates how AI-native command workflows can be genuinely useful. GPD takes inspiration from that system to build a sophisticated prompt-engineered agentic system specifically designed for physics research.

Citation

If GPD contributes to published research, please cite the software using CITATION.cff. Copy-ready formats:

@software{physical_superintelligence_2026_gpd,
  author = {{Physical Superintelligence PBC}},
  title = {Get Physics Done (GPD)},
  version = {1.1.0},
  year = {2026},
  url = {https://github.com/psi-oss/get-physics-done},
  license = {Apache-2.0}
}

Physical Superintelligence PBC (2026). Get Physics Done (GPD) (Version 1.1.0). https://github.com/psi-oss/get-physics-done

License

GPD is released under the Apache License 2.0. See LICENSE.