openscience: Instructions file for Claude Code

CLAUDE.md: OpenScience

Read AGENTS.md first: repository map, commands, conventions, and the CI/release rules. This file keeps the product facts and the prompt-architecture guide that help when the shipped agent misbehaves.

Product facts

OpenScience (openscience) is an open-source, model-agnostic AI research agent for ML engineering and scientific work. Built with Bun and TypeScript, it ships as native binaries for Linux, macOS, and Windows.

• npm package: @synsci/openscience
• Binary name: openscience
• Config dir: ~/.config/openscience/ (override with OPENSCIENCE_CONFIG_DIR)
• Data root: ~/.openscience/ by default (relocatable; legacy synsc data imports automatically)
• Config file: openscience.json
• Provider ID: synsci (Atlas wire contract, do not rename)

Prompt architecture

In this guide, src/... paths are relative to backend/cli; prompt paths such as agent/prompt/... and session/prompt/... are relative to backend/cli/src.

The Research loop is shared across providers. Prompt selection, scientific context, model options and API serialization are separate steps. The harness is OpenCode's Build path with science in skills, agents, headers and a few switchable units; the loop itself knows nothing about science, deliverables or budgets.

Agent registry + selected model + current user message
    -> agent prompt, otherwise the model-family header with the science block
    -> environment (+ harness env lines), project instructions, core-skills index, posture reminder
    -> system-transform plugin, then parameter/header hooks
    -> provider message/tool normalization and inference options
    -> provider API
    -> on a final answer or a tripped guard, the harness units may continue or redirect

Header selection

LLM.prompts in src/session/llm.ts selects an explicit agent.prompt first. An agent without one (research, plan) receives the model-family header: SystemPrompt.provider(model) in src/session/system.ts routes by wire model id in OpenCode's order (gpt-4/o1/o3 and other gpt → gpt.txt; gpt-6/astra → gpt-astra.txt; codex → codex.txt; gemini- → gemini.txt; claude → anthropic.txt; otherwise default.txt). Each family file carries one {{SCIENCE}} slot that the runtime fills with agent/prompt/science.txt (Evidence and files; Methods and deliverables; Manuscripts and figures), so the science text is byte-identical across families. session/prompt/response.txt is appended to every header.