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

Streamlined Distribution for Agent Definitions #2295

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

Originally created by @kamilchm on GitHub (Oct 27, 2025).

Question

I have a question about distributing agents for OpenCode. I have a repo with different agents defined in
md files now, and I want to share them with others with minimal friction. I don't want to force everyone to use the
full selection of agents, but I want a simple process for selecting only the agents they want. I also want them to
have an easy way of updating the definitions of agents they select.

The most straightforward way would be something like a filtered-out git command, or a tool that scaffolds projects
from templates and is used to manage the OpenCode agent directory. It's not a complex solution, but it also feels
fragile and hard to reason about.

The other possibility I see is OpenCode plugins. I don't know how installation and updates work for them, but the
fact that you can define a list of plugins in the config file looks like a good, standard ecosystem solution. Is
there a way to create a plugin that will be auto-installed and optionally auto-updated and that creates an agent
using the SDK? Thinking further, it would be great if I could distribute an agent definition with custom tools in
one package, and the only thing the user needs to do to use it is add its name to the config file.

I tried to find something in the source code to support this idea, but I couldn't.

What is the best way to build a shareable OpenCode agents repository today?

Originally created by @kamilchm on GitHub (Oct 27, 2025). ### Question I have a question about distributing agents for OpenCode. I have a repo with different agents defined in md files now, and I want to share them with others with minimal friction. I don't want to force everyone to use the full selection of agents, but I want a simple process for selecting only the agents they want. I also want them to have an easy way of updating the definitions of agents they select. The most straightforward way would be something like a filtered-out git command, or a tool that scaffolds projects from templates and is used to manage the OpenCode agent directory. It's not a complex solution, but it also feels fragile and hard to reason about. The other possibility I see is OpenCode plugins. I don't know how installation and updates work for them, but the fact that you can define a list of plugins in the config file looks like a good, standard ecosystem solution. Is there a way to create a plugin that will be auto-installed and optionally auto-updated and that creates an agent using the SDK? Thinking further, it would be great if I could distribute an agent definition with custom tools in one package, and the only thing the user needs to do to use it is add its name to the config file. I tried to find something in the source code to support this idea, but I couldn't. What is the best way to build a shareable OpenCode agents repository today?
yindo added the discussion label 2026-02-16 17:35:00 -05:00
yindo commented 2026-02-16 17:35:01 -05:00
Author
Owner
Copy Link
Copy Source

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

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

  • #3087: Asks about a community plugin repository for discovering and downloading plugins
  • #1849: Requests CLI install/uninstall support for plugins, addressing the distribution friction you mentioned
  • #3207: Proposes MCP Registry integration for easier discovery and management of tools/servers
  • #2237: Suggests native TypeScript toolsets for code-first tools, which could support your custom tools distribution idea

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

@github-actions[bot] commented on GitHub (Oct 27, 2025): This issue might be a duplicate of existing issues. Please check: - #3087: Asks about a community plugin repository for discovering and downloading plugins - #1849: Requests CLI install/uninstall support for plugins, addressing the distribution friction you mentioned - #3207: Proposes MCP Registry integration for easier discovery and management of tools/servers - #2237: Suggests native TypeScript toolsets for code-first tools, which could support your custom tools distribution idea Feel free to ignore if none of these address your specific case.
yindo commented 2026-02-16 17:35:01 -05:00
Author
Owner
Copy Link
Copy Source

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

We are going to add a better support for this, probably a marketplace or something eventually so you can browse and explore.

Until then we could probably add an agent add command that can grab them from a repo or something

opencode agent currently only has the create subcommand, we should probably allow for some management of agents with it too, at the very least a list command

@rekram1-node commented on GitHub (Oct 27, 2025): We are going to add a better support for this, probably a marketplace or something eventually so you can browse and explore. Until then we could probably add an agent add command that can grab them from a repo or something `opencode agent` currently only has the `create` subcommand, we should probably allow for some management of agents with it too, at the very least a list command
yindo commented 2026-02-16 17:35:01 -05:00
Author
Owner
Copy Link
Copy Source

@kamilchm commented on GitHub (Oct 27, 2025):

Cool, do you know if there's a way to extend OpenCode CLI commands (like agent) with a plugin? I haven't written any plugins for OpenCode yet.

Do you have any other ideas on how to implement this kind of workflow in another way, before the full-featured solution can land?

@kamilchm commented on GitHub (Oct 27, 2025): Cool, do you know if there's a way to extend OpenCode CLI commands (like `agent`) with a plugin? I haven't written any plugins for OpenCode yet. Do you have any other ideas on how to implement this kind of workflow in another way, before the full-featured solution can land?
yindo commented 2026-02-16 17:35:01 -05:00
Author
Owner
Copy Link
Copy Source

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

You can't extend them right now, but I think what you want should probably be first party supported, if you have a proposal, a PR would be welcome

@rekram1-node commented on GitHub (Oct 27, 2025): You can't extend them right now, but I think what you want should probably be first party supported, if you have a proposal, a PR would be welcome
yindo commented 2026-02-16 17:35:01 -05:00
Author
Owner
Copy Link
Copy Source

@kamilchm commented on GitHub (Oct 27, 2025):

Thanks! I'll think about a proposal and potentially put together a PR.

@kamilchm commented on GitHub (Oct 27, 2025): Thanks! I'll think about a proposal and potentially put together a PR.
yindo commented 2026-02-16 17:35:01 -05:00
Author
Owner
Copy Link
Copy Source

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

sweet

@rekram1-node commented on GitHub (Oct 27, 2025): sweet
yindo commented 2026-02-16 17:35:01 -05:00
Author
Owner
Copy Link
Copy Source

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

@kamilchm I think that a filter list in config could work.

{
  "$schema": "https://opencode.ai/config.json",
  "agent_paths": {
    "generic": {
      "description": "generic agents that are always available",
      "path": "$HOME/.local/opencode/agents",
      "enabled": {
        "all": "*",
        },
      "disabled": {
        "specific": "clean-codebase",
        },
     },
     "project_specific": {
      "description": "agents that are in a local codebase",
      "path": "./AGENTS",
      "enabled": {
        "limit": "plan-*",
        "specific": "super-cool-agent"
        },
      },
    },
  },
}

Could work for agent_path, tool_path, command_path.

For TUI, add a ctrl-x shift-a for agent config.
Would search all agent paths, allow enabling/disabling paths/agents, switch agent config like claude-agents and qwen-agents and deepseek-agents so troublesome agents are not available.

@rekram1-node
Going further, we could have distinct opencode.jsonc called environments and it would be possible to switch between them. Each would then enable distinct agents, tools and commands.
I would see this used for creating distinct opencode environments like : CODING, DOCUMENTATION, ISSUE-MANAGEMENT, READONLY, PLANNING.

Not a market, but perhaps a HUB ? But it's going to be flooded with multiple copies of the same thing.

Perhaps a git repository opencode-blocks for agents/commands/tools with a tagging system for :

model_compatibility : claude-*, >qwen3-14b, >=deepseek-v3, >=oss-gpt-120b, >=qwen3-30b-a3b
review_score: >4

Keep only 5 best examples per use case (like optimized version working on small llm for local use and complex version requiring >400b model from API), and group agent+subagents in folders when they are interdependent.

Automatic merging of updates to README.md in a folder for appended user review of a agent. That's how I'd implement it. Then opencode could have a command to fuzzy search for available agents/commands/tools and propose preview with buttons : open browser to url, copy url, download file to local repo in .opencode/agent, download to $HOME/.local/opencode/agents/.

The thing missing is a detailed instruction sheet on how to write complete and well structured agents/commands for AI. This could be sent as context to generate commands or agents from within opencode. It should detail all what agent could do and how to have it told to do something like using a certain tool for a certain task.

The best I found is AGENT-SYSTEM-BLUEPRINT.md. This should be on the website ! I made a version for COMMAND also.

I have a `/create-agent` 
---
name: create-agent
mode: primary
temperature: 0.0
permissions:
  bash:
    "*": "deny"
    "mkdir": "allow"
    "ls": "allow"
    "cat": "allow"
    "head": "allow"
    "read": "allow"
    "write": "ask"
  edit: "deny"
  read:
    "*.md": "allow"
    "./**/*.md": "allow"
  write:
    "*": "deny"
    "**/*": "deny"
    "./agent/subagents/*.md": "allow"
    "./agent/*.md": "allow"
...

**ANALYZE** the user request for agent creation: "$ARGUMENTS"

**ASK** user for agent details if missing:
- **What is the agent name?** (e.g., "my-agent", "subprocesso", "specialized-tool", "analysis-bot"
- **What type of agent should this be?** (choose: primary, subagent)
- **What is your agent's purpose?** What specific functions should it perform?
- **What permissions should this agent have?** (read, edit, write, bash capabilities)

**CONTEXT**:

@.opencode/AGENT-SYSTEM-BLUEPRINT.md

**TASKS**:

**TASK 1: CONFIRM AGENT DETAILS**
- **DISPLAY** Agent: [name], agent: [type], agent definition: (definition), agent purpose: (purpose), agent permissions: (permissions).
- **WAIT** for user response

**TASK 2: CREATE AGENT FILE DRAFT**
- **READ** reference blueprint @.opencode/AGENT-SYSTEM-BLUEPRINT.md
- **DRAFT** the agent file
- **WAIT** for user response

**TASK 3: CREATE AGENT FILE**
- **CREATE** new agent file in ./opencode/agent/[agent-name].md or subagent in ./opencode/agent/subagents/[agent-name].md

**TASK 4: CHECK**
- **VERIFY** target agent exists in .opencode/agent/[agent-name].md or  ./opencode/agent/subagents/[agent-name].md

**TASK 5: VALIDATE CREATED AGENT**
- **READ** created agent file to verify format and permissions
- **REVIEW** created agent against @.opencode/AGENT-SYSTEM-BLUEPRINT.md
- **ENSURE** agent has appropriate delegated controls
- **DISPLAY** completion summary status after checking it :
  - ✅ Agent file structure follows blueprint patterns
  - ✅ Agent permissions set appropriately
  - ✅ Context loading sections formatted correctly
  - ✅ Agent assignment appropriate
  - ✅ Quality gates and validation steps completed
  - ✅ Agent ready for use: `@[agent-name]`

**SUCCESS CRITERIA**:
✅ Agent file follows blueprint structure
✅ Agent permissions align with security model
✅ Agent assignment matches use cases

**YOU MUST** follow the established blueprint patterns exactly
**EXECUTE** the agent creation process now.
@johnr14 commented on GitHub (Nov 7, 2025): @kamilchm I think that a filter list in config could work. ```jsonc { "$schema": "https://opencode.ai/config.json", "agent_paths": { "generic": { "description": "generic agents that are always available", "path": "$HOME/.local/opencode/agents", "enabled": { "all": "*", }, "disabled": { "specific": "clean-codebase", }, }, "project_specific": { "description": "agents that are in a local codebase", "path": "./AGENTS", "enabled": { "limit": "plan-*", "specific": "super-cool-agent" }, }, }, }, } ``` Could work for `agent_path`, `tool_path`, `command_path`. For TUI, add a `ctrl-x shift-a` for agent config. Would search all agent paths, allow enabling/disabling paths/agents, switch agent config like `claude-agents` and `qwen-agents` and `deepseek-agents` so troublesome agents are not available. ---- @rekram1-node Going further, we could have distinct `opencode.jsonc` called `environments` and it would be possible to switch between them. Each would then enable distinct agents, tools and commands. I would see this used for creating distinct opencode environments like : `CODING`, `DOCUMENTATION`, `ISSUE-MANAGEMENT`, `READONLY`, `PLANNING`. ---- Not a market, but perhaps a HUB ? But it's going to be flooded with multiple copies of the same thing. Perhaps a `git` repository `opencode-blocks` for agents/commands/tools with a tagging system for : `model_compatibility` : claude-*, >qwen3-14b, >=deepseek-v3, >=oss-gpt-120b, >=qwen3-30b-a3b `review_score`: >4 Keep only 5 best examples per use case (like optimized version working on small llm for local use and complex version requiring >400b model from API), and group agent+subagents in folders when they are interdependent. Automatic merging of updates to README.md in a folder for **appended** user review of a agent. That's how I'd implement it. Then opencode could have a command to fuzzy search for available agents/commands/tools and propose preview with buttons : open browser to url, copy url, download file to local repo in .opencode/agent, download to $HOME/.local/opencode/agents/. ---- The thing missing is a **detailed instruction sheet** on how to write complete and well structured agents/commands for AI. This could be sent as context to generate commands or agents from within opencode. It should detail all what agent could do and how to have it told to do something like using a certain tool for a certain task. The best I found is [AGENT-SYSTEM-BLUEPRINT.md](https://github.com/darrenhinde/opencode-agents/blob/main/.opencode/AGENT-SYSTEM-BLUEPRINT.md). This should be on the website ! I made a version for COMMAND also. <details> <summary>I have a `/create-agent`</summary> ```markdown --- name: create-agent mode: primary temperature: 0.0 permissions: bash: "*": "deny" "mkdir": "allow" "ls": "allow" "cat": "allow" "head": "allow" "read": "allow" "write": "ask" edit: "deny" read: "*.md": "allow" "./**/*.md": "allow" write: "*": "deny" "**/*": "deny" "./agent/subagents/*.md": "allow" "./agent/*.md": "allow" ... **ANALYZE** the user request for agent creation: "$ARGUMENTS" **ASK** user for agent details if missing: - **What is the agent name?** (e.g., "my-agent", "subprocesso", "specialized-tool", "analysis-bot" - **What type of agent should this be?** (choose: primary, subagent) - **What is your agent's purpose?** What specific functions should it perform? - **What permissions should this agent have?** (read, edit, write, bash capabilities) **CONTEXT**: @.opencode/AGENT-SYSTEM-BLUEPRINT.md **TASKS**: **TASK 1: CONFIRM AGENT DETAILS** - **DISPLAY** Agent: [name], agent: [type], agent definition: (definition), agent purpose: (purpose), agent permissions: (permissions). - **WAIT** for user response **TASK 2: CREATE AGENT FILE DRAFT** - **READ** reference blueprint @.opencode/AGENT-SYSTEM-BLUEPRINT.md - **DRAFT** the agent file - **WAIT** for user response **TASK 3: CREATE AGENT FILE** - **CREATE** new agent file in ./opencode/agent/[agent-name].md or subagent in ./opencode/agent/subagents/[agent-name].md **TASK 4: CHECK** - **VERIFY** target agent exists in .opencode/agent/[agent-name].md or ./opencode/agent/subagents/[agent-name].md **TASK 5: VALIDATE CREATED AGENT** - **READ** created agent file to verify format and permissions - **REVIEW** created agent against @.opencode/AGENT-SYSTEM-BLUEPRINT.md - **ENSURE** agent has appropriate delegated controls - **DISPLAY** completion summary status after checking it : - ✅ Agent file structure follows blueprint patterns - ✅ Agent permissions set appropriately - ✅ Context loading sections formatted correctly - ✅ Agent assignment appropriate - ✅ Quality gates and validation steps completed - ✅ Agent ready for use: `@[agent-name]` **SUCCESS CRITERIA**: ✅ Agent file follows blueprint structure ✅ Agent permissions align with security model ✅ Agent assignment matches use cases **YOU MUST** follow the established blueprint patterns exactly **EXECUTE** the agent creation process now. ``` </details>
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
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#2295
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?