@coscientist/opencode-plugin

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

• Build the plugin.
• Load it in OpenCode.
• cosci_install_agents() and cosci_install_prompts().
• cosci_run_create(goal=...), draft plan, cosci_plan_approve(), submit jobs.
• 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)

• Build the plugin.

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

• 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
  

• Restart OpenCode.

Loader B: Global plugin directory (older layouts)

• Build the plugin (same as above).
• 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
  

• 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

• cosci_run_create(goal="Map solvation free energy workflow")
• Draft plan -> cosci_plan_set(plan_text=..., plan_json=[...])
• Approval -> cosci_plan_approve()
• Submit -> cosci_job_submit_slurm(script_path="jobs/run.sh")
• 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

• Switch to @cosci-deep-planner.
• Provide literature file paths.
• It claims each paper via cosci_paper_claim before spawning subagents to prevent duplicate assignment.
• It spawns background subagents that must read full files via cosci_extract_text (PDF/HTML) or cosci_read_file (text).
• Wait event-driven for subagents with cosci_background_wait_all(task_ids=[...], timeout_seconds=0) (no polling loop).
• It merges summaries and writes a deep plan with dependencies and failure modes.
• 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.