@techdivision/opencode-cli

CLI tools for OpenCode plugin management.

Prerequisites

• Node.js >= 18
• npm >= 9

Installation

Option A: User-wide Plugins (recommended)

Install CLI globally and plugins in your user config directory:

# Install CLI globally
npm install -g github:techdivision/opencode-cli

# Install plugins in user config directory
cd ~/.config/opencode
npm install github:techdivision/opencode-plugins

# Link plugins (from user config directory)
opencode-link              # Links directly to ~/.config/opencode/commands/, etc.

# Or link in any project
cd /path/to/my-project
opencode-link              # Links to .opencode/commands/, etc.

Option B: Project-local Plugins

Install plugins locally in each project:

cd /path/to/my-project
mkdir -p .opencode && cd .opencode
npm install github:techdivision/opencode-plugins
npx opencode-link
cd ..

Option C: Global CLI + Local Plugins

Install CLI globally, plugins per project:

# Install CLI globally (once)
npm install -g github:techdivision/opencode-cli

# In each project: install plugins locally
cd /path/to/my-project/.opencode
npm install github:techdivision/opencode-plugins
cd ..

# Run from project root
opencode-link list         # Finds plugins in .opencode/node_modules/

Plugin Discovery

Plugins are discovered from two locations (priority: last wins):

Priority	Location	Path
1 (low)	User config	~/.config/opencode/node_modules/
2 (high)	Local	{project}/.opencode/node_modules/

Important: If a plugin exists in both locations, the local version wins.

Plugin Types

Monorepo Plugins

A monorepo contains multiple plugins in subdirectories, each with a .opencode/ folder.

Example: opencode-plugins

opencode-plugins/
├── package.json
├── core/
│   └── .opencode/
│       ├── commands/
│       ├── agents/
│       └── skills/
├── pm/
│   └── .opencode/
│       ├── commands/
│       └── agents/
└── magento/
    └── .opencode/
        └── commands/

Install: npm install github:techdivision/opencode-plugins

Singlerepo Plugins

A singlerepo is a standalone plugin with content directories in the package root.

Example: opencode-plugin-magento

opencode-plugin-magento/
├── package.json
├── plugin.json          # Plugin metadata (name, category, hooks)
├── commands/
│   ├── quality.md
│   └── deploy.md
├── agents/
│   └── magento-expert.md
└── skills/
    └── magento/
        └── ...

Install: npm install github:techdivision/opencode-plugin-magento

How Linking Works

When you run opencode-link <plugin>, the CLI:

1. Discovers plugins from user config and local node_modules/
2. Creates symlinks from target directory to plugin source files
3. Runs postlink hooks if defined in plugin.json

Example: Linking in a Project

cd /path/to/my-project
opencode-link magento

Before:

my-project/
└── .opencode/
    └── node_modules/
        └── @techdivision/opencode-plugin-magento/
            └── commands/
                ├── quality.md
                └── deploy.md

After:

my-project/
└── .opencode/
    ├── commands/
    │   ├── magento.quality.md -> ../node_modules/.../commands/quality.md
    │   └── magento.deploy.md  -> ../node_modules/.../commands/deploy.md
    └── node_modules/
        └── ...

Example: Linking in User Config

cd ~/.config/opencode
opencode-link time-tracking

Result:

~/.config/opencode/
├── config.json              # OpenCode main config (not touched)
├── commands/
│   ├── time-tracking.init.md -> ./node_modules/.../commands/init.md
│   └── time-tracking.timesheet.md -> ...
├── agents/
│   └── time-tracking.md -> ./node_modules/.../agents/time-tracking.md
└── node_modules/
    └── @techdivision/opencode-plugin-time-tracking/
        └── ...

Symlink Naming Convention

Content Type	Source File	Target Symlink
commands	commands/deploy.md	commands/{plugin}.deploy.md
agents	agents/expert.md	agents/expert.md
guidelines	guidelines/style.md	guidelines/style.md
skills	skills/group/skill-name/	skills/skill-name/
tools	tools/my-tool.ts	tools/my-tool.ts

Note: Commands are prefixed with the plugin name to avoid conflicts between plugins.

Commands

Command	Description
opencode-link	Link all standard plugins
opencode-link all	Link ALL plugins (standard + optional)
opencode-link <plugin>	Link a specific plugin
opencode-link list	List available plugins
opencode-link status	Show current links
opencode-link clean	Remove all symlinks
opencode-link schema	Regenerate schema

Options

Flag	Description
--target-dir=<path>	Override target directory
--singular	Use singular directory names (agent/ instead of agents/)

Programmatic Usage

You can also use the CLI modules programmatically:

import { discoverPlugins, getContentTypes } from '@techdivision/opencode-cli/discovery';
import { createSymlink, getItemsToLink } from '@techdivision/opencode-cli/linker';
import { generateCombinedSchema } from '@techdivision/opencode-cli/schema';

// Discover plugins
const plugins = discoverPlugins('/path/to/.opencode');
console.log(`Found ${plugins.size} plugins`);

// Get all content types
const types = getContentTypes(plugins);
console.log(`Content types: ${types.join(', ')}`);

License

MIT