CLAUDE.md: OpenScience

Project Overview

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/ (also ~/.openscience/; legacy ~/.synsc auto-migrates)
Config file: openscience.json
Provider ID: synsci (Atlas wire contract, do not rename)

Repository Structure

Single git repo organized by runtime boundary.

frontend/          workspace (browser UI), docs/share site, and shared UI
backend/           CLI/server, skills, sessions, and provider integrations
tooling/           SDK, plugin runtime, repo automation, launcher, utilities, and patches

Development

# Run CLI in dev mode
bun run dev

# Build all platform binaries
cd backend/cli && bun run build

# Typecheck
bun run typecheck

# Run tests
cd backend/cli && bun test

Prompt Architecture (Dual-Layer)

The CLI uses a dual-layer prompt system: provider-level system prompts + agent-level workflow prompts.

User request with agent name (e.g., "research")
  │
  ├─ Layer 1: SYSTEM role ← session prompt (provider-specific)
  │   src/session/system.ts selects by model provider
  │
  └─ Layer 2: USER role injection ← agent prompt (task-specific)
      src/session/prompt.ts selects by agent name + tier

Session prompts (`src/session/prompt/`) (6 provider + 4 utility)

File	Purpose
`anthropic.txt`	Claude models
`beast.txt`	GPT-4o / o1 / o3
`codex_header.txt`	GPT-5 / Codex
`gemini.txt`	Gemini models
`qwen.txt`	Qwen / fallback
`copilot-gpt-5.txt`	Copilot GPT-5
`plan.txt`, `plan-reminder-anthropic.txt`	Plan mode
`build-switch.txt`, `max-steps.txt`	Utility

Routing logic: src/session/system.ts → SystemPrompt.provider(model).

Agent prompts (`src/agent/prompt/`)

File	Agent(s)
`research.txt`	`research` (default harness)
`biology.txt`	`biology` (specialist)
`physics.txt`	`physics` (specialist)
`ml.txt`	`ml` (specialist)
`physics-critique.txt`	`physics-critique` (subagent)
`critique.txt`	`critique` (subagent)
`reviewer.txt`	`reviewer` (subagent)
`literature-review.txt`	`literature-review` (subagent)
`write.txt`	`write` (subagent)
`explore.txt`	`explore` (subagent)
`plan.txt`	`plan` (mode, in `src/session/prompt/`)
`compaction.txt`	`compaction` (system)
`title.txt`	`title` (system)

Routing logic: src/session/prompt.ts injects agent workflow prompts by agent name (an if-chain in insertReminders).

Agent registry (`src/agent/agent.ts`)

Defines built-in agents with Agent.Info schema: name, mode (primary/subagent/all), hidden, model, prompt, permission, temperature, steps.

Default harness: research (the single user-facing default; also the plan-exit target) Specialists: biology, physics, ml Mode: plan (read-only) Subagents (hidden from users): task, explore, literature-review, critique, reviewer, physics-critique, write System agents: compaction, title

Custom agents can be added via config file (openscience.json → agent key). See src/cli/cmd/agent.ts for the creation CLI.

RCA & Debugging Guide

Agent misbehaving? Trace the prompt chain:

Which agent is active? → src/agent/agent.ts, find the agent by name, check its mode, model, prompt fields
Which prompt is injected? → src/session/prompt.ts, follow the input.agent.name switch
Which system prompt? → src/session/system.ts, SystemPrompt.provider(model) selects by provider

Common failure patterns:

Symptom	Likely cause	Where to look
Agent ignores skills	Skill catalog missing/truncated in prompt	`src/agent/prompt/{agent}.txt`, check toolkit section
Wrong model used	Agent/model config incorrect	`src/agent/agent.ts` + `openscience.json` `agent` config
Agent skips stages	Stage gates not mandatory in prompt	`src/agent/prompt/{agent}.txt`, check BLOCKING vs advisory language
Critique not triggered	Critique is advisory, not mandatory	`src/agent/prompt/critique.txt` + parent prompt's critique section
Sub-agent returns empty	Context window exhaustion or bad prompt	`src/agent/agent.ts`, check subagent's `steps` limit
Custom agent not appearing	Config not in `openscience.json` or wrong `mode`	Config file `agent` key → `src/agent/agent.ts`

Key files for prompt debugging (read these first):

src/agent/agent.ts          # Agent definitions, what agents exist and their config
src/agent/prompt/*.txt      # Agent behavior, what the agent is told to do
src/session/prompt.ts       # Routing, which prompt gets injected for which agent
src/session/system.ts       # Provider routing, which system prompt for which model

Style Guide

See AGENTS.md for full style guide. Key points:

Prefer const over let, avoid else, single-word variable names
Use Bun APIs (Bun.file(), etc.)
Rely on type inference, avoid explicit annotations
No mocks in tests, test real implementations
No any type