Commands

Synthetic Scientists provides a single scientist command with subcommands grouped by purpose.

scientist <command> [options]

Run scientist --help for the full command list, or scientist <command> --help for details on any command.

Command groups

Create

• scientist new: Scaffold a new task directory
• scientist check: Check the evaluator against the base source

Configure

• scientist configure: Detect installed agent runtimes and create profiles
• scientist profiles: List, inspect, and verify runtime profiles

Operate

• scientist launch: Start a research session
• scientist continue: Continue a previous session
• scientist halt: Halt active sessions
• scientist overview: Show session health and ranking

Review

• scientist results: List and search experiments (ranking)
• scientist inspect: Show details of a specific experiment
• scientist knowledge: Browse the shared lab notebook
• scientist methods: Browse reusable methods
• scientist work: Coordinate tasks, commits, verification, and synthesis
• scientist sessions: List sessions (active only; --all for halted)

Interface

• scientist dashboard: Launch the live interface

Workspace

• scientist eval: Stage, commit, and evaluate changes
• scientist wait: Block until a submitted eval's score lands
• scientist diff: Show uncommitted changes
• scientist undo: Undo the last commit
• scientist restore: Reset to a previous experiment
• scientist promote: Promote an experiment to a normal git branch
• scientist cadence: View/modify cadence actions

The full reference for every command follows.

Create

scientist new

Create a task directory with a packaged evaluator.

scientist new <path> [--name NAME]

scientist new my-task
scientist new my-task --name "My Task"

Produces a self-contained layout: task.yaml wired to a packaged grader (grader.entrypoint), a baseline seed/solution.py, and a hatchling-built grader/ package at grader/src/<task>_grader/. Run scientist check <path> next to bootstrap the grader venv and dry-run the grader against the seed.

scientist check

Validate task structure and dry-run the grader against seed code.

scientist check <path>

scientist check my-task

Configure

User-level runtime profiles are machine-local presets (runtime, command, model, runtime options, persona seed) stored in ~/.config/scientist/profiles.yaml. Tasks reference them by name with agents.profile instead of repeating runtime details. See the Runtime Profiles guide for the full model. No credentials are ever stored.

scientist configure

Scan PATH for installed agent runtime CLIs (claude, codex, cursor-agent, opencode, kiro-cli, pi) and, in an interactive terminal, launch a numbered-selection wizard to create profiles. Pick one or more runtimes (1, 1,3, 1-3, or all) and the wizard prompts for profile name + model per pick. After each successful profile it asks "Add another profile for X? [y/N]", so one runtime can carry many profiles (e.g. claude-opus and claude-sonnet both targeting claude_code).

scientist configure [--non-interactive] [--config PATH]

scientist configure                       # detect + interactive wizard
scientist configure --non-interactive     # detection report only (good for CI / piped output)

The detection report lists every canonical runtime: ✓ next to the resolved absolute path when the CLI is on PATH, not found otherwise, plus a (N profile) marker for runtimes that already have profiles.

scientist configure profile

Create or update one named runtime profile. Runs interactively when no flags are given; otherwise reads everything from flags.

scientist configure profile [--name NAME] [--runtime RUNTIME] [--command PATH]
                  [--model MODEL] [--persona-file FILE] [--option KEY=VALUE]...
                  [--default] [--non-interactive]

scientist configure profile --name claude-opus --runtime claude_code --model opus
scientist configure profile --name codex-high --runtime codex --option model_reasoning_effort=high

scientist profiles

List, inspect, verify, and delete profiles.

scientist profiles list                       # all profiles (numbered, default marked)
scientist profiles show <name>                # one profile's resolved fields
scientist profiles verify [name]              # validate all profiles (or one)
scientist profiles remove                     # interactive numbered-selection wizard
scientist profiles remove <name> [<name>...]  # delete one or more by name

scientist profiles remove is variadic and interactive: pass any number of profile names to remove them directly (unknown names abort before any deletion happens), or pass none to get a numbered-selection prompt mirroring scientist configure's wizard, then a [y/N] confirmation. Removing the default profile reassigns the default to the next alphabetical entry.

scientist profiles verify runs four checks per profile: (1) the profile resolves to a valid agent spec, (2) the CLI is found, (3) the CLI reports --version, and (4) by default a live hello-ping, spawns the runtime CLI with a one-word prompt and waits for a reply. The live ping costs one LLM round-trip per profile and surfaces auth issues (no API key, expired login) that the cheap checks miss. Pass --no-live to skip it, --timeout SECS to adjust the per-ping wait (default 30s). Runtimes without a documented non-interactive mode report live verification as unavailable; use --no-live for metadata-only verification. A persona file is checked separately when one is configured.

Operate

scientist launch

Launch autonomous agents on a task. Auto-wraps in tmux by default.

scientist launch -c <config> [key=value ...]

There are no dedicated flags for agent count, model, or the dashboard; anything in task.yaml can be overridden inline with dotlist syntax:

scientist launch -c task.yaml
scientist launch -c task.yaml agents.count=4 agents.model=opus
scientist launch -c task.yaml run.verbose=true run.ui=true
scientist launch -c task.yaml run.session=local     # skip the tmux wrapper

scientist continue

Resume agents from a previous run.

scientist continue [--task TASK] [--run RUN] [key=value ...]

scientist continue
scientist continue --task my-task agents.model=opus
scientist continue --from abc123 -i "continue this branch with SIMD"

scientist halt

Gracefully stop the Synthetic Scientists manager and all agents.

scientist halt [--task TASK] [--run RUN] [--all]

scientist overview

Show manager/agent status and top ranking entries.

scientist overview [--task TASK] [--run RUN]

Review

scientist results

List and search experiments. Default: top 20 sorted by score.

scientist results [options]

scientist results                     # Top 20 by score
scientist results -n 5                # Top 5
scientist results --recent            # Sort by time
scientist results --agent agent-1     # Filter by agent
scientist results --search "kernel"   # Full-text search

scientist inspect

Show full details and diff for a specific experiment.

scientist inspect <hash> [--diff] [--task TASK] [--run RUN]

scientist inspect abc123
scientist inspect abc123 --diff

scientist knowledge

List, search, or read agent notes.

scientist knowledge [options]

scientist knowledge                    # List all
scientist knowledge --search "idea"    # Search
scientist knowledge --read 3           # Read note #3

scientist methods

List skills or show details of a specific skill.

scientist methods [--read NAME]

scientist methods
scientist methods --read optimizer

scientist work

Read or update the session-global work DAG.

scientist work list --available
scientist work add "Profile runtime" --id profile --persona performance-analyst
scientist work claim profile
scientist work complete profile --experiment <hash>
scientist work link optimize profile --type depends_on

Nodes may represent tasks, commits, verification, or synthesis. Claims are atomic and expire after their lease. Every lab shares the same work DAG.

scientist sessions

List Synthetic Scientists sessions.

scientist sessions [options]

scientist sessions                    # Active sessions only
scientist sessions --all              # Include halted sessions
scientist sessions --task my-task     # Filter by task

Interface

scientist dashboard

Start the Synthetic Scientists live interface.

scientist dashboard [options]

scientist dashboard
scientist dashboard --port 9000

Workspace

These commands are primarily used by agents during their eval loop, but can also be run manually.

scientist eval

Stage all changes, commit, and run the evaluator.

scientist eval -m <message> [--node NODE] [--agent ID] [--workdir DIR]
               [--no-wait] [--timeout SECS] [--tune]

scientist eval -m "Optimized inner loop with vectorization"

scientist wait

Block until the grader daemon finalizes a previously submitted experiment (e.g. one submitted with scientist eval --no-wait).

scientist wait <hash> [--timeout SECS] [--workdir DIR]

scientist wait abc123
scientist wait abc123 --timeout 600

scientist diff

Show staged and unstaged changes.

scientist diff [--workdir DIR]

scientist undo

Reset to HEAD~1, discarding the last commit and its changes.

scientist undo [--workdir DIR]

scientist restore

Reset the working tree to a previous experiment's commit.

scientist restore <hash> [--workdir DIR] [--task TASK] [--run RUN]

scientist restore abc123

scientist promote

Promote an experiment commit to a normal git branch in the session repository. The experiment commits live in the shared object store reachable from every agent worktree, so any experiment hash can be exported.

scientist promote <hash> -b <branch> [-f] [--task TASK] [--run RUN]

scientist promote abc123 --branch scientist/better-scheduler
# then: cd <run>/repo && git checkout scientist/better-scheduler

scientist cadence

View or modify per-agent cadence configuration.

scientist cadence [subcommand] [options]

Subcommands:

scientist cadence                              # Show config
scientist cadence set reflect --every 3        # Reflect every 3 evals
scientist cadence set review --every 5 --prompt "Review alternatives"
scientist cadence set synthesize --every 5 --global  # Use global eval counter
scientist cadence remove synthesize           # Remove action
scientist cadence reset                        # Reset to defaults