# Installation

SEED-agent is installed like an OpenCode plugin package, while model provider
authentication remains owned by OpenCode. Normal users run the installer in the
repository they want SEED to work on; they do not clone the SEED Harness source
repository or connect a local source checkout to OpenCode.

## Runtime Requirements

- Linux. This release is distributed and validated for Linux only; Windows and
  macOS are not supported yet.
- Node.js `>=20`
- OpenCode CLI `>=1.15.6`
- Tested OpenCode CLI: `1.15.7`

The OpenCode CLI is installed outside this package, so SEED-agent enforces
compatibility through `doctor`. If a user has an older OpenCode CLI,
`doctor` exits with failure before they start relying on `/seed`.

## For Humans

Paste this into your LLM agent session from the repository where you want
`/seed` to work:

```text
Install and configure SEED Harness for the current project. Keep SEED model-neutral unless I explicitly ask to pin a model. First verify OpenCode is installed, then run the @seed-lab/opencode-seed-agent installer for this project, tell me how to authenticate the OpenCode provider/model I want, run seed-agent doctor --project --agents, and tell me how to start /seed.
```

Or run the installer yourself:

```bash
cd <your-work-repo>
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
```

Inside OpenCode:

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

The installer registers a package plugin entry in OpenCode config and writes
SEED config for the current target project. It creates
`.opencode/opencode.jsonc` and `.opencode/seed-agent.jsonc` with model-neutral
SEED profiles, Lab-Representative, dynamic team tools, `/seed`, SEED MCP
defaults, and user skill roots disabled by default. By default, SEED inherits
the model selected in OpenCode for Lab-Representative. If a project wants to pin
one model for all SEED profiles, run the installer with `--model
provider/model`.
It also writes static project OpenCode agent and command entries instead of
relying only on the plugin config hook. The project config includes
`default_agent: "lab-representative"`, the Lab-Representative primary agent,
SEED command aliases, and disable stubs for native OpenCode `build`, `plan`,
`general`, `explore`, and `scout` entries unless host agents are explicitly
allowed.
For non-git workspaces, the installer writes the same OpenCode runtime defaults
to project-root `opencode.jsonc` as a compatibility config, because OpenCode may
load that file more reliably than walking into `.opencode/` before the project
has a git worktree.

After install, the OpenCode TUI should open on `Lab-Representative`. Dynamic
team member identities live in SEED run artifacts, not in the OpenCode agent
selector.

If OpenCode does not open on `Lab-Representative`, rerun the latest installer
in that target project:

```bash
npx @seed-lab/opencode-seed-agent@latest install --project
```

The installer normalizes the project SEED config to the current single
Lab-Representative shape and writes a `.bak-*` backup of the previous
`.opencode/seed-agent.jsonc`.

If Build/Plan still appears after reinstall, inspect parent directories for
inherited OpenCode config, for example `../.opencode/opencode.jsonc` or
another parent-directory OpenCode config. OpenCode merges parent project
configs, so a parent config can affect the current project.

## For LLM Agents

Follow these steps when helping a user install SEED Harness:

1. Check OpenCode:

   ```bash
   opencode --version
   ```

   If OpenCode is missing, ask the user to install it first from
   https://opencode.ai/docs. With npm available, the common install command is:

   ```bash
   npm install -g opencode-ai
   ```

2. Install SEED in the user's target repository. Do not clone the SEED Harness
   source repository for normal package installs.

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

3. Authenticate the provider the user wants to use through OpenCode:

   ```bash
   opencode providers login -p <provider>
   ```

4. Verify:

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

5. Start OpenCode and tell the user to run `/seed`.

## Maintainer Local Checkout

Use this flow only when developing or validating SEED Harness itself from an
unpublished local checkout:

```bash
cd seed-harness
npm install
npm run build
node ./bin/seed-agent.js install --local --project
opencode providers login -p <provider>
node ./bin/seed-agent.js doctor --project --agents
```

`install --local --project` updates the project `.opencode/opencode.jsonc`
plugin list, creates `.opencode/seed-agent.jsonc` if it is missing, and
prepares `.opencode` plugin runtime dependencies for OpenCode. The generated
SEED config is model-neutral by default, ignores personal SEED user config for
project installs, disables personal user skill roots, and does not merge
host/user MCP servers by default. It does not create a model provider, does not
read API key values, and does not register a mock model.

## Verify

```bash
npx --yes @seed-lab/opencode-seed-agent@latest doctor --project --agents
npx --yes @seed-lab/opencode-seed-agent@latest run --model anthropic/claude-sonnet-4-5 --variant high "Create a short SEED trace smoke test and stop after reporting the run directory."
```

The expected healthy state is:

- OpenCode CLI is installed.
- SEED plugin is present in `opencode.jsonc`.
- SEED config is present or defaults are acceptable.
- If SEED config pins explicit models, those configured providers are visible to
  `opencode providers list`. If SEED config is model-neutral, `doctor` reports
  that the OpenCode selected provider/model will be used at runtime.
- Lab-Representative is registered through the primary agent id
  `lab-representative`.
- Native `Build` and `Plan` should not appear in the SEED project agent list
  after a current isolated project install.
- Dynamic team members are stored in SEED run artifacts, not in the OpenCode
  agent selector.

For an unpublished local checkout, replace
`npx --yes @seed-lab/opencode-seed-agent@latest` with
`node ./bin/seed-agent.js`.

## Provider Keys

Every user should run provider login on their own machine:

```bash
opencode providers login -p <provider>
```

Examples include `opencode providers login -p openai` for GPT models and
`opencode providers login -p anthropic` for Claude models. SEED-agent relies on
OpenCode for provider credentials and does not store model API keys. The plugin
trace redacts secrets, reasoning payloads, and raw host-tool output bodies by
default.
