Skip to main content
OpenCode Agents supports three installation methods: an interactive TUI browser, a non-interactive CLI for automation, and a bash script for advanced use cases. All three methods install agents to .opencode/agents/ in your project.

​
Requirements

For TUI and CLI

Node.js 20 or higher — the CLI is zero-dependency and runs on Node.js built-ins only.

For bash script

Git and bash — the script clones the repo and creates symlinks or copies.

​
Method 1 — Interactive TUI

Recommended for first-time users. The TUI provides a visual browser with search, category tabs, and pack exploration.
The TUI launches automatically when you run the CLI in a terminal that supports TTY: 
npx github:dmicheneau/opencode-template-agent
Or explicitly: 
npx github:dmicheneau/opencode-template-agent tui

​
TUI features

  • Category tabs — browse agents by category (← → or Tab)
  • Agent list — navigate with ↑ ↓, select with Space
  • Search — press / to filter agents by name or description
  • Pack explorer — view and install predefined packs
  • Install confirmation — review selections before installing

​
TUI keyboard shortcuts

KeyAction
↑ ↓Navigate agent list
← →Switch category tabs
TabCycle through tabs
SpaceSelect/deselect agent
EnterInstall selected agents
/Open search
EscCancel or go back
qQuit

​
Method 2 — Non-interactive CLI

Best for automation, CI/CD, or scripting. All commands are non-interactive and suitable for pipelines.
The CLI provides commands for installing agents, packs, or categories without user interaction.

​
Install a single agent

npx github:dmicheneau/opencode-template-agent install typescript-pro

​
Install a pack

Install one or more predefined packs: 
npx github:dmicheneau/opencode-template-agent install --pack backend

​
Install by category

Install all agents in one or more categories: 
npx github:dmicheneau/opencode-template-agent install --category languages

​
Install all agents

Install the entire registry of 69 agents: 
npx github:dmicheneau/opencode-template-agent install --all

​
CLI options

OptionDescription
--forceOverwrite existing agent files
--dry-runPreview changes without writing files
--permissions <preset>Apply permission preset (strict, balanced, permissive, yolo)
--yoloSet all permissions to allow (requires typing CONFIRM)
--save-permissionsSave permission choices as default

​
List and search commands

npx github:dmicheneau/opencode-template-agent list

​
Update outdated agents

Reinstall agents whose installed file hash doesn’t match the registry: 
npx github:dmicheneau/opencode-template-agent update
Or as a flag: 
npx github:dmicheneau/opencode-template-agent install --update

​
Verify integrity

Verify that installed agent files match their lock file hashes: 
npx github:dmicheneau/opencode-template-agent verify

​
Rebuild lock file

Rebuild the lock file from disk (recompute hashes for all installed agents): 
npx github:dmicheneau/opencode-template-agent rehash

​
Uninstall agents

npx github:dmicheneau/opencode-template-agent uninstall postgres-pro

​
Method 3 — Bash script

For advanced users. The bash script clones the repo locally and creates symlinks (or copies) into your OpenCode config. Ideal for global installs or custom directory structures.
Run the install script directly from GitHub: 
curl -fsSL https://raw.githubusercontent.com/dmicheneau/opencode-template-agent/main/install.sh | bash
The script will:
  • Clone the repo to ~/.local/share/opencode-agents
  • Detect your OpenCode config (project .opencode/ or global ~/.config/opencode/)
  • Create symlinks in .opencode/agents/ pointing to the cloned repo
  • Preserve your existing opencode.json and agents

​
Bash script options

OptionDescription
--copyCopy agent files instead of creating symlinks
--dir PATHTarget directory (default: current directory)
--globalInstall into ~/.config/opencode/ instead of project .opencode/
--forceSkip interactive confirmations
--dry-runPreview actions without executing
--uninstallRemove previously installed agents

​
Examples

curl -fsSL https://raw.githubusercontent.com/dmicheneau/opencode-template-agent/main/install.sh | bash -s -- --global

​
Manual clone method

For full control, clone the repo and set OPENCODE_CONFIG_DIR:
1

Clone the repository

git clone https://github.com/dmicheneau/opencode-template-agent.git ~/.opencode-agents
2

Set OPENCODE_CONFIG_DIR

Add to your shell config (~/.zshrc, ~/.bashrc, etc.):
export OPENCODE_CONFIG_DIR=~/.opencode-agents
3

Reload your shell

source ~/.zshrc
Or restart your terminal.
OpenCode will now use the cloned repo as the agent source.

​
Where are agents installed?

All three methods install agents to the same location: 
.opencode/
├── agents/
│   ├── ai/
│   ├── business/
│   ├── data-api/
│   ├── devops/
│   ├── devtools/
│   ├── docs/
│   ├── languages/
│   ├── mcp/
│   ├── security/
│   ├── web/
│   └── manifest.json
├── agents.lock
└── opencode.json
  • Project install — .opencode/ in your project root
  • Global install — ~/.config/opencode/ (accessible from all projects)
The CLI and TUI never modify your opencode.json. Your existing configuration is always preserved.

​
Permission management

Agents declare required permissions in their frontmatter. The installer resolves permissions based on presets or explicit overrides.

​
Permission presets

PresetDescription
strictDeny all risky permissions by default
balancedAllow common workflows, deny destructive operations
permissiveAllow most operations, deny only high-risk actions
yoloAllow everything (requires typing CONFIRM)

​
Set permissions during install

npx github:dmicheneau/opencode-template-agent install --pack backend --permissions balanced

​
Command aliases

The CLI supports short aliases for common commands:
Full commandAliases
installi, add
uninstallremove, rm
listls
searchfind
npx github:dmicheneau/opencode-template-agent i typescript-pro
npx github:dmicheneau/opencode-template-agent ls
npx github:dmicheneau/opencode-template-agent rm typescript-pro

​
Next steps

Agent Catalog

Browse all 69 agents with quality scores and descriptions

Packs

Explore 15 predefined packs for common workflows

OpenCode Plugin

Install the plugin for LLM-powered agent discovery

CLI Reference

Full CLI command reference and flags

Build docs developers (and LLMs) love

Get started for freeTalk to us