Research controls

Research is the default agent. It can search the literature, analyze data, write code, run experiments, and prepare a report. Skills supply procedures for particular domains.

Start with a clear goal, the inputs, an output location, and any limits on time or spending.

Plan before execution

Use /plan when you want to agree on an approach before implementation:

/plan Compare these treatment groups. Identify assumptions, possible
confounders, the statistical test, and the outputs we should save.

Plan mode inspects the available material and prepares a plan. It does not carry out the proposed analysis or edit project files, apart from its plan files. After reviewing the plan, return to Research and ask it to execute the agreed steps.

Normal and Ultra effort

Ultra can involve more work and model usage. It does not guarantee a better answer or a fixed number of parallel workers.

openscience run --effort normal "Check the assumptions in results/analysis.md"
openscience run --effort ultra "Compare defensible approaches to the missing data in this project"

A model's reasoning tier is a separate setting; see Models.

Delegation and independence

In the research controls, delegation determines how readily OpenScience divides independent work:

Independence controls how often the agent asks you to resolve choices:

• Interactive: plan together and discuss consequential choices.
• Balanced: ask about meaningful ambiguities while continuing routine work.
• Independent: proceed within the task's constraints and ask when blocked.

These settings guide collaboration. They do not replace your action-approval settings or a service's spending controls.

Workers

The built-in workers are explore (a read-only scout for files, data, code and papers), five specialists built from one template: ml, biology, physics, chemistry and data (pipelines, processing, coding, visualization), and general, a plain worker for a multi-step brief that fits no specialty. Each specialist carries an index of its skill categories and the domain tools those need; the lead dispatches one by name through the Task tool, and independent workers run at the same time with no fixed cap.

You can also hand a job to a worker yourself: type @ in the composer and pick one (@explore where is the early-stopping split decided?). The message becomes that worker's brief, the lead waits for its report, and the worker's session opens from the delegation row. A worker's config can set hidden: true to keep it out of the @ menu while the lead may still dispatch it.

A worker runs on its own configured model when the agent has one, otherwise on the Worker model from Customize → Models, otherwise on the lead's model. No built-in agent has a model in code; the recommended configuration is documented below. Workers work in the lead's own directory: the files they write there are the deliverables, and the lead reads them directly. The lead writes a self-contained brief with a definition of done, waits for the result (returned once, in a <task_result> envelope with a task_id that can resume the same worker), and integrates it; checking the lead's own output is never delegated. A worker started in the background returns immediately and wakes the lead with its result when it finishes. Workers cannot dispatch workers unless subagent_depth in openscience.json allows deeper nesting (default 1).

A delegated task shows as one line (what it is doing, which agent, its state and elapsed time) and streams nothing while it runs; open it for the result, its saved Results and Open agent, which shows the worker's own conversation. Stopping the lead also cancels its active delegated work. A stopped task's saved files and recorded tool results remain available.

Only the latest assistant message's text after its final tool call counts as the result; earlier progress text cannot make an unfinished worker look complete. A result without a Verification section (the command, its exit code, what it proves) is a claim, and the lead is told so.

Recommended models

Put the models you want each agent to use in openscience.json; nothing is hard-coded:

{
  "model": "openai/gpt-6-astra",
  "agent": {
    "explore": { "model": "google/gemini-3.8-flash" },
    "ml": { "model": "openai/gpt-6-sol", "variant": "high" },
    "biology": { "model": "openai/gpt-6-sol" },
    "physics": { "model": "openai/gpt-6-sol" },
    "chemistry": { "model": "openai/gpt-6-sol" },
    "data": { "model": "openai/gpt-6-sol" }
  }
}

A worker on a different model than the lead uses its own variant (reasoning effort); on the lead's model it inherits the lead's. Add your own specialist the same way, with mode: "subagent", skills: ["<category>", ...] for its domain index and a permission rule per domain tool it may use without a skill.

Handoffs retain command receipt references and failures. A shell exit of zero describes the outer process; it does not establish that nested tests passed or that a scientific conclusion is valid. Those claims still need their actual test or evaluation evidence.

The Show reasoning and activity control stays available during execution. Some providers return tool activity without readable reasoning; OpenScience indicates that state rather than presenting missing reasoning as an empty trace. A compute submission receipt records its state at that moment; use View current job for its latest status.

Action approval

Choose how much oversight you want from the composer's research controls. Ask always, Ask risky, and Full access offer progressively fewer routine approval prompts.

Keep your request specific about changes or costs you want to review. See Permissions and control for choosing an approval mode and understanding a request.

Persistent goals and progress

Use /goal for an objective you want to pursue across multiple steps:

/goal Produce a reproducible analysis of data/samples.csv, with code,
a figure, a methods note, and a list of unresolved limitations.

The session header shows progress and context usage. /checkpoint captures a recovery point; /handoff saves a continuation note and compacts the conversation. Commands offered as skills must be enabled in your setup.

A persistent goal does not mean OpenScience can keep working while your computer or app is off. Save a checkpoint before interrupting a long task.

Custom agents

Create a reusable specialist when you need a consistent role across projects:

openscience agent create
openscience agent list

The creation wizard produces a Markdown definition you can review and edit. Custom agents live in .openscience/agent/ for a project or ~/.config/openscience/agent/ for your user account.

For a manually authored reviewer:

---
description: Review analysis plans for confounding and data leakage
mode: primary
permission:
  edit: deny
  bash: deny
---

Review the analysis plan and identify unsupported assumptions.
Explain each concern and suggest a check before the analysis runs.

Save it as analysis-reviewer.md in the agent directory. Select it with --agent analysis-reviewer, or in the app: once a second primary agent exists, an agent chip appears beside the model control in the composer, and Tab in an empty composer cycles through the primary agents. A primary agent can lead a session, a subagent is for delegated tasks and the @ menu, and all supports both.

Other frontmatter options: model (provider/model-id; a worker without one uses the lead's model), temperature and top_p, steps (a cap on agentic iterations, after which the agent is asked to summarize and list what remains), color (a hex value or a theme color such as accent), disable, and permission.task globs that decide which workers the agent may dispatch. The deprecated tools: map still loads; openscience agent create writes permission: rules.

Custom definitions change the agent's instructions and permitted actions. Test a new profile on a small task before relying on it.