opencode-local-context

Inject developer-local Markdown context into OpenCode agents and resolve explicit OpenCode-style {env:NAME} placeholders in prompts.

Requires OpenCode 2—the OpenCode 1 plugin API is not supported—and runs as type-stripped TypeScript on Node 26+.

TL;DR

Think of it as .env for your agents: keep developer- or machine-specific context out of shared AGENTS.md and agent definitions.

Create .opencode/context.local.md in your project:

# My local context

- My team is {env:TEAM_NAME}.
- My issue tracker project is {env:ISSUE_PROJECT}.
- My local service runs at http://localhost:3000.

Start OpenCode with those environment variables available:

TEAM_NAME="team-analytics" ISSUE_PROJECT="big-platform" opencode

The resolved Markdown is included in your agents' context, while the local file can remain uncommitted. Use context.<agent>.local.md when context should apply to one configured agent only.

The .env comparison is a mental model: this plugin does not load .env files. It reads local Markdown and resolves {env:NAME} from OpenCode's existing environment. Because resolved values are sent to the model, use this only for non-secret context—never tokens, passwords, or credentials.

Use it for information that is useful to your local agent sessions but should not live in shared instructions: your team, development environment, issue-tracker project, preferred test device, or other developer-specific context.

Features

• Adds .opencode/context.local.md to every assembled system prompt—the agent loop and OpenCode's internal compaction, generate, and title requests alike.
• Adds .opencode/context.<agent>.local.md only to that agent's configured prompt.
• Supports Markdown and file-based agent definitions that carry their own prompt.
• Resolves {env:NAME} in assembled system prompts, general and per-agent local context, and configured agent prompts and descriptions.
• Reads only explicitly referenced environment variables. It never copies the whole environment into a prompt.
• Reads context files once at plugin startup, not on every model call.
• Its only dependency is @opencode/plugin.

Install

Add the package to the plugins array in opencode.json or opencode.jsonc:

{
	"$schema": "https://opencode.ai/config.json",
	"plugins": ["opencode-local-context"]
}

To pass options, use the object form:

{
	"$schema": "https://opencode.ai/config.json",
	"plugins": [
		{
			"package": "opencode-local-context",
			"options": { "missingEnv": "warn" }
		}
	]
}

Default files

Files are resolved from the project's canonical checkout by default, so nested OpenCode working directories share the same predictable project-level context:

your-project/
└── .opencode/
    ├── context.local.md
    ├── context.build.local.md
    └── context.review.local.md

context.local.md is appended as a separate system-prompt block to every request kind.

context.<agent>.local.md is appended to only the matching agent's explicit prompt. For example, context.review.local.md applies to an agent configured as review in opencode.json or loaded from .opencode/agents/review.md.

The plugin deliberately does not create or replace prompts for built-in or promptless agents. Doing so would replace OpenCode's built-in provider or specialized agent instructions rather than append to them. General local context still applies to every agent.

All files are optional. An absent context directory or absent files are silent no-ops.

Example

.opencode/context.local.md:

# Local developer context

- My team is {env:TEAM_NAME}.
- My local service URL is {env:LOCAL_SERVICE_URL}.
- Prefer examples for my time zone: {env:TIME_ZONE}.

.opencode/context.review.local.md:

When reviewing, pay extra attention to backwards compatibility with my local
integration branch.

A generic team or issue-tracker context is equally valid—the plugin has no tracker-specific logic:

- Team: {env:TEAM_NAME}
- Issue tracker project: {env:ISSUE_PROJECT}
- Current iteration: {env:ITERATION_NAME}

Environment interpolation

The supported syntax is {env:NAME}, where NAME matches a normal environment variable name (A-Z, a-z, digits after the first character, and _). For example:

Use the local account for {env:DEVELOPER_EMAIL}.

Interpolation covers:

1. every text part of OpenCode's assembled system prompt, including AGENTS.md, global instructions, and custom instructions;
2. general and per-agent local context;
3. configured agent prompt and description values.

Only names that occur in placeholders are read from process.env.

Missing variables

missingEnv controls references to variables that are not set:

| Value | Behavior | | ------- | --------------------------------------------------------------------- | | error | Default. Throw a clear error naming the variable and prompt source. | | warn | Substitute "" and log one warning per variable to the OpenCode logs. | | empty | Silently substitute "". |

The warn policy deduplicates warnings for the plugin lifetime, avoiding a warning on every model call. Warnings go to console.warn, which OpenCode captures into its logs.

Set interpolate to false to leave all {env:NAME} placeholders unchanged.

[!WARNING] Interpolated values become part of the prompt and are sent to the configured model provider. Never interpolate API tokens, passwords, private keys, credentials, or other secrets. This plugin limits environment access to explicitly referenced variables, but it cannot make a secret safe after you reference it.

Options

All options are optional and validated at startup.

| Option | Type | Default | Description | | ------------------ | ------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------- | | root | "worktree" \| "directory" | "worktree" | Base for a relative contextDir: the canonical checkout or the working directory. | | contextDir | string | ".opencode" | Context directory. Absolute paths are accepted. | | generalFile | string | "context.local.md" | General context filename within contextDir. | | agentFilePattern | string containing {agent} once | "context.{agent}.local.md" | Pattern used to discover per-agent files. Must be a filename, not a path. | | missingEnv | "error" \| "warn" \| "empty" | "error" | Missing environment-variable policy. | | interpolate | boolean | true | Enables {env:NAME} interpolation. |

Example with a directory relative to OpenCode's active directory:

{
	"$schema": "https://opencode.ai/config.json",
	"plugins": [
		{
			"package": "opencode-local-context",
			"options": {
				"root": "directory",
				"contextDir": ".developer-context",
				"generalFile": "all.md",
				"agentFilePattern": "agent-{agent}.md",
				"missingEnv": "warn"
			}
		}
	]
}

Programmatic API

The package default-exports the OpenCode 2 plugin definition; the same object is also a named export:

import localContext, { LocalContextPlugin } from "opencode-local-context";

Lifecycle

OpenCode loads configuration, agents, and plugins at startup. This plugin snapshots local context files during plugin startup and interpolates them immediately. Changes to context files, plugin options, or relevant environment variables require quitting and restarting OpenCode.

Per-agent context is applied through an agent transform, so it targets only agents that carry an explicit prompt; files for built-in or promptless agents are ignored to avoid replacing OpenCode's own instructions. The general context and the assembled-system interpolation are registered for every request kind—context, compaction, generate, and title—so OpenCode's internal model calls see them too.

Development

The package is published as type-stripped TypeScript source and loaded directly by OpenCode. There is no transpilation, bundling, generated declaration output, or build step.

npm install
npm run check

npm run check verifies formatting, lint, strict TypeScript, and the test suite (node --test). Agents should run npm run agentic:verify instead: it applies Biome's autofixes first, then runs the same typecheck and tests.

License

MIT