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

How to reference other mds in the md of Subagents by using @? #1949

New Issue
Open
opened 2026-02-16 17:33:22 -05:00 by yindo · 32 comments
yindo commented 2026-02-16 17:33:22 -05:00
Owner
Copy Link
Copy Source

Originally created by @Cyberbolt on GitHub (Oct 4, 2025).

Originally assigned to: @rekram1-node on GitHub.

I think this feature in Claude Code is not well implemented

For example

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on @docs/Development-Guide.md

Provide constructive feedback without making direct changes.
Originally created by @Cyberbolt on GitHub (Oct 4, 2025). Originally assigned to: @rekram1-node on GitHub. I think this feature in Claude Code is not well implemented For example ``` --- description: Reviews code for quality and best practices mode: subagent model: anthropic/claude-sonnet-4-20250514 temperature: 0.1 tools: write: false edit: false bash: false --- You are in code review mode. Focus on @docs/Development-Guide.md Provide constructive feedback without making direct changes. ```
yindo commented 2026-02-16 17:33:22 -05:00
Author
Owner
Copy Link
Copy Source

@github-actions[bot] commented on GitHub (Oct 4, 2025):

This issue might be a duplicate of existing issues. Please check:

  • #2225: Automatically load @ referenced files in AGENTS.md into context - discusses the same @ reference functionality for markdown files that OpenCode currently doesn't support but should
  • #1490: The Manual Instructions in AGENTS.md seems to only work for relative references in the current project - mentions issues with @ file references not working as expected relative to the file they're referenced from

Feel free to ignore if none of these address your specific case.

@github-actions[bot] commented on GitHub (Oct 4, 2025): This issue might be a duplicate of existing issues. Please check: - #2225: Automatically load @ referenced files in AGENTS.md into context - discusses the same @ reference functionality for markdown files that OpenCode currently doesn't support but should - #1490: The Manual Instructions in AGENTS.md seems to only work for relative references in the current project - mentions issues with @ file references not working as expected relative to the file they're referenced from Feel free to ignore if none of these address your specific case.
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@Cyberbolt commented on GitHub (Oct 4, 2025):

Not AGENTS.md / CLAUDE.md, Claude Code currently cannot implement referencing other md files with @ in Subagent. Is there any hope for opencode to achieve this?

@Cyberbolt commented on GitHub (Oct 4, 2025): Not AGENTS.md / CLAUDE.md, Claude Code currently cannot implement referencing other md files with @ in Subagent. Is there any hope for opencode to achieve this?
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 4, 2025):

@Cyberbolt yeah I think we want all our md parsing to be consistent so currently we only read and inject files from an "@" for the commands but we want to do it for AGENTS.md and maybe agent definitions too that makes sense

@rekram1-node commented on GitHub (Oct 4, 2025): @Cyberbolt yeah I think we want all our md parsing to be consistent so currently we only read and inject files from an "@" for the commands but we want to do it for AGENTS.md and maybe agent definitions too that makes sense
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@Cyberbolt commented on GitHub (Oct 4, 2025):

@Cyberbolt yeah I think we want all our md parsing to be consistent so currently we only read and inject files from an "@" for the commands but we want to do it for AGENTS.md and agent definitions too that makes sense

Is my understanding correct? Currently, @ is useful for AGENTS.md and commands, but not for Subagents. @ is included in the form of files in AGENTS.md and commands, and the LLM reads them when needed.

@Cyberbolt commented on GitHub (Oct 4, 2025): > [@Cyberbolt](https://github.com/Cyberbolt) yeah I think we want all our md parsing to be consistent so currently we only read and inject files from an "@" for the commands but we want to do it for AGENTS.md and agent definitions too that makes sense Is my understanding correct? Currently, @ is useful for AGENTS.md and commands, but not for Subagents. @ is included in the form of files in AGENTS.md and commands, and the LLM reads them when needed.
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 4, 2025):

Yeah currently we only resolve the @ reference for commands but we should do it for the other things too

@rekram1-node commented on GitHub (Oct 4, 2025): Yeah currently we only resolve the @ reference for commands but we should do it for the other things too
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@Cyberbolt commented on GitHub (Oct 4, 2025):

@rekram1-node I see this issue was raised on August 25th, and currently opencode still does not support referencing via @ in AGENTS.md and Subagents. I think this is a very practical feature. May I ask how much engineering effort would be required to add it, or would you accept a PR?

@Cyberbolt commented on GitHub (Oct 4, 2025): @rekram1-node I see this [issue](https://github.com/sst/opencode/issues/2225) was raised on August 25th, and currently opencode still does not support referencing via @ in AGENTS.md and Subagents. I think this is a very practical feature. May I ask how much engineering effort would be required to add it, or would you accept a PR?
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 8, 2025):

Yeah currently we only resolve the @ reference for commands but we should do it for the other things too

Won't that behavior break the pattern/use case documented here, where files are only read when the context indicates that is appropriate. In this case when I am dealing with Rust code the @docs/typescript-guidelines.md will not be read:

https://opencode.ai/docs/rules/#manual-instructions-in-agentsmd

Related:

@taqtiqa-mark commented on GitHub (Oct 8, 2025): > Yeah currently we only resolve the @ reference for commands but we should do it for the other things too Won't that behavior break the pattern/use case documented here, where files are only read when the context indicates that is appropriate. In this case when I am dealing with Rust code the `@docs/typescript-guidelines.md` will not be read: https://opencode.ai/docs/rules/#manual-instructions-in-agentsmd Related: - #2965
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 8, 2025):

That documentation was added solely because we don't currently resolve the @ references. We will soon tho.

In regards to @Cyberbolt, there are a few small things I discussed w/ dax that I wanna include so I will probably do that this weekend / Monday. If you really want to you can start one and then I will do commits to it afterwards if needed.

Note that we wanna wanna do @ resolves for:

  • AGENTS.md
  • commands (already supported, it also resolves @agent references but the other 2 probably shouldn't)
  • agent definitions

We have a config markdown parser namespace

We also support the !`...` notations for commands, potentially should support those for others as well.

@rekram1-node commented on GitHub (Oct 8, 2025): That documentation was added solely because we don't currently resolve the @ references. We will soon tho. In regards to @Cyberbolt, there are a few small things I discussed w/ dax that I wanna include so I will probably do that this weekend / Monday. If you really want to you can start one and then I will do commits to it afterwards if needed. Note that we wanna wanna do @ resolves for: - AGENTS.md - commands (already supported, it also resolves @agent references but the other 2 probably shouldn't) - agent definitions We have a config markdown parser namespace We also support the !\`...\` notations for commands, potentially should support those for others as well.
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 8, 2025):

That documentation was added solely because we don't currently resolve the @ references.

Ack, and the current behavior is desirable (as outlined).
Will you consider placing the new (or old) behavior behind a config variable?
Say import_at? that lives in the md file, and can also be set via global and local config files?

@taqtiqa-mark commented on GitHub (Oct 8, 2025): > That documentation was added solely because we don't currently resolve the @ references. Ack, and the current behavior is desirable (as outlined). Will you consider placing the new (or old) behavior behind a config variable? Say `import_at`? that lives in the md file, and can also be set via global and local config files?
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 8, 2025):

We could make it configurable, would it not make sense ot just remove those @ prefixes if they link to large files? The idea behind resolving them was to be consistent with both other tools (claude code, codex, etc) and commands.

@rekram1-node commented on GitHub (Oct 8, 2025): We could make it configurable, would it not make sense ot just remove those @ prefixes if they link to large files? The idea behind resolving them was to be consistent with both other tools (claude code, codex, etc) and commands.
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 8, 2025):

We could make it configurable ...

Thanks for considering this possibility.

That would be great. The current behavior is desirable in orchestration workflow scenarios.

... would it not make sense ot just remove those @ prefixes if they link to large files?

Not really. These (Agent, Subagent, Command) files are categorically distinct from project/other files, so the @ abstraction is useful in preserving that distinction. And the config variable allows use cases that otherwise are either not possible or are hacky.

The idea behind resolving them was to be consistent with both other tools (claude code, codex, etc) and commands.

Agreed, familiarity for legacy users migrating is important. If this is a core long-term goal of the project, I suggest adding a compat_claude, compat_codex, etc., config variables and collecting, and setting, the various related variables behind that.

I'd also argue against forcing (no config variable) the behaviors of these abstractions (Agent, Command) to be the same. Generally the point of introducing an abstraction is to solve a problem. Forcing the abstractions to be clones defeats that purpose.
Naturally adding the import_at config variable to Commands improves the flexibility of that abstraction, and users whose use case is not thwarted by redundant/identical abstractions will be unimpeded.

@taqtiqa-mark commented on GitHub (Oct 8, 2025): > We could make it configurable ... Thanks for considering this possibility. That would be great. The current behavior is desirable in orchestration workflow scenarios. > ... would it not make sense ot just remove those @ prefixes if they link to large files? Not really. These (Agent, Subagent, Command) files are categorically distinct from project/other files, so the `@` abstraction is useful in preserving that distinction. And the config variable allows use cases that otherwise are either not possible or are hacky. > The idea behind resolving them was to be consistent with both other tools (claude code, codex, etc) and commands. Agreed, familiarity for legacy users migrating is important. If this is a core long-term goal of the project, I suggest adding a `compat_claude`, `compat_codex`, etc., config variables and collecting, and setting, the various related variables behind that. I'd also argue against forcing (no config variable) the behaviors of these abstractions (Agent, Command) to be the same. Generally the point of introducing an abstraction is to solve a problem. Forcing the abstractions to be clones defeats that purpose. Naturally adding the `import_at` config variable to Commands improves the flexibility of that abstraction, and users whose use case is not thwarted by redundant/identical abstractions will be unimpeded.
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@webboty commented on GitHub (Oct 8, 2025):

Note for the team – I’m not sure whether this will actually work with our current tooling, but I wanted to share an idea that feels intuitive.

We could reference auxiliary markdown files using the @ prefix, e.g. @AGENTS_BROWSER_TESTER.md for a file at the project root or @subfolder/AGENTS_BROWSER_TESTER.md for one inside a subdirectory. Some of these AGENTS_*.md files also reference other AGENTS_*.md files in the same way, creating nested includes.

Just passing this along for consideration-

@webboty commented on GitHub (Oct 8, 2025): **Note for the team** – I’m not sure whether this will actually work with our current tooling, but I wanted to share an idea that feels intuitive. We could reference auxiliary markdown files using the `@` prefix, e.g. `@AGENTS_BROWSER_TESTER.md` for a file at the project root or `@subfolder/AGENTS_BROWSER_TESTER.md` for one inside a subdirectory. Some of these `AGENTS_*.md` files also reference other `AGENTS_*.md` files in the same way, creating nested includes. Just passing this along for consideration-
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 8, 2025):

@taqtiqa-mark I think the team wants almost everything to be customizable generally, but I just wanna understand your case better

Not really. These (Agent, Subagent, Command) files are categorically distinct from project/other files, so the @ abstraction is useful in preserving that distinction. And the config variable allows use cases that otherwise are either not possible or are hacky.

When would you want to @ reference a file otherwise? Like what does the @ do for you in any other circumstance?

Ofc if you do @email or something that doesn't exist then it would remain the same, but if you @ reference files in a prompt, shouldn't the behavior be consistent?

@rekram1-node commented on GitHub (Oct 8, 2025): @taqtiqa-mark I think the team wants almost everything to be customizable generally, but I just wanna understand your case better > Not really. These (Agent, Subagent, Command) files are categorically distinct from project/other files, so the @ abstraction is useful in preserving that distinction. And the config variable allows use cases that otherwise are either not possible or are hacky. When would you want to @ reference a file otherwise? Like what does the @<filename> do for you in any other circumstance? Ofc if you do @email or something that doesn't exist then it would remain the same, but if you @ reference files in a prompt, shouldn't the behavior be consistent?
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 8, 2025):

When would you want to @ reference a file otherwise?

I am not sure that I would.
IIUC, @ indicates file location in the config folder hierarchy - the abstraction I referenced. So @ indicates something located in a global, local, OPENCODE_CONFIG folder.
If you meant: what context other than Agent/Subagent files would I expect @ point to a file in the config folder hierarchy? Then I would expect that to be true in Agent, Subagent, Rules, Command and Tool files as well as instruction files. With the convention that *.md files can have yaml front matter setting import_at, and otherwise the default set in the config file chain applies when using *.txt, etc., files. So @email, first looks for $OPENSOURCE_CONFIG/<context>/email.md (possibly setting import_at) then $OPENSOURCE_CONFIG/<context>/email (not able to set import_at, but using the setting from $OPENSOURCE_CONFIG/opencode.jsonc ). Where <context> is agents, commands, tools or rules.

Like what does the @ do for you in any other circumstance?

In all circumstances (Rules, Agents, Commands, Tools) I'd expect/hope the @ does the same thing (subject to the variable setting of import_at)

.... if you @ reference files in a prompt, shouldn't the behavior be consistent?

Yes it should be consistent within the context (Rules, Commands, Tools, Agents/Subagents): Files in the config hierarchy.

The `folder/file/location.conv` should be understood to be referring to files in project hierarchy. Here, naturally, `./.../.../files` does not mean import this file automatically, and immediately. But if you did want to be consistent then adding import_backticks would seem natural?

Apologies if that is not clear. On reflection I should have used AI to generate some Gherkin feature files :) ... I may still do.

@taqtiqa-mark commented on GitHub (Oct 8, 2025): > When would you want to @ reference a file otherwise? I am not sure that I would. IIUC, `@` indicates file location in the config folder hierarchy - the abstraction I referenced. So `@` indicates something located in a global, local, OPENCODE_CONFIG folder. If you meant: what context other than Agent/Subagent files would I expect `@` point to a file in the config folder hierarchy? Then I would expect that to be true in Agent, Subagent, Rules, Command and Tool files as well as `instruction` files. With the convention that `*.md` files can have yaml front matter setting `import_at`, and otherwise the default set in the config file chain applies when using `*.txt`, etc., files. So `@email`, first looks for `$OPENSOURCE_CONFIG/<context>/email.md` (possibly setting `import_at`) then `$OPENSOURCE_CONFIG/<context>/email` (not able to set `import_at`, but using the setting from `$OPENSOURCE_CONFIG/opencode.jsonc` ). Where `<context>` is `agents`, `commands`, `tools` or `rules`. > Like what does the @ do for you in any other circumstance? In all circumstances (Rules, Agents, Commands, Tools) I'd expect/hope the `@` does the same thing (subject to the variable setting of `import_at`) > .... if you @ reference files in a prompt, shouldn't the behavior be consistent? Yes it should be consistent within the context (Rules, Commands, Tools, Agents/Subagents): Files in the ****config**** hierarchy. The \`folder/file/location.conv\` should be understood to be referring to files in ****project**** hierarchy. Here, naturally, \`./.../.../files\` does not mean import this file automatically, and immediately. But if you did want to be consistent then adding `import_backticks` would seem natural? Apologies if that is not clear. On reflection I should have used AI to generate some Gherkin feature files :) ... I may still do.
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 8, 2025):

unless im misunderstanding you then we are completely in agreement? the only difference you seem to be stating is making the @ prefix for the agent, command, rule files configurable? and making import_at define the prefix?

but yeah im strictly talking about agent, command, rule files not all md files in general or anything like that

@rekram1-node commented on GitHub (Oct 8, 2025): unless im misunderstanding you then we are completely in agreement? the only difference you seem to be stating is making the @ prefix for the agent, command, rule files configurable? and making import_at define the prefix? but yeah im strictly talking about agent, command, rule files not all md files in general or anything like that
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 8, 2025):

the only difference you seem to be stating is making the @ prefix for the agent, command, rule files configurable?

No. import_at makes the behavior configurable: import_at: true/false/ask

and making import_at define the prefix?

No. As above. The prefix is always @ and refers the the config folder hierarchy.

Current behavior is: import_at: false
Meaning the @files are not automatically imported, but rather left to the instructions to the AI backend (see current doc example)

@taqtiqa-mark commented on GitHub (Oct 8, 2025): > the only difference you seem to be stating is making the @ prefix for the agent, command, rule files configurable? No. `import_at` makes the behavior configurable: `import_at: true/false/ask` > and making import_at define the prefix? No. As above. The prefix is always `@` and refers the the config folder hierarchy. Current behavior is: `import_at: false` Meaning the `@files` are not automatically imported, but rather left to the instructions to the AI backend (see current doc example)
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 8, 2025):

ahhh okay i gotchu, thx for clarifying

@rekram1-node commented on GitHub (Oct 8, 2025): ahhh okay i gotchu, thx for clarifying
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 8, 2025):

I think #1990 is relevant context to think about. If an /add command like Aider /add is introduced, then this might impact the `./file/location.conv` convention?

In a prompt file the next words, /add `file/location`, could mean add the file to current context. But in workflow prompts where placeholders are used this might get tricky to parse?

@taqtiqa-mark commented on GitHub (Oct 8, 2025): I think #1990 is relevant context to think about. If an `/add` command like [Aider `/add`](https://aider.chat/docs/usage/commands.html) is introduced, then this might impact the \`./file/location.conv\` convention? In a prompt file the next words, /add \`file/location\`, could mean add the file to current context. But in workflow prompts where placeholders are used this might get tricky to parse?
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 9, 2025):

@rekram1-node thinking about this a little more, and the current syntax seems a little brittle and idiosyncratic.
Some problems:

  • @ is a special character that the opencode agent-user and agent-author has to take care not to use or must escape, e.g. When wanting to send data to, say, a build-bot on social app: "Send a message to @build containing a summary of the CI log"
  • there is not a consistent way for an agent-author to invoke, Agents/Subagents, Commands, Tools, Rules.

A potential solution is:

  • @@ is the prefix agent-authors and agent-users use for invoking Agents/Subagents, Commands, Tools, Rules.
  • Where the same suffix is used in multiple contexts, say a shared Agent and shared Command, the syntax is @@shared for agent and @@commands/shared or in general @@<context>/shared.

Thoughts?

@taqtiqa-mark commented on GitHub (Oct 9, 2025): @rekram1-node thinking about this a little more, and the current syntax seems a little brittle and idiosyncratic. Some problems: - `@` is a special character that the opencode agent-user and agent-author has to take care not to use or must escape, e.g. When wanting to send data to, say, a build-bot on social app: "Send a message to @build containing a summary of the CI log" - there is not a consistent way for an agent-author to invoke, Agents/Subagents, Commands, Tools, Rules. A potential solution is: - `@@` is the prefix agent-authors and agent-users use for invoking Agents/Subagents, Commands, Tools, Rules. - Where the same suffix is used in multiple contexts, say a `shared` Agent and `shared` Command, the syntax is `@@shared` for agent and `@@commands/shared` or in general `@@<context>/shared`. Thoughts?
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 9, 2025):

for the @ thing we only resolve it if you have a file or agent that it references, otherwise it stays as is so I wouldnt say u need to take extra care not to use and you would rarely ever need to escape it

as for @@, why introduce a new standard? almost every coding agent supports @ syntax for this type of stuff making it @@ would break workflows no?

@rekram1-node commented on GitHub (Oct 9, 2025): for the @ thing we only resolve it if you have a file or agent that it references, otherwise it stays as is so I wouldnt say u need to take extra care not to use and you would rarely ever need to escape it as for @@, why introduce a new standard? almost every coding agent supports @ syntax for this type of stuff making it @@ would break workflows no?
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 9, 2025):

for the @ thing we only resolve it if you have a file or agent that it references,

Correct, and there is a default build agent in opencode, so the user will find that opencode build agent is invoked instead of the summary being sent to the build in their social app.

as for @@, why introduce a new standard?

Because the social media space conventions adopted @user long ago. Agents are the interloper. No?
Also it is very early in the AI-Agent use case to insist that conventions are set in stone?

almost every coding agent supports @ syntax for this type of stuff making it @@ would break workflows no?

Possibly, but the change is trivial to make, and users will not need to tie themselves in knots trying to reconcile two different, but overlapping, domains insisting on adopting the same convention for incompatible use cases.

@taqtiqa-mark commented on GitHub (Oct 9, 2025): > for the @ thing we only resolve it if you have a file or agent that it references, Correct, and there is a default `build` agent in opencode, so the user will find that opencode `build` agent is invoked instead of the summary being sent to the `build` in their social app. > as for @@, why introduce a new standard? Because the social media space conventions adopted `@user` long ago. Agents are the interloper. No? Also it is very early in the AI-Agent use case to insist that conventions are set in stone? > almost every coding agent supports @ syntax for this type of stuff making it @@ would break workflows no? Possibly, but the change is trivial to make, and **users** will not need to tie themselves in knots trying to reconcile two different, but overlapping, domains insisting on adopting the same convention for incompatible use cases.
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 10, 2025):

as for @@, why introduce a new standard?

Actually, maybe this is where your earlier idea you canvassed is relevant, by making this configurable: import_prefix: @@ would be useful?
This way if some other project adopt a different convention the users can just redefine the prefix?

@taqtiqa-mark commented on GitHub (Oct 10, 2025): > as for @@, why introduce a new standard? Actually, maybe this is where your earlier idea you canvassed is relevant, by making this configurable: `import_prefix: @@` would be useful? This way if some other project adopt a different convention the users can just redefine the prefix?
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 10, 2025):

hmm perhaps

@rekram1-node commented on GitHub (Oct 10, 2025): hmm perhaps
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 11, 2025):

Working on integrating my first agent/subagent/command/rules stack, so apologies for the evolving and incomplete understanding/requirements....

I think that both the @ and @@ are the most ergonomic.

  • @: Adapts the "socials"convention. For addressing agents/subagents. Examples:
    • @ide set up a rust project for mobile and web app.: Reads and executes the $OPENCODE_CONFIG/agents/ide.md
    • @ide/ticket analyze 'README.md': Reads and executes the $OPENCODE_CONFIG/agents/ide/ticket.md where README.md is in the project root.
  • @@: Convention to import file (current proposed @ behavior). Example:
    • CRITICAL: When you encounter a file reference (e.g., @@rules/general.md), use your Read tool to load it on a need-to-know basis.

Thoughts?

@taqtiqa-mark commented on GitHub (Oct 11, 2025): Working on integrating my first agent/subagent/command/rules stack, so apologies for the evolving and incomplete understanding/requirements.... I think that both the `@` and `@@` are the most ergonomic. - `@`: Adapts the "socials"convention. For addressing agents/subagents. Examples: - `@ide set up a rust project for mobile and web app.`: Reads and executes the `$OPENCODE_CONFIG/agents/ide.md` - `@ide/ticket analyze 'README.md'`: Reads and executes the `$OPENCODE_CONFIG/agents/ide/ticket.md` where README.md is in the project root. - `@@`: Convention to import file (current proposed `@` behavior). [Example](https://opencode.ai/docs/rules/#manual-instructions-in-agentsmd): - `CRITICAL: When you encounter a file reference (e.g., @@rules/general.md), use your Read tool to load it on a need-to-know basis.` Thoughts?
yindo commented 2026-02-16 17:33:23 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 11, 2025):

We will see, Idk though I think we want things to stay consistent so for file references they will almost certainly remain as just @. Consistent with existing behavior and other popular tools

@rekram1-node commented on GitHub (Oct 11, 2025): We will see, Idk though I think we want things to stay consistent so for file references they will almost certainly remain as just @. Consistent with existing behavior and other popular tools
yindo commented 2026-02-16 17:33:24 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 11, 2025):

for file references they will almost certainly remain as just @. Consistent with existing behavior and other popular tools

How do we disambiguate: @ide set up a rust project for mobile and web app. So that it does not just insert the contents of agents/ide.md before set up a rust project for mobile and web app.?

@taqtiqa-mark commented on GitHub (Oct 11, 2025): > for file references they will almost certainly remain as just @. Consistent with existing behavior and other popular tools How do we disambiguate: `@ide set up a rust project for mobile and web app.` So that it does not just insert the contents of `agents/ide.md` before `set up a rust project for mobile and web app.`?
yindo commented 2026-02-16 17:33:24 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 11, 2025):

because that would require you to write @agents/ide.md

but i see what u mean there could be some cases and then the question becomes what takes preference

@rekram1-node commented on GitHub (Oct 11, 2025): because that would require you to write @agents/ide.md but i see what u mean there could be some cases and then the question becomes what takes preference
yindo commented 2026-02-16 17:33:24 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 11, 2025):

Thanks again for engaging in this.

but i see what u mean there could be some cases and then the question becomes what takes preference

I think the difficulty arises when you want the dev to retain control of what the behavior is, and at the same time make all behaviors consistent and intuitive.

Overloading @ with different behaviors depending on the content of the suffix feels wrong - but that is subjective taste.

More objectively how do you allow developers control over importing without creating idisyncratic behavior.

E.G. import_at: false (current behavior) means @ide do this in acted on but @agents/ide.md is not acted on.

Never mind that the action associated with @ is wildly different: Agent execution vs file read.

If you do insist on overloading @ with different behaviors (agent execution and file reading), would you consider adding the config variable execute_at: true, false, ask ?

@taqtiqa-mark commented on GitHub (Oct 11, 2025): Thanks again for engaging in this. > but i see what u mean there could be some cases and then the question becomes what takes preference I think the difficulty arises when you want the dev to retain control of what the behavior is, and at the same time make all behaviors consistent and intuitive. Overloading `@` with different behaviors depending on the content of the suffix feels wrong - but that is subjective taste. More objectively how do you allow developers control over importing without creating idisyncratic behavior. E.G. `import_at: false` (current behavior) means `@ide do this` in acted on but `@agents/ide.md` is not acted on. Never mind that the action associated with `@` is wildly different: Agent execution vs file read. If you do insist on overloading `@` with different behaviors (agent execution and file reading), would you consider adding the config variable `execute_at: true, false, ask` ?
yindo commented 2026-02-16 17:33:24 -05:00
Author
Owner
Copy Link
Copy Source

@rekram1-node commented on GitHub (Oct 11, 2025):

E.G. import_at: false (current behavior) means @ide do this in acted on but @agents/ide.md is not acted on.

But in a command currently, both are acted on

config variable execute_at: true, false, ask ?

I think making things configurable makes sense, but the var name may need some work :)

@rekram1-node commented on GitHub (Oct 11, 2025): > E.G. import_at: false (current behavior) means @ide do this in acted on but @agents/ide.md is not acted on. But in a command currently, both are acted on > config variable execute_at: true, false, ask ? I think making things configurable makes sense, but the var name may need some work :)
yindo commented 2026-02-16 17:33:24 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 11, 2025):

E.G. import_at: false (current behavior) means @ide do this in acted on but @agents/ide.md is not acted on.

But in a command currently, both are acted on

Hmm, hadn't stubbed my toes on that idiosyncrasy yet. But will try to bear that in mind.

At least having these config options would make the inconsistent behavior explicit:
In Agents:

import_at: false
execute_at: true

In Commands:

import_at: true
execute_at: true

... but the var name may need some work :)

Yup, apparently one of the two difficult problems in computer science.

@taqtiqa-mark commented on GitHub (Oct 11, 2025): >> E.G. import_at: false (current behavior) means @ide do this in acted on but @agents/ide.md is not acted on. > > But in a command currently, both are acted on Hmm, hadn't stubbed my toes on that idiosyncrasy yet. But will try to bear that in mind. At least having these config options would make the inconsistent behavior explicit: In Agents: ``` import_at: false execute_at: true ``` In Commands: ``` import_at: true execute_at: true ``` > ... but the var name may need some work :) Yup, apparently one of the two difficult problems in computer science.
yindo commented 2026-02-16 17:33:24 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Oct 13, 2025):

To clarify a distinction between @ and /add (proposed) that arose in #1990:

In this context; I believe the following should be respected with unambiguous syntax for each:

  1. there are two sources of data: Config hierarchy, Project hierarchy.
  2. there are two destinations of data: Prompt text, Context text.

This means that @file and /add file should never result in the same file being "imported" - respecting 1.
Also @<anything> should never be placed in the session/LLM context "buffer".
Likewise /add <anything> should never be placed in the session/LLM prompt "buffer".

The debate about @ and @@ concern the Prompt "buffer" content:

  • @: Submitting a prompt to the LLM, vs
  • @@: Expanding the content of the prompt before submission via the LLM's API
@taqtiqa-mark commented on GitHub (Oct 13, 2025): To clarify a distinction between `@` and `/add` (proposed) that arose in #1990: In this context; I believe the following should be respected with unambiguous syntax for each: 1. there are two sources of data: Config hierarchy, Project hierarchy. 2. there are two destinations of data: Prompt text, Context text. This means that `@file` and `/add file` should never result in the same file being "imported" - respecting 1. Also `@<anything>` should never be placed in the session/LLM context "buffer". Likewise `/add <anything>` should never be placed in the session/LLM prompt "buffer". The debate about `@` and `@@` concern the Prompt "buffer" content: - `@`: Submitting a prompt to the LLM, vs - `@@`: Expanding the content of the prompt before submission via the LLM's API
yindo commented 2026-02-16 17:33:24 -05:00
Author
Owner
Copy Link
Copy Source

@taqtiqa-mark commented on GitHub (Feb 5, 2026):

In the spirit of calling out excellent engineering and design....

I've found that the Pi Coding Agent is more robust and, for me has none of the issues that I've encountered in OC, or has an elegant way to resolve them.... I'm dropping out of OC issues:

@taqtiqa-mark commented on GitHub (Feb 5, 2026): In the spirit of calling out excellent engineering and design.... I've found that the Pi Coding Agent is more robust and, for me has none of the issues that I've encountered in OC, or has an elegant way to resolve them.... I'm dropping out of OC issues: - [Pi Coding Agent](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent) - [Overview](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/) - [Example development session](https://www.youtube.com/watch?v=ANQ1IYsFM2s)
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
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#1949
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?