feat(opencode): Added {env:VAR} substitution to markdown-based config parsing #9261

Eric-Guo · 2026-01-18T15:49:53Z

The key difference between this PR and #5092 is this PR allow ENV usage in markdown body.

I already including a real use case in document and give the warning of security concerns.

Notice current json configuration of prompt allow using ENV, so I think using ENV in markdown body should also allowed.

Other coding agent like kimi-cli using ENV in their system prompt, so security concerns is not as serious as the first sight.

github-actions · 2026-01-18T15:50:27Z

The following comment was made by an LLM, it may be inaccurate:

Potential Duplicate Found:

PR feat: {env:MY_VAR} support in the frontmatter of agent/command markdown files (resolves #5054, #5082) #5092: "feat: {env:MY_VAR} support in the frontmatter of agent/command markdown files (resolves [FEATURE]: {env:MY_VAR} support in agent yaml #5054, [FEATURE]: allow shell commands in the frontmatter #5082)"
feat: {env:MY_VAR} support in the frontmatter of agent/command markdown files (resolves #5054, #5082) #5092

Why they're related: Both PRs address the same issue (#5054) and implement the exact same feature: {env:VAR} substitution support in markdown-based configuration files. PR #5092 appears to have already resolved this issue, so PR #9261 may be a duplicate.

Copilot

Pull request overview

This pull request adds environment variable substitution functionality to markdown-based agent configuration parsing. Users can now use the {env:VAR_NAME} syntax in both frontmatter and prompt content of markdown agent files, with unset variables being replaced with empty strings.

Changes:

Added substituteEnv() function to perform environment variable replacement using {env:VAR} syntax
Integrated environment variable substitution into the markdown parsing pipeline
Added comprehensive test coverage for the new functionality including edge cases
Updated documentation with usage examples and security guidance

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
packages/opencode/src/config/markdown.ts	Implements the `substituteEnv` function and integrates it into the parse pipeline
packages/opencode/test/config/markdown.test.ts	Adds comprehensive test suite with proper environment variable setup/teardown
packages/opencode/test/config/fixtures/env-frontmatter.md	Test fixture demonstrating env var substitution in both frontmatter and content
packages/web/src/content/docs/agents.mdx	Documents the new feature with usage examples and security considerations

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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

ariane-emory · 2026-01-18T17:38:42Z

After consultation with a couple of models and further review of the code changes, I do believe that I have come to the conclusion that my take in #5092 does adhere more closely to the original requestor of the Issue's request in #5054 to provide replacement only in the YAML/frontmatter. The version here does expand the scope slightly by providing replacement throughout the body as well.

Whether this expansion in scope is desirable or not I'll leave to the maintainers to decide as I don't hold any strong opinion on that aspect myself.

In any case, either PR seems that it would give the original requestor the ability to do what they wanted to do surely the resolution of their issue would provide them with a pleasant surprise - and if they're happy, so am I, so hopefully one of these PRs will come in to a safe landing.

Eric-Guo · 2026-01-18T17:43:53Z

Thanks your review, I update the document with my real usage, I need ENV in markdown body, so hoping this PR can be choosen. (otherwise, I have to write the prompt in jsonc....)

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-18T17:55:16Z

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

+describe("ConfigMarkdown: env substitution", () => {
+  const tokenKey = "TEST_MCP_TOKEN"
+  const emptyKey = "EMPTY_ENV_VAR"
+  const prevToken = process.env[tokenKey]
+  const prevEmpty = process.env[emptyKey]
+  let parsed: Awaited<ReturnType<typeof ConfigMarkdown.parse>>
+
+  beforeAll(async () => {
+    process.env[tokenKey] = "abc123"
+    delete process.env[emptyKey]
+    parsed = await ConfigMarkdown.parse(import.meta.dir + "/fixtures/env-frontmatter.md")
+  })
+
+  afterAll(() => {
+    if (prevToken === undefined) delete process.env[tokenKey]
+    else process.env[tokenKey] = prevToken
+    if (prevEmpty === undefined) delete process.env[emptyKey]
+    else process.env[emptyKey] = prevEmpty
+  })
+
+  test("should substitute env vars in frontmatter", () => {
+    expect(parsed.data.description).toBe("Token is abc123")
+  })
+
+  test("should substitute missing env vars with empty string in frontmatter", () => {
+    expect(parsed.data.note).toBe("")
+  })
+
+  test("should substitute env vars in content", () => {
+    expect(parsed.content).toContain("Token: abc123")
+    expect(parsed.content).toContain("Missing: ")
+  })
+})


The test only verifies that env variables are replaced with their values or empty strings, but doesn't test edge cases like nested braces, malformed patterns, or special characters in variable names. Consider adding test cases for: 1) Multiple substitutions in the same line, 2) Variables with underscores and numbers, 3) Malformed patterns like {env:} or {env:VAR with spaces}, 4) Variables that contain special regex characters.

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

Copilot · 2026-01-18T17:55:16Z

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

+```markdown title="~/.config/opencode/agents/mcdonalds.md"
+---
+name: "McDonalds"
+description: Agent to help you ordering McDonalds


The description contains a grammatical error. It should be "Agent to help you order from McDonalds" instead of "Agent to help you ordering McDonalds".

Suggested change

description: Agent to help you ordering McDonalds

description: Agent to help you order from McDonalds

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

ariane-emory · 2026-01-18T17:58:21Z

@Eric-Guo I expect that surely you must already be aware, but just in case: you can of course already achieve your terminal goal of using environment variable in the body by using shell expansions. It's not a markedly efficient way to do it, of course, since we're starting a whole shell just to get at an environment variable, but it does work, so it could perhaps suffice in the meantime.

Best of luck!

Eric-Guo · 2026-01-18T18:13:16Z

you can of course already achieve your terminal goal of using environment variable in the body by using shell expansions.

How to do that? I don't know it can, seems not mention in document.

It sounds useful but more crazy and less security (of course)...

But if I can do that, this PR is no need. 😊

ariane-emory · 2026-01-18T18:22:43Z

You would do what is shown here: https://opencode.ai/docs/commands/#shell-output

Simply use a command such as echo ${SOME_ENVIRONMENT_VARIABLE}, as I show here in one of my own test commands (https://github.com/ariane-emory/opencode-config-supplemental/blob/main/command-disabled/debug-env.md):

As stated previously, it's probably not the most efficient way to do it, but it should work.

Eric-Guo · 2026-01-19T01:17:48Z

What I known is command is need to trigger by user, anyway to let the command being triggerd automatically at starting, without user need to do any action? i.e. system prompt can calling command directly?

If answer is no, it's more my need....

ariane-emory · 2026-01-19T03:25:16Z

The commands in the shell expansions run each time you run the slash command. This is in most cases beneficial: after all, if you run the date command, you want the current date every time and if you run ls to see the files in a directory you presumably want to know what files are there right now, not what files used to be there an hour ago during startup. This probably isn't usually so important for echoing environment variables that are in most cases unlikely to change during runtime, but there could perhaps be some corner case that I'm overlooking. No, slash commands cannot be called mechanically by system prompts, they are meant to be invoked by the user.

…ng sent back as assistant message content (anomalyco#11270) Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>

…nt definitions in .md now get env values injected before frontmatter/prompt parsing.

Copilot AI review requested due to automatic review settings January 18, 2026 15:49

Copilot started reviewing on behalf of Eric-Guo January 18, 2026 15:50 View session

Copilot AI reviewed Jan 18, 2026

View reviewed changes

packages/web/src/content/docs/agents.mdx Outdated Show resolved Hide resolved

Eric-Guo mentioned this pull request Jan 18, 2026

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

Open

Eric-Guo force-pushed the substitute_env_in_markdown branch from f7bf935 to b4be2bf Compare January 18, 2026 17:35

Eric-Guo force-pushed the substitute_env_in_markdown branch from b4be2bf to db8a8c2 Compare January 18, 2026 17:41

Eric-Guo force-pushed the substitute_env_in_markdown branch from db8a8c2 to fbccf01 Compare January 18, 2026 17:48

Eric-Guo requested a review from Copilot January 18, 2026 17:52

Copilot started reviewing on behalf of Eric-Guo January 18, 2026 17:53 View session

Copilot AI reviewed Jan 18, 2026

View reviewed changes

Eric-Guo force-pushed the substitute_env_in_markdown branch from c675b6e to 39dcd7b Compare January 19, 2026 01:11

Eric-Guo force-pushed the substitute_env_in_markdown branch 6 times, most recently from 6d02317 to 2fcd86e Compare January 22, 2026 02:53

Eric-Guo mentioned this pull request Jan 22, 2026

[FEATURE]: {env:MY_VAR} support in agent yaml #5054

Open

1 task

Eric-Guo force-pushed the substitute_env_in_markdown branch 4 times, most recently from d5e033a to 9cfdf94 Compare January 28, 2026 07:02

Eric-Guo force-pushed the substitute_env_in_markdown branch 3 times, most recently from 4cc021c to becedb8 Compare January 29, 2026 11:45

thdxr force-pushed the dev branch from cbab81f to 2d3c7a0 Compare January 30, 2026 04:49

opencode and others added 3 commits January 30, 2026 06:48

release: v1.1.45

e1e356c

fix: rm ai sdk middleware that was preventing <think> blocks from bei…

00637c0

…ng sent back as assistant message content (anomalyco#11270) Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>

Added {env:VAR} substitution to markdown-based config parsing, so age…

60905d0

…nt definitions in .md now get env values injected before frontmatter/prompt parsing.

Eric-Guo force-pushed the substitute_env_in_markdown branch from becedb8 to 60905d0 Compare January 30, 2026 07:27

opencode-agent bot force-pushed the dev branch from 00637c0 to 71e0ba2 Compare January 30, 2026 14:32

thdxr force-pushed the dev branch from f1ae801 to 71e0ba2 Compare January 30, 2026 14:35

thdxr requested a review from adamdotdevin as a code owner January 30, 2026 14:35

thdxr force-pushed the dev branch 2 times, most recently from f1ae801 to 08fa7f7 Compare January 30, 2026 14:37

	description: Agent to help you ordering McDonalds
	description: Agent to help you order from McDonalds

feat(opencode): Added {env:VAR} substitution to markdown-based config parsing #9261

Are you sure you want to change the base?

feat(opencode): Added {env:VAR} substitution to markdown-based config parsing #9261

Uh oh!

Conversation

Eric-Guo commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

ariane-emory commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Eric-Guo commented Jan 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ariane-emory commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Eric-Guo commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ariane-emory commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Eric-Guo commented Jan 19, 2026

Uh oh!

ariane-emory commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Eric-Guo commented Jan 18, 2026 •

edited

Loading

ariane-emory commented Jan 18, 2026 •

edited

Loading

ariane-emory commented Jan 18, 2026 •

edited

Loading

Eric-Guo commented Jan 18, 2026 •

edited

Loading

ariane-emory commented Jan 18, 2026 •

edited

Loading

ariane-emory commented Jan 19, 2026 •

edited

Loading