A session is one conversation: your requests, the responses, and the recorded tool activity. OpenScience saves sessions so you can return to a task.
Start a session
Open the workspace with openscience, or send a single request from a terminal:
openscience run "Review the analysis plan in this project"
Use --title to make the session easy to find later:
openscience run --title "Sample quality checks" "Inspect data/samples.csv for missing values"
New sessions use an isolated scratch workspace by default. To make relative tool paths resolve in the selected project, choose project mode when creating the session:
openscience run --workspace project "Analyze the CSV files in this directory"
--workspace isolated explicitly selects the default. Continuing a session preserves
its workspace; an explicit conflicting mode is rejected. Project mode uses the
existing project directory and does not make OpenScience own or delete that directory
when the session is removed. It retains the normal filesystem and tool permissions.
The model receives guidance matching that mode: temporary session scratch in
isolated mode, or durable shared project files in project mode.
Check openscience run --help for workspace-mode support when using an older runtime.
Attach files or pipe input
openscience run "Explain this protocol and identify missing details" --file methods/protocol.md
git diff | openscience run "Review this diff for likely bugs"
Repeat --file for multiple files. Piped input is appended to your message.
--file attaches a file. --attach connects to an already running OpenScience server.
Continue existing work
openscience session list
openscience session list -n 10 --format json
openscience run --continue "Now create a plot of the missing-value counts"
openscience run --session <session-id> "Explain the limitations of the analysis"
Replace <session-id> with an ID from the session list. --continue chooses the latest session; use an explicit ID when several tasks are active.
In the workspace, open the saved conversation in project history. Queued prompts and follow-up messages continue that conversation.
Sending a message follows the latest response. While you read earlier messages, incoming activity keeps your reading position; choose Jump to latest to follow the conversation again. Loading earlier messages preserves your reading position and respects a later Jump to latest or send, even if the history request is slow. Background output checks and compute status updates stay inside the conversation without resetting its scroll position.
Choose model and research settings
| Flag | Purpose |
|---|---|
--model <provider>/<model>, -m | Select an exact configured model. |
--agent <name> | Select a primary agent; defaults to Research. |
--variant <tier> | Select a reasoning tier supported by that model. |
--effort normal or --effort ultra | Choose research breadth. |
--bare | Answer without tools; useful for testing a model connection. |
--command <name> | Run a custom command with the message as its arguments. |
--format json | Write one JSON event per line. |
--workspace project or --workspace isolated | Choose the tool workspace when creating a session. |
See Models and Research controls.
Permissions in terminal runs
An interactive terminal run can ask for permission. Without a terminal, permission prompts are rejected by default so a pipeline does not wait forever.
| Flag | Behavior |
|---|---|
--deny-prompts | Reject permission requests for this run. |
--auto-approve | Approve permission requests for this run and disable delegation. |
--dangerously-skip-permissions | Alias for --auto-approve. |
The two policies are mutually exclusive. They do not persist as app settings.
Use automatic approval only for a task whose allowed work you have already reviewed. A terminal run cannot conduct an interactive clarification conversation; include the needed assumptions and constraints in its prompt.
Exit codes
| Code | Meaning |
|---|---|
0 | The turn completed. |
1 | The session reported an error. |
2 | A usage or configuration error prevented the request. |
3 | A permission request or question was rejected. |
A completed turn is not proof that a scientific claim is correct. Inspect the output and run the relevant checks.
Attach to a running workspace
Start a server in one terminal:
openscience serve --port 4096
Send a request from another:
openscience run --attach http://localhost:4096 "Summarize the project"
openscience run --attach http://localhost:4096 --session <session-id> "Continue the analysis"
Use the server's actual printed URL and the same project context. The server must remain running.
Export and import
openscience export <session-id> > session.json
openscience import session.json
An export contains the conversation record. It is not a complete project backup: copy the datasets, source files, and result files separately. Review the transcript before sharing it because it can include private research content.
For recovery during long work, use /checkpoint or /handoff in the workspace. For machine-readable output and CI, see Automation and JSON output.
Native benchmark runners
The source adapter in tooling/harbor targets Harbor 0.22.0. It requires run --workspace project to preserve the native task working directory for relative tool paths, verifies the selected OpenScience binary, and requires a successful final JSON done event after collecting remote logs. A binary without the workspace option fails setup. Raw and partial trajectories remain available when a run fails; missing usage is not reported as zero. A successful agent process still needs the native task verifier.
Use a matching Linux headless build to benchmark local source changes. The adapter guide contains the exact binary and binary_sha256 arguments. Existing runners pinned to a different Harbor version need separate conformance checks; this adapter does not replace their task images, graders, or aggregation.
Harbor defaults disable session and message title generation with
agent.title.disable: true. Research execution and compaction remain enabled;
interactive sessions keep their normal titles. Trajectory usage covers recorded
root-agent steps and uses catalog cost estimates. It excludes unrecorded auxiliary
calls and external tool or compute charges, so whole-trial cost comparisons need
separate billing evidence.