feat: {env:MY_VAR} support in the frontmatter of agent/command markdown files (resolves #5054, #5082)

packages/opencode/src/config/markdown.ts

@@ -68,11 +68,30 @@ export namespace ConfigMarkdown {
     return content.replace(frontmatter, () => processed)
   }
 
+  // Perform {env:VAR} interpolation on frontmatter data only
+  function interpolateEnvironmentVariables(obj: any): any {
+    if (typeof obj === "string") {
+      return obj.replace(/\{env:([^}]+)\}/g, (_, varName) => {
+        return process.env[varName] || ""
+      })
+    } else if (Array.isArray(obj)) {
+      return obj.map(interpolateEnvironmentVariables)
+    } else if (obj && typeof obj === "object") {
+      const result: any = {}
+      for (const [key, value] of Object.entries(obj)) {
+        result[key] = interpolateEnvironmentVariables(value)
+      }
+      return result
+    }
+    return obj
+  }
+
   export async function parse(filePath: string) {
     const template = await Filesystem.readText(filePath)
 
     try {
       const md = matter(template)
+      md.data = interpolateEnvironmentVariables(md.data)
       return md
     } catch {
       try {

packages/opencode/test/config/markdown.test.ts

@@ -226,3 +226,88 @@ describe("ConfigMarkdown: frontmatter has weird model id", async () => {
     expect(result.content.trim()).toBe("Strictly follow da rules")
   })
 })
+
+// Helper function to reduce test code duplication
+async function parseMarkdownWithEnv(markdown: string) {
+  const tempFile = `/tmp/test-agent-${Date.now()}.md`
+  await Bun.write(tempFile, markdown)
+  try {
+    return await ConfigMarkdown.parse(tempFile)
+  } finally {
+    await Bun.file(tempFile).delete()
+  }
+}
+
+// Tests for {env:VAR} interpolation in frontmatter
+test("should interpolate {env:VAR} in frontmatter", async () => {
+  process.env.TEST_MODEL = "gpt-4"
+  process.env.TEST_DESCRIPTION = "Test agent description"
+
+  const markdownWithEnv = `---
+description: "{env:TEST_DESCRIPTION}"
+model: "{env:TEST_MODEL}"
+mode: primary
+---
+
+# Agent Content
+
+This is the agent content.`
+
+  const result = await parseMarkdownWithEnv(markdownWithEnv)
+
+  expect(result.data.description).toBe("Test agent description")
+  expect(result.data.model).toBe("gpt-4")
+  expect(result.data.mode).toBe("primary")
+  expect(result.content).toContain("Agent Content")
+})
+
+test("should handle missing environment variables gracefully", async () => {
+  delete process.env.NONEXISTENT_VAR
+
+  const markdownWithMissingEnv = `---
+description: "Description with {env:NONEXISTENT_VAR} missing"
+model: "gpt-3.5-turbo"
+---
+
+# Agent Content`
+
+  const result = await parseMarkdownWithEnv(markdownWithMissingEnv)
+
+  expect(result.data.description).toBe("Description with  missing")
+  expect(result.data.model).toBe("gpt-3.5-turbo")
+})
+
+test("should interpolate multiple environment variables in same field", async () => {
+  process.env.PREFIX = "AI"
+  process.env.SUFFIX = "Assistant"
+
+  const markdownWithMultipleEnv = `---
+description: "{env:PREFIX} {env:SUFFIX}"
+model: "gpt-4"
+---
+
+# Agent Content`
+
+  const result = await parseMarkdownWithEnv(markdownWithMultipleEnv)
+
+  expect(result.data.description).toBe("AI Assistant")
+  expect(result.data.model).toBe("gpt-4")
+})
+
+test("should not interpolate {env:VAR} in markdown body content", async () => {
+  process.env.BODY_VAR = "should not appear"
+
+  const markdownWithEnvInBody = `---
+description: "Test agent"
+model: "gpt-4"
+---
+
+# Agent Content
+
+This should not interpolate: {env:BODY_VAR}`
+
+  const result = await parseMarkdownWithEnv(markdownWithEnvInBody)
+
+  expect(result.data.description).toBe("Test agent")
+  expect(result.content).toContain("{env:BODY_VAR}")
+})

packages/web/src/content/docs/agents.mdx

@@ -211,6 +211,45 @@ Provide constructive feedback without making direct changes.
 
 The markdown file name becomes the agent name. For example, `review.md` creates a `review` agent.
 
+#### Environment variables
+
+You can use environment variables in markdown agent frontmatter using the `{env:VAR_NAME}` syntax. This is useful for dynamic configuration, such as selecting models based on environment.
+
+```markdown title="~/.config/opencode/agents/flexible.md"
+---
+description: "Agent using environment-configured model"
+mode: primary
+model: "{env:OPENCODE_MODEL}"
+---
+
+Your prompt content here.
+```
+
+If the environment variable is not set, it will be replaced with an empty string.
+
+:::note
+Environment variable interpolation only applies to frontmatter fields, not to the markdown body content. This prevents accidental substitution of `{env:VAR}` patterns that may appear as examples or documentation in your prompt.
+:::
+
+This enables workflows like tiered model selection:
+
+```bash frame="none"
+# Set different models for different purposes
+export OPENCODE_HIGH_MODEL=anthropic/claude-opus-4-5
+export OPENCODE_MID_MODEL=anthropic/claude-sonnet-4-20250514
+export OPENCODE_LOW_MODEL=anthropic/claude-haiku-4-20250514
+```
+
+Then reference them in your agents:
+
+```markdown title="~/.config/opencode/agents/planner.md"
+---
+description: "High-capability planning agent"
+mode: primary
+model: "{env:OPENCODE_HIGH_MODEL}"
+---
+```
+
 ---
 
 ## Options