Co-Scientist OpenCode Plugin (@coscientist/opencode-plugin)

Co-Scientist, minus the control plane. All brains, minimal wiring.

This is a standalone OpenCode plugin for agentic scientific workflows. Runs are filesystem-backed, approvals are soft gates, and jobs can flow through local Slurm or MCP. It is intentionally "just enough structure" to run real experiments without booting a full service mesh.

If you like sharp tools and short feedback loops, you are home.

If You Only Read One Thing

1. Build the plugin.
2. Load it in OpenCode.
3. cosci_install_agents() and cosci_install_prompts().
4. cosci_run_create(goal=...), draft plan, cosci_plan_approve(), submit jobs.
5. Use @cosci-deep-planner for literature-first deep planning.

Default Roles

• @cosci-supervisor primary hub and default driver for runs.
• @cosci-worker focused subagent for tasks assigned by the supervisor.
• @cosci-deep-planner literature-first planner, plan only (no jobs).

What You Get

• Local run state at .opencode/coscientist.json.
• Soft approval gate: plans exist, must be approved before jobs.
• Local Slurm submit/poll or MCP submit/poll.
• Background subagent sessions for long-ish work.
• Skills loader aligned to OpenCode skill dirs: .opencode/skills/<name>/SKILL.md.
• Minimal UI touch: toasts, nothing invasive.

What You Don't Get (Yet)

• Control plane, orchestrator loop, or worker daemon.
• Multi-user auth or service credentials storage.
• DB migrations, event bus, or RAG store.
• Heavy guardrails. This is for fast prototyping.

Onboarding (Oh-My Style) Paste this into an LLM agent session:

Install and configure the Co-Scientist OpenCode plugin for this repo by following:
apps/coscientist-opencode-plugin/INSTALLATION.md

Install See apps/coscientist-opencode-plugin/INSTALLATION.md for the full, guided flow.

For humans (manual). Pick your loader:

Loader A: Project plugin directory (common)

1. Build the plugin.

   cd apps/coscientist-opencode-plugin
   npm install
   npm run build

2. Add a local plugin file.

   mkdir -p .opencode/plugins
   cat > .opencode/plugins/coscientist.js <<'JS'
   export { default } from "../../apps/coscientist-opencode-plugin/dist/index.js";
   JS

3. Restart OpenCode.

Loader B: Global plugin directory (older layouts)

1. Build the plugin (same as above).
2. Add a global plugin file:

   mkdir -p ~/.config/opencode/plugins
   cat > ~/.config/opencode/plugins/coscientist.js <<'JS'
   export { default } from "/ABS/PATH/apps/coscientist-opencode-plugin/dist/index.js";
   JS

3. Restart OpenCode.

If your build looks for .opencode/plugin/ or ~/.config/opencode/plugin/, swap the folder name.

Optional (npm, published):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@coscientist/opencode-plugin"]
}

Published quick start (recommended):

# project root
npm install -D @coscientist/opencode-plugin
npx @coscientist/cosci init

Then restart OpenCode.

For agents (copy-paste prompt):

You are setting up the Co-Scientist OpenCode plugin.
1) Ensure plugin is loaded.
2) Run cosci_install_agents() and cosci_install_prompts().
3) Create a run: cosci_run_create(goal="...").
4) Draft a plan: cosci_plan_set(plan_text=..., plan_json=[...]).
5) Ask for approval, then cosci_plan_approve().
6) Submit jobs via cosci_job_submit_slurm() or cosci_job_submit_mcp().

Install Agents

cosci_install_agents() writes three agent files into .opencode/agents/:

• @cosci-supervisor primary orchestrator
• @cosci-worker focused subagent
• @cosci-deep-planner literature-first planner

Prompt template overrides (no rebuild):

• Project: .opencode/cosci/agents/<name>.md
• Global: ~/.config/opencode/cosci/agents/<name>.md

Install Prompts

cosci_install_prompts() drops starter skills into OpenCode’s skill directory:

• .opencode/skills/<name>/SKILL.md

Skill names follow OpenCode’s lowercase hyphenated convention (e.g. deep-plan). Each skill file includes OpenCode’s required frontmatter (name, description) plus optional mcp.* fields for Co‑Scientist.

Templates include submit-slurm-job, get-job-details, cancel-job, list-jobs, jobs-register, jobs-unwatch, jobs-watch-list, events-list, events-watch, remote-write-file, remote-read-file, plan-format, deep-plan, literature-summary, extract-text, download-paper, and papers-list.

Quick Start

1. cosci_run_create(goal="Map solvation free energy workflow")
2. Draft plan -> cosci_plan_set(plan_text=..., plan_json=[...])
3. Approval -> cosci_plan_approve()
4. Submit -> cosci_job_submit_slurm(script_path="jobs/run.sh")
5. Poll -> cosci_job_poll_all()

Model Setup Use cosci_model_setup() to configure OpenCode’s default model and small_model, and (optionally) map Co‑Scientist agents to those models. It walks you through a short question flow and writes opencode.json (project or global).

Cluster Setup Use cosci_cluster_setup() to write .mcp.json with MCP toolbox defaults. It asks for SSH host/user/auth, supports repo‑local ./ssh, and keeps secrets out of the file unless you explicitly opt in.

Event Bridge Files (MCP Toolbox) The MCP toolbox writes job events to a JSONL file for long‑running jobs:

• Default: .opencode/cosci-events.jsonl
• State: .opencode/cosci-events-state.json
• Base root: COSCI_PROJECT_DIR (defaults to CWD)
• Override paths: COSCI_EVENTS_PATH, COSCI_EVENTS_STATE_PATH

Run Artifacts Each run writes a provenance folder:

.opencode/coscientist/runs/<run_id>/
  plan.json
  plan.md
  provenance.json
  datasets.json
  papers.json
  artifacts.json
  datasets/<dataset_id>_manifest.json
  seeds.json
  jobs/<job_id>/job.json
  jobs/<job_id>/script.sh
  jobs/<job_id>/sacct.json
  artifacts/

provenance.json captures git SHA + dirty status, environment info, tool versions, and a small event log. Datasets and seeds are stored per run in datasets.json and seeds.json.

Deep Planning Flow

1. Switch to @cosci-deep-planner.
2. Provide literature file paths.
3. It claims each paper via cosci_paper_claim before spawning subagents to prevent duplicate assignment.
4. It spawns background subagents that must read full files via cosci_extract_text (PDF/HTML) or cosci_read_file (text).
5. Wait event-driven for subagents with cosci_background_wait_all(task_ids=[...], timeout_seconds=0) (no polling loop).
6. It merges summaries and writes a deep plan with dependencies and failure modes.
7. If multiple plan blocks exist, use cosci_plan_merge.

Plan Schema Each plan step uses:

• id, type, description (required)
• depends_on (array of step ids)
• inputs, outputs, resources (optional)
• status (pending|running|completed|failed|blocked|cancelled|skipped)
• artifacts (list of {type,path,url,note})

Use cosci_plan_step_update() to update status or attach artifacts.

Text Extraction Use cosci_extract_text(path, offset?, max_chars?) for PDFs/HTML. It caches extracted text in .opencode/coscientist/extract/ and returns section hints. If available, it will use pdftotext (poppler) for PDFs; otherwise it falls back to the bundled pdf-parse parser. Chunk sizes are capped for safety (200k chars for extract, 200k bytes for read).

Configuration

Project config: .opencode/coscientist.config.json Global config: ~/.config/opencode/coscientist.json

Example:

{
  "state_path": ".opencode/coscientist.json",
  "mcp": {
    "submit_tool": "submit_slurm_job",
    "poll_tool": "get_job_details"
  },
  "ui": {
    "toast_on_start": true,
    "toast_on_missing_run": true,
    "toast_on_background_complete": true,
    "toast_on_status": true,
    "toast_on_status_interval_seconds": 300,
    "wake_parent_on_background_complete": true,
    "wake_parent_on_background_error": true
  }
}

Tools All tools return structured objects: { ok: true|false, message?, error?, ... }.

• cosci_help()
• cosci_config_show()
• cosci_cluster_setup(...)
• cosci_model_setup(...)
• cosci_install_agents()
• cosci_install_prompts()
• cosci_install_command()
• cosci_command(command, run_id?)
• cosci_skill_list()
• cosci_skill_get(name)
• cosci_skill_mcp(skill, arguments_json) (arguments_json is an object)
• cosci_skill_install_default(name, content?, scope?) (name is lower-case hyphenated)
• cosci_mcp_servers()
• cosci_mcp_tools(server?)
• cosci_background_task(description, prompt, agent?)
• cosci_background_list()
• cosci_background_wait(task_id, timeout_seconds?)
• cosci_background_wait_all(task_ids?, timeout_seconds?)
• cosci_run_create(goal, run_id?)
• cosci_run_select(run_id)
• cosci_run_status(run_id?)
• cosci_status_toast(run_id?)
• cosci_next_actions(run_id?)
• cosci_events_sync(run_id?, timeout_ms?, use_watch?, server?)
• cosci_plan_set(run_id?, plan_text?, plan_json?) (plan_json is an array of objects)
• cosci_plan_get(run_id?)
• cosci_plan_step_update(run_id?, step_id, status?, artifacts?, append_artifacts?)
• cosci_plan_approve(run_id?, note?)
• cosci_plan_merge(run_id?, plan_json_list, plan_text?, apply?) (plan_json_list is an array)
• cosci_job_submit_slurm(run_id?, script_path, log_path?, note?)
• cosci_job_validate(script_path)
• cosci_job_submit_mcp(run_id?, mcp_tool?, job_json, log_path?, note?) (job_json is an object)
• cosci_job_register(run_id?, slurm_id, log_path?, note?)
• cosci_job_poll(run_id?, slurm_id)
• cosci_job_poll_mcp(run_id?, mcp_tool?, slurm_id)
• cosci_job_poll_all(run_id?)
• cosci_job_list(run_id?)
• cosci_read_file(path, offset?, max_bytes?) (max_chars is a deprecated alias)
• cosci_extract_text(path, offset?, max_chars?, refresh?)
• cosci_download_paper(url, filename?, dir?, max_bytes?, overwrite?)
• cosci_papers_list(dir?)
• cosci_paper_claim(run_id?, paper_id?, url?, path?, title?, claimant?, task_id?, note?, allow_reclaim?)
• cosci_paper_release(run_id?, paper_id?, url?, path?, note?)
• cosci_paper_registry(run_id?)
• cosci_dataset_register(run_id?, dataset_id, path?, checksum?, notes?, replace?)
• cosci_dataset_list(run_id?)
• cosci_artifact_register(run_id?, path, kind?, produced_by_job_id?, step_id?, checksum?, notes?, replace?)
• cosci_seed_set(run_id?, seed, label?, replace?)
• cosci_seed_list(run_id?)
• cosci_state_path()

MCP Notes

• Skills can declare MCP frontmatter: mcp.server and mcp.tool.
• cosci_skill_mcp() routes to that MCP tool with server-aware resolution.
• If the MCP toolbox event bridge is available, jobs are auto-registered and cosci_events_sync() can ingest job state updates.

Background Wake Notes

• cosci_background_wait() is event-driven and supports timeout_seconds=0 for no-timeout wait.
• cosci_background_wait_all() waits on many tasks via event wake-ups (no polling loop).
• On completion/error, subagent events can wake the parent session automatically.

Datasets + Seeds Use cosci_dataset_register() to capture dataset identifiers, checksums, and directory manifests. Use cosci_seed_set() to record RNG seeds (and cosci_seed_list() to review them).

Artifacts Use cosci_artifact_register() to record output files with checksums, producing job ids, and optional plan step linkage. Records are stored in artifacts.json under the run folder.

MCP Toolkit (npm/bunx) Use the standalone toolbox package (recommended for parity with the main system):

.mcp.json (npx):

{
  "mcpServers": {
    "cosci": {
      "command": "npx",
      "args": ["-y", "@coscientist/mcp-toolbox@latest"]
    }
  }
}

Or let the plugin generate it with cosci_cluster_setup().

Bootstrap CLI (npm/bunx) One command to set up .opencode/plugins/coscientist.js and .mcp.json:

npx -y @coscientist/cosci init

Or bunx:

bunx @coscientist/cosci init

Run MCP toolbox directly (no OpenCode):

npx -y @coscientist/cosci mcp-run

Local plugin path:

cosci init --plugin-path ./dist/index.js

Write MCP config to global scope:

cosci init --mcp-scope global

.mcp.json (bunx):

{
  "mcpServers": {
    "cosci": {
      "command": "bunx",
      "args": ["@coscientist/mcp-toolbox@latest"]
    }
  }
}

Event bridge tools (from the toolbox):

• jobs_register, jobs_unwatch
• events_list, events_watch

Remote file tools (from the toolbox):

• remote_write_file, remote_read_file

UI Notes We only touch the UI via toasts. Periodic status toasts are controlled via ui.toast_on_status and ui.toast_on_status_interval_seconds. The plugin is intentionally polite, not invasive.

State & Files

• State file: .opencode/coscientist.json
• State log: .opencode/coscientist.json.log
• Skills: .opencode/skills/
• Agents: .opencode/agents/
• Slash command: .opencode/commands/cosci.md

Build All (plugin + toolbox + CLI)

npm run build:all

Disclaimer Not affiliated with OpenCode or its maintainers.