superscientist

Superscientist

Autonomous physics-based computational science — the AI scientist that runs the simulations, not just the literature.

Most agentic research tools stop at reading papers or tuning neural networks. Superscientist closes the loop on physics-based modeling: a Claude Code harness that designs experiments with you, submits jobs to local or HPC backends, polls them across sessions, verifies the outputs, and resumes after crashes — autonomously, until the workflow completes.

How it works

                      ┌─────────────────────────────────────┐
                      │   run-workflow.sh — session loop    │
                      │   resumes until workflow completes  │
                      └──────────────┬──────────────────────┘
                                     │
   ┌─────────┐   ┌────────┐   ┌────────────┐   ┌────────┐   ┌──────────┐
   │ Design  │──▶│  Plan  │──▶│  Execute   │──▶│ Verify │──▶│ Complete │
   └─────────┘   └────────┘   └────────────┘   └────────┘   └──────────┘
        │            │              │              │             │
        ▼            ▼              ▼              ▼             ▼
   experiment-  workflow-     executing-      result-       workflow-
   design       planning      workflows  +    verification  completion
                              compute-backend

   ┌─────────────────────────────────────────────────────────────────┐
   │  Checkpoint files (survive crashes, enable resumption):         │
   │  workflow-state.json  ·  progress.log  ·  init.sh               │
   └─────────────────────────────────────────────────────────────────┘

Every workflow runs through five phases. Three checkpoint files persist state across sessions, so any new Claude session can recover full context and continue — and run-workflow.sh chains sessions automatically until the workflow finishes.

Compute backends

Backend	Type	Dispatch	Typical use
local (Shell)	Local	Sync (≤2 min) / async (longer)	Quick tests, structure prep, lightweight analysis
slurm	HPC scheduler	Async via tmux + DPDISP_DONE marker	Academic clusters

Both backends share one code path through DPDispatcher — the same stage subagent runs whether you target your laptop or a cluster. Async jobs launch in a tmux session and signal completion with a DPDISP_DONE marker file, so the orchestrator can poll without holding context.

Skills

Ten skills cover the full workflow. Subagents invoke them automatically — you don't call them directly.

Group	Skill	Purpose
Bootstrap	using-superscientist	Session-start awareness
Bootstrap	session-resume	Recover full context from checkpoint files on a fresh session
Design	experiment-design	Collaborative dialogue to define the experiment
Planning	workflow-planning	Convert the approved design into staged execution plan
Execution	executing-workflows	Sequential subagent dispatch, one stage at a time
Execution	compute-backend	Submit jobs to local or HPC backends via DPDispatcher
Quality	result-verification	Verify each stage's outputs against success criteria
Quality	systematic-debugging	Root-cause investigation when a stage fails
State	checkpoint-management	Read/write the three-file state system
Completion	workflow-completion	Summary report, archive, commit

Run until done — run-workflow.sh

Workflows often span hours or days; Claude sessions are bounded. run-workflow.sh is a thin shell wrapper that launches claude -p "Invoke session-resume" in a loop and exits only when the workflow's state file reports completed, blocked, or error.

./run-workflow.sh /path/to/workflow-dir

Built-in safeguards:

• Max-session cap (default 20) — prevents runaway loops
• Per-session timeout (default 2h)
• Rapid-failure detection — halts after 3 consecutive sessions under 60s that made no progress
• Pause gate — touch PAUSE in the workflow dir to suspend without killing