pi-unify-cmd

Load slash commands from Claude Code, OpenCode, Codex, and Gemini CLI into pi — unified via the adapter pattern.

Features

• Unified slash commands — discover .md and .toml command files from Claude Code, OpenCode, Codex, and Gemini CLI and register them as pi slash commands
• Agent-prefixed naming — each command gets a clear prefix (e.g. /claude:review, /codex:opsx-apply, /gemini:change)
• Argument interpolation — normalises all agent-specific argument syntax ($ARGUMENTS, $1, $@, {{args}}) into pi's native format
• Recursive scanning — walks subdirectories and flattens nested paths into command names (e.g. bkfw/pr-resolve.md → /opencode:bkfw__pr-resolve)
• Multi-directory support — combine multiple global and project-level roots per adapter
• Custom adapters — add your own command sources with configurable formats (yaml-frontmatter, gemini-toml, raw)
• Zero-config defaults — works out of the box with standard agent directory layouts
• Management commands — /unify-cmd:list, /unify-cmd:reload, /unify-cmd:scan, /unify-cmd:config

Installation

For Humans

# Via pi CLI
pi --add-package pi-unify-cmd

# Or add manually to ~/.pi/agent/settings.json packages array:
#   "pi-unify-cmd"

For AI Agents

Add to your settings.json packages list:

{
  "packages": ["pi-unify-cmd"]
}

Agent prompt reference: https://github.com/buihongduc132/pi-unify-cmd/blob/main/README.md

For pi git-sourced

Add to settings.json as a git-sourced extension:

{
  "packages": [
    {
      "name": "pi-unify-cmd",
      "url": "https://github.com/buihongduc132/pi-unify-cmd.git"
    }
  ]
}

Usage

Once installed, commands from other agents are automatically discovered and available with prefixed names:

/claude:review          Review the current changes
/codex:opsx-apply      Apply an OpenAI SpecX operation
/gemini:change         Apply a Gemini CLI change
/opencode:bkfw__pr-resolve  Resolve a PR (nested command)

Argument Interpolation

All agent-specific argument syntax is normalised:

Agent	Syntax	Example
Claude	$ARGUMENTS	Review: $ARGUMENTS
Codex	$1, $@, ${@:N:L}	Create $1 with $@
Gemini	{{args}}	Run: {{args}}
Pi	$1, $@, ${@:N:L}	Build $1 ${@:2}

Management Commands

/unify-cmd:list    — List all discovered commands
/unify-cmd:reload  — Rescan all directories
/unify-cmd:scan    — Show directory discovery details
/unify-cmd:config  — Show current configuration

Supported Agents

Agent	Format	Global roots	Project roots
Claude Code	YAML frontmatter	~/.claude/commands/	.claude/commands/
OpenCode	YAML frontmatter	~/.config/opencode/commands/, ~/.config/opencode/command/, ~/.config/opencode/profiles/default/commands/	.opencode/commands/, .opencode/command/
Codex	YAML frontmatter	~/.codex/prompts/	—
Gemini	TOML + YAML frontmatter	~/.gemini/commands/	—
Custom	Configurable	Configurable	Configurable

Configuration

Global: ~/.pi/agent/unify-cmd.json Project: .unify-cmd.json

{
  "agents": {
    "claude": {
      "enabled": true,
      "globalDir": "~/.claude/commands",
      "projectDir": ".claude/commands",
      "recursive": true
    },
    "opencode": {
      "enabled": true,
      "globalDirs": [
        "~/.config/opencode/commands",
        "~/.config/opencode/command",
        "~/.config/opencode/profiles/default/commands"
      ],
      "projectDirs": [".opencode/commands", ".opencode/command"],
      "recursive": true
    },
    "codex": { "enabled": true, "globalDir": "~/.codex/prompts", "recursive": true },
    "gemini": { "enabled": true, "globalDir": "~/.gemini/commands", "recursive": true }
  },
  "custom": [
    {
      "name": "my-agent",
      "enabled": true,
      "globalDir": "~/.my-agent/cmds",
      "format": "yaml-frontmatter"
    }
  ],
  "labelFormat": "[{scope}] ({agent}) | {description}",
  "prefixFormat": "{agent}:{name}"
}

Config Options

Option	Description	Default
agents.*.enabled	Enable/disable agent	true
agents.*.globalDir	Single global commands directory	agent-specific
agents.*.globalDirs	List of global commands directories (combined with globalDir, deduped)	agent-specific
agents.*.projectDir	Single project-level commands directory	agent-specific
agents.*.projectDirs	List of project-level commands directories	agent-specific
agents.*.recursive	Walk subdirectories; flatten nested names	true for built-ins
agents.*.nameSeparator	Separator for flattening nested paths into names	"__"
custom	Array of custom adapter configs	[]
labelFormat	Autocomplete description format	[{scope}] ({agent}) | {description}
prefixFormat	Command name format	{agent}:{name}

Tokens: {scope} → G/L, {agent} → agent name, {name} → command name, {description} → command description

Custom Adapters

Add your own command sources with format: "yaml-frontmatter" | "gemini-toml" | "raw".

Architecture

extensions/
├── index.ts            ← Extension entry: registerCommand + management cmds
├── discovery.ts        ← discoverCommands (multi-dir, dedupe) — pure, testable
├── index-helpers.ts    ← Pure functions: arg interpolation, label/name formatting
├── adapters.ts         ← CommandAdapter interface + 5 adapters + recursive scan
├── config.ts           ← Config loader (global + project deep merge)
├── types.ts            ← Shared types + defaults
└── *.test.ts           ← 70 tests

Adapter pattern: each agent has an adapter that knows how to scan its directory and parse its format. All adapters implement the CommandAdapter interface. Custom adapters use the same interface with configurable format.

License

MIT