{"id":51609545,"url":"https://github.com/gko/modular-agents","last_synced_at":"2026-07-12T06:01:54.293Z","repository":{"id":368896581,"uuid":"1286422826","full_name":"gko/modular-agents","owner":"gko","description":"Modular agent support for OpenCode. Define agents as folders with multiple prompt files instead of single .md files.","archived":false,"fork":false,"pushed_at":"2026-07-02T16:49:24.000Z","size":117,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T18:29:55.819Z","etag":null,"topics":["ai-agents","developer-tools","llm","modular","opencode","opencode-plugin","prompt-engineering"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/modular-agents","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-01T19:09:07.000Z","updated_at":"2026-07-02T16:49:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gko/modular-agents","commit_stats":null,"previous_names":["gko/modular-agents"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/gko/modular-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gko%2Fmodular-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gko%2Fmodular-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gko%2Fmodular-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gko%2Fmodular-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gko","download_url":"https://codeload.github.com/gko/modular-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gko%2Fmodular-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35383520,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","developer-tools","llm","modular","opencode","opencode-plugin","prompt-engineering"],"created_at":"2026-07-12T06:01:53.452Z","updated_at":"2026-07-12T06:01:54.283Z","avatar_url":"https://github.com/gko.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Modular Agents for OpenCode\n\n[![npmjs.com](https://img.shields.io/npm/v/modular-agents.svg?color=blue)](https://www.npmjs.com/modular-agents) [![tests](https://github.com/gko/modular-agents/actions/workflows/test.yml/badge.svg)](https://github.com/gko/modular-agents/actions/workflows/test.yml)\n\n\u003e Define agents as folders with multiple maintainable prompt files.\n\n## Features\n\n- Agents as folders instead of single files\n- Recursively includes all `.md` and `.txt` files\n- Supports all agent configuration fields via YAML frontmatter\n- Works alongside native single-file agents\n\n## Installation\n\n### From npm (Recommended)\n\n```bash\nopencode plugin modular-agents --global\n```\n\nOr add it to your `opencode.json`:\n\n```json\n{\n  \"plugin\": [\"modular-agents\"]\n}\n```\n\n### Local Development\n\nPlace `modular-agents.ts` and `package.json` in:\n\n- `.opencode/plugins/` (project level)\n- or `~/.config/opencode/plugins/` (global)\n\n## Usage\n\nCreate folders inside `.opencode/agents/` (project) or `~/.config/opencode/agents/` (global).\n\n### Folder Structure Example\n\n```\n.opencode/agents/rust-expert/\n├── index.md                 # Recommended\n├── rules/\n│   ├── core.md\n│   └── security.md\n├── examples/\n│   └── good-patterns.md\n├── constraints.md\n└── test/\n    └── index.md             # Included as normal content\n```\n\n### `index.md` – Recommended, Not Strictly Required\n\n- If `index.md` exists in the folder root, **OpenCode** parses it (frontmatter + base prompt).\n- The plugin then **enriches** that prompt with all other `.md`/`.txt` files found recursively.\n- If there is **no `index.md`**, the plugin will still create the agent using the folder name and all other files as the prompt. This is useful for trait-only / composable agents.\n\n**Example without `index.md`** (trait composition):\n\n```\n.opencode/agents/code-reviewer/\n├── pragmatic.txt\n├── security-focused.txt\n└── concise.txt\n```\n\nThis creates an agent called `code-reviewer` composed purely from the trait files.\n\n### How Files Are Merged\n\n- OpenCode handles the `index.md` (if present).\n- The plugin appends every other `.md` and `.txt` file (including `index.md` files inside subfolders).\n- YAML frontmatter in additional files is stripped.\n- Files are sorted alphabetically by relative path.\n- Subfolder `index.md` files become regular sections (e.g. `### test/index.md`).\n\n### Resulting Prompt\n\n```markdown\nYou are a senior Rust developer...\n\n### constraints.md\n...\n\n### rules/core.md\n...\n\n### test/index.md\n...\n```\n\nThis design lets you build large, maintainable agents from smaller reusable pieces.\n\n## Limitations\n\n- Changes require restarting the session.\n- Best suited for complex or large agents.\n\n## License\n\nThis project is open source and available under the [MIT](/LICENSE) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgko%2Fmodular-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgko%2Fmodular-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgko%2Fmodular-agents/lists"}