SEED HARNESS

한국어 README

SEED Harness is an OpenCode plugin for running traceable lab-style work through one professor-facing agent: Lab-Representative.

Use /seed in the target project. Lab-Representative receives the goal, decides whether a dynamic internal team is useful, tracks evidence and progress, and writes auditable run artifacts under .seed-agent/runs/<run_id>/.

The user should not choose or manage internal workers. SEED registers Lab-Representative as the single SEED OpenCode agent; task-specific members are per-run dynamic role contracts created by Lab-Representative. SEED core does not auto-create fixed paper-review, web-app, automation, or research-framework teams from keywords, file types, or PDF paths.

Requirements

• Linux runtime. This release is distributed and validated for Linux only. Windows and macOS are not supported yet.
• Node.js >=20
• OpenCode >=1.15.6
• At least one OpenCode model provider configured or selected. SEED can run with OpenAI/GPT, Anthropic/Claude, or any other OpenCode provider/model because provider auth and model selection stay in OpenCode.

Check Node and npm:

node --version
npm --version

Install OpenCode first:

npm install -g opencode-ai
opencode --version

Install In A Target Project

Run these commands in the repository or working directory where you want /seed to work:

npx --yes @seed-lab/opencode-seed-agent@latest install --project
opencode providers login -p <provider>
npx --yes @seed-lab/opencode-seed-agent@latest doctor --project --agents
opencode

install --project is model-neutral by default. If you want to pin every SEED profile to one explicit OpenCode model instead of using the model selected in OpenCode, add --model provider/model, for example:

npx --yes @seed-lab/opencode-seed-agent@latest install --project --model anthropic/claude-sonnet-4-5

The installer writes:

• .opencode/opencode.jsonc
• .opencode/seed-agent.jsonc
• opencode.jsonc in the project root as a compatibility config for OpenCode workspaces that do not reliably discover .opencode/ before startup

Expected install behavior:

• OpenCode opens on Lab-Representative.
• SEED inherits the OpenCode selected model by default. If the professor chooses Claude, GPT, or another provider/model for Lab-Representative, internal SEED delegation and dynamic agent-threads use that same selected model unless the project config explicitly pins a model profile.
• OpenCode keeps provider credentials. SEED does not read or store API keys.
• Project installs ignore personal SEED config by default.
• Host MCP servers, host tools, host commands, and host agents are isolated by default.
• Native OpenCode build/plan primary faces are disabled for the installed project.

Inside OpenCode, start with:

/seed "Analyze this repository and tell me the run directory."

Plain chat with Lab-Representative is still normal OpenCode chat. Use /seed when you want SEED to create a tracked run, task board, activity briefings, evidence ledger, and final report artifacts.

Normal Use

Give the goal once through /seed:

/seed "analyze this repository and improve the README"
/seed "implement the missing CLI validation flow, run checks, and write a final report"
/seed "Analyze and review ./2605.18747v1.pdf"

These are examples, not built-in product lanes. SEED is meant for many kinds of repository, research, implementation, review, automation, and local workflow tasks. Paper/PDF analysis is only one possible task.

Lab-Representative should then:

• maintain the primary task and any real subtasks;
• decide whether to run solo, delegate, or create a dynamic team;
• validate member role contracts before child sessions launch;
• give coding/execution members helper delegation plus workspace lease/diff tools, so large artifacts can be split by the worker instead of falling back to Lab-Representative direct edits;
• keep evidence, progress, trace, and final report artifacts current;
• report blockers instead of silently waiting;
• cite task, tool, agent, or evidence records for final claims.

Agent Threads And Message Trace

SEED treats each dynamic team member as an agent-thread: a durable work thread with a role id, OpenCode session, mailbox, tool/skill/MCP policy, helper budget, memory, and trace. Helper child sessions are subordinate to one agent-thread; they are useful for bounded parallel work, but they are not top-level team members unless Lab-Representative promotes them.

Agent-to-agent prompts go through durable message envelopes. Delivery is then recorded as live promptAsync, mailbox-only, retry, or failure. Inspect:

• .seed-agent/runs/<run_id>/threads/threads.json
• .seed-agent/runs/<run_id>/threads/<thread_id>/tool-manifest.json
• .seed-agent/runs/<run_id>/threads/<thread_id>/helpers.jsonl
• .seed-agent/runs/<run_id>/messages/envelopes.json
• .seed-agent/runs/<run_id>/messages/delivery.jsonl
• .seed-agent/runs/<run_id>/team/conversation.jsonl
• .seed-agent/runs/<run_id>/context/bundles.json
• .seed-agent/runs/<run_id>/context/metrics.jsonl

Inside OpenCode, use seed_agent_thread_status, seed_agent_thread_trace, seed_message_queue, seed_message_read, seed_message_deliver, seed_context_bundle_list, seed_context_bundle_read, and seed_context_metrics when Lab-Representative needs to debug who called whom, with which prompt, tool policy, context refs, and delivery state.

SEED stores stable contracts, warm run/team summaries, hot mailbox/meeting deltas, heavy artifact refs, and memory checkpoints in the context ledger. Launch prompts can inline stable contract context once; later turns use digests or refs where possible. This keeps each agent-thread's role/tool prefix more stable for prompt-cache-friendly providers while preserving a readable audit trail.

Final completion is gated by evidence, workspace state, runtime lifecycle, and reported deliverable quality. If a final report mentions an HTML artifact, SEED reads the file and blocks completion on missing files, placeholder/TODO text, or unfinished runtime/helper/background work. This prevents incomplete artifacts from being marked completed.

Long Running Work

While a SEED run is running, type these commands directly into the OpenCode TUI:

/seed-status
/seed-lab-meeting

Useful behavior:

• /seed-status and /seed-lab-meeting are TUI-local SEED commands. They are not injected into the Lab-Representative prompt through OpenCode's server command path.
• /seed-status is a read-only status board. It shows the active run, agent-threads, sessions/background ids, helper child-session counts, recent checkpoints, sub-plans, budget state, context-ledger counts, trace refs, and activity paths without waking Lab-Representative or mutating the run.
• Activity briefings are written under .seed-agent/runs/<run_id>/activity/, including latest.md.
• /seed-lab-meeting is the only professor command that intentionally pauses a running SEED runtime. It blocks new queue/delegation/write work, lets already running background workers finish their assigned background sessions, and then has Lab-Representative report current results plus the remaining plan.

Use only the three professor-facing slash commands: /seed <goal>, /seed-status, and /seed-lab-meeting. Detailed report/trace/intervention flows remain available through run artifacts and SEED tools for Lab-Representative, but they are not registered as public slash commands.

Manual Lab Meeting

SEED no longer opens Lab Meetings automatically on a one-hour timer. A Lab Meeting starts only when the professor types:

/seed-lab-meeting

When already-running background sessions finish, SEED writes a meeting summary under the run directory, sets the run to awaiting_feedback, and keeps new internal delegation/team/write-lease work paused. The next normal chat message from the professor is recorded as Lab Meeting feedback, stored as professor memory, and used by Lab-Representative to resume and reschedule the remaining work. There is no separate resume slash command.

Run Artifacts

Each run writes files under:

.seed-agent/memory/
  MEMORY.md
  items/
.seed-agent/runs/<run_id>/
  run.json
  tasks.json
  events.jsonl
  agent_calls.jsonl
  model_calls.jsonl
  tool_calls.jsonl
  budget.json
  workspace/
    leases.json
    conflicts.json
    diffs.json
  idempotency/
    records.json
  meetings/
    state.json
    <meeting_id>.md
  evidence.md
  progress.md
  final_report.md
  activity/
    README.md
    latest.md
    latest.json
    <10-minute-window>.md
    raw/
  artifacts/

Markdown files are meant to be human-readable. JSON/JSONL files are the source of truth for reconstruction and audit. Trace payloads redact secrets, hidden model reasoning payloads, and raw host-tool output bodies by default.

To check whether SEED actually launched team members, inspect these artifacts. For a tiny smoke task, Lab-Representative may record a direct-work decision in seed_orchestrator_record_decision; in that case agent_calls.jsonl can stay empty and team/runtime.json may contain only the lead lab-representative. When a dynamic team is created, agent_calls.jsonl, team/runtime.json, team/launch-ledger.jsonl, and team/conversation.jsonl show member role ids, prompt summaries, session ids, and messages. team/conversation.jsonl is the primary ordered debug log for team traffic: entries include explicit from/to, launch ids, agent call ids, child session ids, prompt refs, allowed/denied tools, MCP/skill policy, and read/write path metadata when available. Inside OpenCode, use seed_team_conversation to read the same log.

Configuration

Project config lives at:

.opencode/seed-agent.jsonc

Common settings:

{
  "reporting": {
    "default_language": "ko"
  },
  "lab_meeting": {
    "enabled": false,
    "interval_minutes": 60
  },
  "activity_journal": {
    "enabled": true,
    "interval_minutes": 10
  },
  "permissions": {
    "execution_mode": "autonomous"
  },
  "skills": {
    "allow_project_skills": true,
    "allow_user_skills": false
  }
}

reporting.default_language controls the professor-facing runtime language, not only the final report. With ko, normal chat updates, progress.md, final_report.md, Lab Meeting notes, team summaries, and blockers are written in Korean. With en, those professor-facing outputs are written in English. Code, commands, file paths, API names, package names, and quoted source text are left unchanged.

permissions.execution_mode defaults to autonomous. Routine Lab-Representative edit/write/bash work is allowed so the professor is not a click bottleneck, but configured risky bash patterns such as recursive remove, hard reset, forced clean, dd, and filesystem formatting still ask for professor approval through OpenCode. Set it to interactive if you want OpenCode to ask for every edit/write/bash call.

Project skills can be placed in:

.seed-agent/skills/<name>/SKILL.md
.opencode/skills/<name>/SKILL.md
.agents/skills/<name>/SKILL.md

Personal user skill roots are disabled by default for reproducible project behavior.

The installer also adds a project-local .seed-agent/skills/using-superpowers skill. SEED disables OpenCode's native skill tool by default so global ~/.agents/skills entries do not leak into runs; reusable workflow guidance is loaded through SEED skill tools instead.

Internet lookup has two paths. OpenCode's native websearch and webfetch tools are allowed for Lab-Representative by default. SEED's optional websearch MCP is auto and becomes enabled when EXA_API_KEY or TAVILY_API_KEY is present before OpenCode starts. Dynamic team members can use search/fetch only when Lab-Representative grants those tools in their role contract.

OpenCode controls the TUI color theme and renders raw tool-call lines in its own style. For a high-signal audit view, inspect team/conversation.jsonl; SEED records explicit from -> to entries, prompt refs, child session ids, and the per-member session_tools map there.

For more details, see:

• docs/installation.md
• docs/cli.md
• docs/commands.md
• docs/configuration.md
• docs/architecture.md

Troubleshooting

Check the published package version:

npm view @seed-lab/opencode-seed-agent version

Reinstall the latest project config:

npx --yes @seed-lab/opencode-seed-agent@latest install --project

Run doctor:

npx --yes @seed-lab/opencode-seed-agent@latest doctor --project --agents

If OpenCode still opens on Build or Plan, check for parent OpenCode config files. OpenCode merges parent project configs too.

Examples:

cat ../.opencode/opencode.jsonc

Expected agent-list check:

opencode agent list

lab-representative (primary) should be present. build and plan should not appear in the SEED project agent list. OpenCode may still show its own maintenance agents such as compaction, summary, and title.

If doctor --agents says Lab-Representative is not visible, rerun the latest installer and restart OpenCode. As a manual fallback, make sure the project .opencode/opencode.jsonc contains these entries. For non-git workspaces, put the same entries in project-root opencode.jsonc as well:

{
  "plugin": ["@seed-lab/opencode-seed-agent"],
  "default_agent": "lab-representative",
  "agent": {
    "build": { "disable": true, "hidden": true },
    "plan": { "disable": true, "hidden": true },
    "general": { "disable": true, "hidden": true },
    "explore": { "disable": true, "hidden": true },
    "scout": { "disable": true, "hidden": true },
    "lab-representative": {
      "mode": "primary",
      "description": "Lab-Representative: professor-facing SEED Lab representative."
    }
  }
}

After a manual edit, restart OpenCode and rerun seed-agent doctor --agents.

If provider auth is missing, run:

opencode providers login -p <provider>

Examples include opencode providers login -p openai for GPT models and opencode providers login -p anthropic for Claude models.

Uninstall

For a project-local install, remove the SEED plugin entry from .opencode/opencode.jsonc, then remove .opencode/seed-agent.jsonc if you no longer need the project config.

Run artifacts are intentionally left in .seed-agent/runs/ for audit. Delete them only when you no longer need the trace history.

Maintainer Checks

For source checkout validation:

npm run verify
npm run canary:package
node ./bin/seed-agent.js doctor --project --agents

For a provider-backed smoke run:

node ./bin/seed-agent.js run --model anthropic/claude-sonnet-4-5 --variant high "Create a short SEED trace smoke test and stop after reporting the run directory."

Swap the provider/model for whatever OpenCode provider you have configured.