Skip to main content
Remove one or more agents from .opencode/agents/. Supports single agents, categories, packs, and bulk removal.

​
Usage

npx opencode-agents uninstall <agent>

​
Uninstall Modes

​
Single Agent

Remove a specific agent by name: 
npx opencode-agents uninstall typescript-pro
The CLI will:
  • Delete .opencode/agents/<category>/<name>.md (or root for primary agents)
  • Remove the lock file entry from .manifest-lock.json
  • Clean up empty category directories
  • Report “not installed” if the agent doesn’t exist on disk

​
Category Mode

Remove all agents from one or more categories: 
# Single category
npx opencode-agents uninstall --category devops

# Multiple categories (comma or space separated)
npx opencode-agents uninstall --category devops,security
npx opencode-agents uninstall --category devops security
Available categories: languages, ai, web, data-api, devops, devtools, security, mcp, business, docs

​
Pack Mode

Remove all agents from one or more packs: 
# Single pack
npx opencode-agents uninstall --pack backend

# Multiple packs
npx opencode-agents uninstall --pack backend,devops
See list —packs for available packs.

​
Uninstall All

Remove every agent in the registry: 
npx opencode-agents uninstall --all
This removes all 69 agents and the lock file. The .opencode/agents/ directory will be empty.

​
Flags

​
--dry-run
boolean
default:"false"
Preview what would be removed without deleting any files.
npx opencode-agents uninstall --pack backend --dry-run

​
Mutual Exclusivity

These flags cannot be combined:
  • --all + --pack
  • --all + --category
  • --pack + --category
The CLI will exit with an error if you attempt to combine them.

​
Security

Symlink protection: The CLI refuses to delete symlinks. If an agent file is a symlink, uninstall will fail with a security error to prevent directory traversal attacks.

​
Examples

​
Uninstall a single agent

npx opencode-agents uninstall postgres-pro
# Agent "postgres-pro" removed.

​
Uninstall a category

npx opencode-agents uninstall --category security
# Uninstalling 5 agents from category "security"...
# 5 removed, 0 not found, 0 failed

​
Uninstall a pack with dry-run

npx opencode-agents uninstall --pack devops --dry-run
# Dry run — no files will be deleted
#
# Uninstalling pack "devops" (9 agents)...
# [dry-run] docker-specialist
# [dry-run] kubernetes-specialist
# [dry-run] terraform-specialist
# [dry-run] aws-specialist
# [dry-run] ci-cd-engineer
# [dry-run] linux-admin
# [dry-run] platform-engineer
# [dry-run] sre-engineer
# [dry-run] incident-responder
#
# 9 removed, 0 not found, 0 failed

​
Uninstall all agents

npx opencode-agents uninstall --all
# Uninstalling all 69 agents...
# 69 removed, 0 not found, 0 failed

​
Uninstall an agent that doesn’t exist

npx opencode-agents uninstall foobar
# Agent "foobar" not found.
# Did you mean: rust-pro, postgres-pro, python-pro?

​
Output Summary

After batch uninstallation (category, pack, or all), the CLI prints: 
5 removed, 0 not found, 0 failed
  • removed — Agents successfully deleted from disk
  • not found — Agents that were not installed
  • failed — Agents that encountered an error during deletion (e.g., permission denied, symlink detected)

​
Exit Codes

CodeMeaning
0All agents removed successfully (or not found)
1One or more agents failed to uninstall, or validation error

​
What Gets Deleted

  1. Agent file — .opencode/agents/<category>/<name>.md (or root for primary agents)
  2. Lock entry — Corresponding entry in .manifest-lock.json
  3. Empty directories — Category folders are removed if empty after uninstall
The .opencode/agents/ directory itself is not deleted, even if empty.
  • install — Install agents
  • list — See what agents are available
  • verify — Check installed agent integrity
  • rehash — Rebuild lock file from disk

Build docs developers (and LLMs) love

Get started for freeTalk to us