---
slug: "pi-command"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/niels-bosman/pi-command@main/README.md"
repo: "https://github.com/niels-bosman/pi-command"
source_file: "README.md"
branch: "main"
---
# pi-command

A [Pi](https://pi.dev) package that makes reusable command files from Claude Code, Gemini CLI, and Codex available inside Pi.

It supports:

- Claude Code markdown commands in `.claude/commands/**/*.md` and `~/.claude/commands/**/*.md`
- Gemini CLI TOML commands in `.gemini/commands/**/*.toml` and `~/.gemini/commands/**/*.toml`
- Gemini markdown commands in `.gemini/commands/**/*.md` for teams that use that convention
- Codex markdown prompts in `.codex/prompts/**/*.md` and `~/.codex/prompts/*.md`

## Install

```bash
pi install npm:pi-command
```

Then restart Pi or run:

```txt
/reload
```

## Local testing

From this checkout:

```bash
pi -e ../../personal/pi-command
```

Or install it as a local Pi package:

```bash
pi install ../../personal/pi-command
```

Then restart Pi or run:

```txt
/reload
```

## Usage

### Invoke a command file directly

```txt
@.claude/commands/release.md
run @.claude/commands/release.md
@.gemini/commands/git/commit.toml staged changes only
```

When the whole input is a supported command-file reference, `pi-command` expands the command and sends the expanded prompt to the active model.

### Invoke as slash commands

Discovered files are also registered as Pi slash commands:

```txt
/release
/claude:release
/command release
/command @.claude/commands/release.md
/command-list
```

Nested Gemini-style files use colon names. For example:

```txt
.gemini/commands/git/commit.toml -> /git:commit
```

Codex prompts use the Codex convention:

```txt
~/.codex/prompts/draftpr.md -> /prompts:draftpr
```

### Model invocation

The extension registers a `pi_command` tool. If you ask any Pi model/provider to run a reusable command, the model can call `pi_command`, receive the expanded command instructions, and carry them out.

## Expansion support

- Markdown frontmatter: `description`, `argument-hint`, `disable-model-invocation`
- Gemini TOML fields: `prompt`, `description`, `argument-hint`
- Arguments: `$1`-`$9`, `$0`, `$ARGUMENTS`, `$@`, `${@:N}`, `${@:N:L}`
- Codex named placeholders: uppercase `KEY=value` arguments can fill `$KEY`
- Gemini `{{args}}` replacement and default argument appending
- File references: Claude `@path` and Gemini `@{path}`
- Shell snippets: Claude ``!`cmd` `` and Gemini `!{cmd}` with user confirmation before execution

The extension does not enforce Claude `allowed-tools` or `model` metadata; Pi's current tool/model settings remain in charge.

## Development

```bash
npm install
npm run check
npm run pack:dry
```

## License

MIT