anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 10:15:31 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

[FEATURE]: Improve Subagent Invocation Documentation #2463

New Issue
Open
opened 2026-02-16 17:35:45 -05:00 by yindo · 5 comments
yindo commented 2026-02-16 17:35:45 -05:00
Owner
Copy Link
Copy Source

Originally created by @mossbergmaverick on GitHub (Nov 1, 2025).

Originally assigned to: @jayair on GitHub.

Feature hasn't been suggested before.

  • I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

The current documentation explains that subagents can be invoked automatically or manually, but doesn't clearly explain how to write agent prompts for automatic invocation when creating agents via markdown files.

From the docs:

Subagents can be invoked:

  • Automatically by primary agents for specialized tasks based on their descriptions.
  • Manually by @ mentioning a subagent in your message.

What's unclear for users creating agents via .md files:

  • Should primary agents use @subagent-name or just subagent-name in their system prompts?
  • What syntax should be written in the markdown body of primary agent files?
  • How does the automatic invocation mechanism work?

Context

This issue specifically concerns users who create agents using markdown files in:

  • ~/.config/opencode/agent/
  • .opencode/agent/

The confusion is about what to write in the markdown body (system prompt), not the frontmatter configuration.

Expected vs Actual Behavior

User possible expectation based on docs:

# .opencode/agent/test-agent.md
---
description: Test agent
mode: primary
---
Example: "@test-subagent create a test file"

What actually works:

# .opencode/agent/test-agent.md
---
description: Test agent
mode: primary
---
Example: "test-subagent create a test file"

The @ prefix is only for manual user invocation, not for automatic agent-to-agent invocation in system prompts.

Suggested Documentation Improvement

Add a clear example in the Agents section showing the difference:

Proposed addition:

Subagent Invocation

Subagents can be invoked in two ways:

1. Automatic Invocation (by primary agents)

When creating agents via markdown files, primary agents invoke subagents by mentioning their name without @ in the system prompt:

Primary agent file (~/.config/opencode/agent/delegator.md):

---
description: Main development agent that delegates tasks
mode: primary
tools:
  write: false
---

You delegate file creation to the file-writer subagent.
When user requests file creation, invoke it like this:
"file-writer create the requested file"

NOT like this: "@file-writer create file"  # @ is only for manual user invocation

Subagent file (~/.config/opencode/agent/file-writer.md):

---
description: Creates and manages files
mode: subagent
tools:
  write: true
---

You create files as requested.

2. Manual Invocation (by users)

Users invoke subagents directly in the TUI using @:

@file-writer create test.txt with content "hello"

Technical Note

Subagents appear as available tools to primary agents based on their description. The primary agent decides when to invoke them based on the task context. In the agent's system prompt (markdown body), reference subagents by name only, without the @ prefix.

Additional Examples for Markdown Agent Files

Example 1: Testing Agent

# .opencode/agent/developer.md

---
description: Main development agent
mode: primary
tools:
  write: false
---
Delegate test creation to test-writer subagent:
"test-writer generate tests for this code"

# .opencode/agent/test-writer.md

---
description: Writes unit and integration tests
mode: subagent
tools:
  write: true
---
You write comprehensive tests for the code provided.

Example 2: Security Review

# Primary agent markdown body
When security review is requested, invoke the subagent:
"security-auditor analyze this code for vulnerabilities"

# Correct ✅
"security-auditor analyze code"

# Incorrect ❌ (@ is for manual user invocation only)
"@security-auditor analyze code"

Related Documentation Files

  • /docs/agents/
  • Specifically the "Usage" and "Markdown" sections

Impact

This clarification would help users who create agents via markdown files:

  • Understand the difference between automatic and manual invocation syntax
  • Write correct agent system prompts in markdown files
  • Avoid confusion with @ syntax when writing agent instructions
Originally created by @mossbergmaverick on GitHub (Nov 1, 2025). Originally assigned to: @jayair on GitHub. ### Feature hasn't been suggested before. - [x] I have verified this feature I'm about to request hasn't been suggested before. ### Describe the enhancement you want to request ## Problem The current documentation explains that subagents can be invoked automatically or manually, but doesn't clearly explain **how** to write agent prompts for automatic invocation **when creating agents via markdown files**. From the docs: > Subagents can be invoked: > > - Automatically by primary agents for specialized tasks based on their descriptions. > - Manually by @ mentioning a subagent in your message. **What's unclear for users creating agents via `.md` files:** - Should primary agents use `@subagent-name` or just `subagent-name` in their system prompts? - What syntax should be written in the markdown body of primary agent files? - How does the automatic invocation mechanism work? ## Context This issue specifically concerns users who create agents using markdown files in: - `~/.config/opencode/agent/` - `.opencode/agent/` The confusion is about what to write in the **markdown body** (system prompt), not the frontmatter configuration. ## Expected vs Actual Behavior **User possible expectation based on docs:** ```markdown # .opencode/agent/test-agent.md --- description: Test agent mode: primary --- Example: "@test-subagent create a test file" ``` **What actually works:** ```markdown # .opencode/agent/test-agent.md --- description: Test agent mode: primary --- Example: "test-subagent create a test file" ``` The `@` prefix is only for **manual user invocation**, not for automatic agent-to-agent invocation in system prompts. ## Suggested Documentation Improvement Add a clear example in the **Agents** section showing the difference: ### Proposed addition: ## Subagent Invocation Subagents can be invoked in two ways: ### 1. Automatic Invocation (by primary agents) When creating agents via markdown files, primary agents invoke subagents by mentioning their name **without @** in the system prompt: **Primary agent file** (`~/.config/opencode/agent/delegator.md`): ```markdown --- description: Main development agent that delegates tasks mode: primary tools: write: false --- You delegate file creation to the file-writer subagent. When user requests file creation, invoke it like this: "file-writer create the requested file" NOT like this: "@file-writer create file" # @ is only for manual user invocation ``` **Subagent file** (`~/.config/opencode/agent/file-writer.md`): ```markdown --- description: Creates and manages files mode: subagent tools: write: true --- You create files as requested. ``` ### 2. Manual Invocation (by users) Users invoke subagents directly in the TUI using **@**: ``` @file-writer create test.txt with content "hello" ``` ### Technical Note Subagents appear as available tools to primary agents based on their `description`. The primary agent decides when to invoke them based on the task context. In the agent's system prompt (markdown body), reference subagents by name only, without the `@` prefix. ## Additional Examples for Markdown Agent Files ### Example 1: Testing Agent `# .opencode/agent/developer.md` ```markdown --- description: Main development agent mode: primary tools: write: false --- Delegate test creation to test-writer subagent: "test-writer generate tests for this code" ``` `# .opencode/agent/test-writer.md` ```markdown --- description: Writes unit and integration tests mode: subagent tools: write: true --- You write comprehensive tests for the code provided. ``` ### Example 2: Security Review ```markdown # Primary agent markdown body When security review is requested, invoke the subagent: "security-auditor analyze this code for vulnerabilities" # Correct ✅ "security-auditor analyze code" # Incorrect ❌ (@ is for manual user invocation only) "@security-auditor analyze code" ``` ## Related Documentation Files - `/docs/agents/` - Specifically the "Usage" and "Markdown" sections ## Impact This clarification would help users who create agents via markdown files: - Understand the difference between automatic and manual invocation syntax - Write correct agent system prompts in markdown files - Avoid confusion with `@` syntax when writing agent instructions
yindo added the discussiondocumentation labels 2026-02-16 17:35:45 -05:00
yindo commented 2026-02-16 17:35:45 -05:00
Author
Owner
Copy Link
Copy Source

@JayGhiya commented on GitHub (Nov 2, 2025):

post upgrade to v1 i am not able to invoke them manually is this expected @mossbergmaverick ?

@JayGhiya commented on GitHub (Nov 2, 2025): post upgrade to v1 i am not able to invoke them manually is this expected @mossbergmaverick ?
yindo commented 2026-02-16 17:35:45 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Nov 3, 2025):

@JayGhiya we are gonna update that

@rekram1-node commented on GitHub (Nov 3, 2025): @JayGhiya we are gonna update that
yindo commented 2026-02-16 17:35:45 -05:00
Author
Owner
Copy Link
Copy Source

@johnr14 commented on GitHub (Nov 7, 2025):

I would like to know how the the sub-agent communicates back with the agent that called it.

Does the subagent return the last message, the whole context or nothing ?
Could that be customizable with a return: all|last|compact|validator config ?

Example :
  • plan agent calls plan-drafter subagent with instructions on what to plan
    • plan-drafter will :
      • decide to investigate current code using plan-code or plan-doc to plan what files need modifications
      • receive the plan produced by the subagent and decide if more investigation is needed
      • call subagent plan-project with the previous produced plan to enhance and correct the plan with any specific instructions related to the project instructions. Returns a plan that is coherent with the project's convention
      • review plan draft and check if any refactoring is needed before passing it back to plan agent
  • plan will ask user if the plan-draft is ok or if there are any changes requiring calling back plan-drafter
  • plan will send the plan to sub-agent plan-manager that will write the plan to a file

The thing is that subagents can quickly fill their context up and that's better than the main agent busting it's context.
But they should be able to provide context back like a function would return.
There are no clear information in the documentation about this.

A build in tool like return could also be called when a subagent has finished so it can write it's return message like : `status=COMPLETED|FAILED,message="".

While at it, a validator agent could be specified to validate that the agent was successful. It could be validator: simple-validator config. The validator could read the last message or use a tool call to read last N messages if it isn't sure. The validator would return COMPLETED or FAILED and a description of what went wrong.

Is it possible to change/append to the system_prompt for a model in the config ?
I like to force tags on Kimi Linear, seems to help it a bit.

Also, is there a way to have a scratch pad for the agents ? Something like the todo list.

Could we get a document that will never be duplicated in the discussion ? Any changes to it would be lost or would require a rollback for the llm. The user could consult it's versions and start a new session with what he considers the best iteration or revert to it in the current session. I think this would help context, might not be for all cases.

Also it would be nice to ask the llm about opencode. I would propose the command /opencode ask that would have access to the opencode documentation and answer.

Example:
/opencode how can I limit a agent to generate at most 3000 tokens per interaction
@build I would like to limit agent-somename to 3000 tokens and change context limit to 32000.

Session name: Why is is always New session ?
Could it be updated to a short description like [plan] plan the new super feature... the first characters of the first command of the session with the original agent/command ?

Thanks

@johnr14 commented on GitHub (Nov 7, 2025): I would like to know how the the sub-agent communicates back with the agent that called it. Does the subagent return the last message, the whole context or nothing ? Could that be customizable with a `return: all|last|compact|validator` config ? <details> <summary>Example : </summary> - `plan` agent calls `plan-drafter` subagent with instructions on what to plan - `plan-drafter` will : - decide to investigate current code using `plan-code` or `plan-doc` to plan what files need modifications - receive the plan produced by the subagent and decide if more investigation is needed - call subagent `plan-project` with the previous produced plan to enhance and correct the plan with any specific instructions related to the project instructions. Returns a plan that is coherent with the project's convention - review plan draft and check if any refactoring is needed before passing it back to `plan` agent - `plan` will ask user if the plan-draft is ok or if there are any changes requiring calling back `plan-drafter` - `plan` will send the plan to sub-agent `plan-manager` that will write the plan to a file </details> The thing is that subagents can quickly fill their context up and that's better than the main agent busting it's context. But they should be able to provide context back like a function would return. There are no clear information in the documentation about this. A build in tool like `return` could also be called when a subagent has finished so it can write it's return message like : `status=COMPLETED|FAILED,message="". While at it, a validator agent could be specified to validate that the agent was successful. It could be `validator: simple-validator` config. The validator could read the last message or use a tool call to read last N messages if it isn't sure. The validator would return COMPLETED or FAILED and a description of what went wrong. ---- Is it possible to change/append to the `system_prompt` for a model in the config ? I like to force <think> tags on Kimi Linear, seems to help it a bit. ---- Also, is there a way to have a `scratch pad` for the agents ? Something like the todo list. Could we get a document that will never be duplicated in the discussion ? Any changes to it would be lost or would require a rollback for the llm. The user could consult it's versions and start a new session with what he considers the best iteration or revert to it in the current session. I think this would help context, might not be for all cases. ---- Also it would be nice to ask the llm about opencode. I would propose the command `/opencode ask` that would have access to the opencode documentation and answer. Example: `/opencode how can I limit a agent to generate at most 3000 tokens per interaction` `@build I would like to limit agent-somename to 3000 tokens and change context limit to 32000`. ---- Session name: Why is is always `New session` ? Could it be updated to a short description like `[plan] plan the new super feature...` the first characters of the first command of the session with the original agent/command ? Thanks
yindo commented 2026-02-16 17:35:45 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Nov 7, 2025):

@johnr14

Does the subagent return the last message

It returns the last text message it had.

Is it possible to change/append to the system_prompt for a model in the config ?
I like to force tags on Kimi Linear, seems to help it a bit.

Not currently , you can use AGENTS.md or a prompt for an agent but we don't really allow this specifically for a model across everything

Also it would be nice to ask the llm about opencode. I would propose the command /opencode ask that would have access to the opencode documentation and answer.

I kinda like this idea because then it is less intruisive and we dont have to throw stuff in the system prompt everywhere

Session name: Why is is always New session ?
Could it be updated to a short description like [plan] plan the new super feature... the first characters of the first command of the session with the original agent/command ?

It's not supposed to be... What model / provider are you using?

@rekram1-node commented on GitHub (Nov 7, 2025): @johnr14 > Does the subagent return the last message It returns the last text message it had. > Is it possible to change/append to the system_prompt for a model in the config ? I like to force tags on Kimi Linear, seems to help it a bit. Not currently , you can use AGENTS.md or a prompt for an agent but we don't really allow this specifically for a model across everything > Also it would be nice to ask the llm about opencode. I would propose the command /opencode ask that would have access to the opencode documentation and answer. I kinda like this idea because then it is less intruisive and we dont have to throw stuff in the system prompt everywhere > Session name: Why is is always New session ? Could it be updated to a short description like [plan] plan the new super feature... the first characters of the first command of the session with the original agent/command ? It's not supposed to be... What model / provider are you using?
yindo commented 2026-02-16 17:35:45 -05:00
Author
Owner
Copy Link
Copy Source

@johnr14 commented on GitHub (Nov 7, 2025):

@rekram1-node

Is it possible to change/append to the system_prompt for a model in the config ?
I like to force tags on Kimi Linear, seems to help it a bit.

Not currently , you can use AGENTS.md or a prompt for an agent but we don't really allow this specifically for a model across everything

hmm, could be done with config ?

{
    "$schema": "https://opencode.ai/config.json",
    "provider": {
        "llamacpp": {
            "npm": "@ai-sdk/openai-compatible",
            "name": "llamacpp (local)",
            "options": {
                "baseURL": "http://192.168.1.132:8112/v1"
            },
            "models": {
                "DeepCogito-109b": {
                    "name": "DeepCogito-109b local",
                    "system_prompt": "CUSTOM PROMPT",
                },
            }
        },
        "vllm":{  
            "npm": "@ai-sdk/openai-compatible",
            "name": "vllm (local)",
            "options": {
                "baseURL": "http://192.168.1.132:8111/v1",
                "apiKey": "local"
                },
            "models": {
                "Kimi-Linear-48B-A3B-Instruct": {
                "name": "Kimi-Linear-48B-A3B-Instruct",
                "system_prompt_prepend": "INSTRUCTIONS HERE AT TOP",
                "system_prompt_append": "INSTRUCTIONS HERE AT BOTTOM",
                },
            }
        }
    },
    "model": "Kimi-Linear-48B-A3B-Instruct",
    "small_model": "Kimi-Linear-48B-A3B-Instruct"
}

Also it would be nice to ask the llm about opencode. I would propose the command /opencode ask that would have access to the opencode documentation and answer.

I kinda like this idea because then it is less intruisive and we dont have to throw stuff in the system prompt everywhere

You might add some docs with FAQ, implementation details (tutorial, examples, explanations), release notes. That could save time and be quite useful. I would process all github issues for most asked questions and check that the generated answer is right. Then bundle that in a few FAQ files by component (agents/tools/tui/etc.) in the doc and there you go. Limit file access to .opencode/docs for the command /opencode and provide list of files and a summary of what they contain in a README.md index.

Session name: Why is is always New session ?
Could it be updated to a short description like [plan] plan the new super feature... the first characters of the first command of the session with the original agent/command ?

It's not supposed to be... What model / provider are you using?

Kimi-Linear, only running opencode locally, didn't try API. Sorry then, but a fail-safe would be great when using smaller models.

@johnr14 commented on GitHub (Nov 7, 2025): @rekram1-node > > Is it possible to change/append to the system_prompt for a model in the config ? > > I like to force tags on Kimi Linear, seems to help it a bit. > > Not currently , you can use AGENTS.md or a prompt for an agent but we don't really allow this specifically for a model across everything hmm, could be done with config ? ```json { "$schema": "https://opencode.ai/config.json", "provider": { "llamacpp": { "npm": "@ai-sdk/openai-compatible", "name": "llamacpp (local)", "options": { "baseURL": "http://192.168.1.132:8112/v1" }, "models": { "DeepCogito-109b": { "name": "DeepCogito-109b local", "system_prompt": "CUSTOM PROMPT", }, } }, "vllm":{ "npm": "@ai-sdk/openai-compatible", "name": "vllm (local)", "options": { "baseURL": "http://192.168.1.132:8111/v1", "apiKey": "local" }, "models": { "Kimi-Linear-48B-A3B-Instruct": { "name": "Kimi-Linear-48B-A3B-Instruct", "system_prompt_prepend": "INSTRUCTIONS HERE AT TOP", "system_prompt_append": "INSTRUCTIONS HERE AT BOTTOM", }, } } }, "model": "Kimi-Linear-48B-A3B-Instruct", "small_model": "Kimi-Linear-48B-A3B-Instruct" } ``` > > > Also it would be nice to ask the llm about opencode. I would propose the command /opencode ask that would have access to the opencode documentation and answer. > > I kinda like this idea because then it is less intruisive and we dont have to throw stuff in the system prompt everywhere You might add some docs with FAQ, implementation details (tutorial, examples, explanations), release notes. That could save time and be quite useful. I would process all github issues for most asked questions and check that the generated answer is right. Then bundle that in a few FAQ files by component (agents/tools/tui/etc.) in the doc and there you go. Limit file access to `.opencode/docs` for the command `/opencode` and provide list of files and a summary of what they contain in a README.md index. > > Session name: Why is is always New session ? > > Could it be updated to a short description like [plan] plan the new super feature... the first characters of the first command of the session with the original agent/command ? > > It's not supposed to be... What model / provider are you using? Kimi-Linear, only running opencode locally, didn't try API. Sorry then, but a fail-safe would be great when using smaller models.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label discussion documentation
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#2463
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?