# pi-agent-extensions

Custom extensions for the [pi coding agent](https://github.com/badlogic/pi-mono).

## Extensions

| Extension | Description |
|-----------|-------------|
| [auto-rename](./auto-rename/) | Automatically generate session names based on first user query |
| [bash-picker](./bash-picker/) | Pick bash snippets from recent messages and copy to clipboard |
| [crosstalk](./crosstalk/) | Inter-session control socket and messaging (adapted from Armin Ronacher) |
| [pi-env-ctx](./pi-env-ctx/) | Exports Pi-native `AGENT_CTX_*` metadata (harness/session/model) to child processes |
| [oqto-todos](./oqto-todos/) | Todo management tools for Oqto frontend integration (drop-in replacement for OpenCode todowrite/todoread) |
| [read-image-guard](./read-image-guard/) | Replaces oversized `read` image payloads to prevent provider request-body overflows |
| [sudo](./pi-sudo/) | First-class `sudo_exec` tool with masked password prompt and `pam_faillock` lockout guard |
| [trx-picker](./trx-picker/) | Browse, filter, and multi-select trx issues from an overlay, dispatch to current or new tmux session |
| [inline-macros](./pi-inline-macros/) | Expand inline `::name` prompt macros using loaded prompt templates |
| [markdown-export](./pi-markdown-export/) | Export current session transcripts to Markdown via `/export-md` |
| [message-timestamps](./pi-message-timestamps/) | Show local time/date prefixes for user+assistant transcript messages in TUI |
| [history-search](./pi-history-search/) | `HistorySearch`/`HistoryRead` tools letting the agent search its own past sessions via a colocated SQLite FTS5 index (no external LLM; works with and without oqto) |

> **Note:** The `delegate` and `tmux-delegate` extensions have been removed in favor of [pi-subagents](https://github.com/nicobailon/pi-subagents) (`pi install npm:pi-subagents`), which provides structured JSON streaming, usage tracking, chain/parallel modes, and a TUI clarification overlay.

## Development

### Prerequisites

- Node.js 18+
- npm

### Setup

```bash
npm install
```

### Commands

| Command | Description |
|---------|-------------|
| `npm run check` | Run lint + typecheck |
| `npm run lint` | Biome linting only |
| `npm run lint:fix` | Auto-fix lint issues |
| `npm run typecheck` | tsgo type checking |

### Linting Rules

This repo uses [Biome](https://biomejs.dev/) with strict rules:

**Correctness:**
- `noUnusedVariables`: error - Catch dead code
- `noUnusedImports`: error - Keep imports clean

**Complexity:**
- `noExcessiveCognitiveComplexity`: warn (max 25) - Flag overly complex functions

**Style:**
- `noNonNullAssertion`: warn - Discourage `!` assertions
- `useConst`: error - Prefer `const` over `let`
- `useTemplate`: error - Prefer template literals over concatenation
- `noUnusedTemplateLiteral`: error - Don't use backticks for plain strings
- `noParameterAssign`: error - Don't reassign parameters
- `useDefaultParameterLast`: error - Default params at end
- `useShorthandArrayType`: error - Use `T[]` not `Array<T>`
- `useSingleVarDeclarator`: error - One variable per declaration

**Suspicious:**
- `noExplicitAny`: warn - Discourage `any` type
- `noConfusingVoidType`: error - Avoid confusing void usage
- `noDoubleEquals`: error - Use `===` not `==`
- `noEmptyBlockStatements`: warn - Flag empty blocks
- `noImplicitAnyLet`: error - Require types for `let`
- `noShadowRestrictedNames`: error - Don't shadow globals

**Performance:**
- `noAccumulatingSpread`: warn - Avoid spread in loops
- `noDelete`: warn - Prefer `undefined` over `delete`

**Security:**
- `noDangerouslySetInnerHtml`: error - Prevent XSS vectors

### Type Checking

Uses [tsgo](https://github.com/ArnaudBarre/tsgo) for fast TypeScript checking with strict settings.

## Creating a New Extension

1. Create a new directory: `mkdir my-extension`
2. Add `index.ts` with the extension code
3. Optionally add:
   - `README.md` - Documentation
   - `*.schema.json` - JSON Schema for config validation
   - `*.example.json` - Example configuration

See the [pi extension documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md) for the full API.

### Extension Template

```typescript
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  // Subscribe to events
  pi.on("session_start", async (_event, ctx) => {
    if (ctx.hasUI) {
      ctx.ui.notify("Extension loaded!", "info");
    }
  });

  // Register commands
  pi.registerCommand("my-command", {
    description: "Do something",
    handler: async (args, ctx) => {
      ctx.ui.notify(`Args: ${args}`, "info");
    },
  });
}
```

## Installation

### Via npm (recommended)

Published extensions can be installed directly via pi:

```bash
pi install npm:@byteowlz/pi-auto-rename
pi install npm:@byteowlz/pi-bash-picker
pi install npm:@byteowlz/pi-trx-picker
```

### Manual installation

To use extensions locally from this repo:

```bash
# Global installation (all projects)
cp -r <extension-name> ~/.pi/agent/extensions/

# Or project-local
cp -r <extension-name> .pi/extensions/

# Or symlink for development
ln -s $(pwd)/<extension-name> ~/.pi/agent/extensions/<extension-name>
```

## Publishing Extensions

Individual extensions can be published as npm packages under the `@byteowlz/` scope. Pi loads TypeScript directly via jiti, so no build step is needed.

```bash
just publish-setup auto-rename   # Prepare extension for npm
just publish-setup-all           # Prepare all extensions
just publish auto-rename         # Publish to npm
just publish-all                 # Publish all
just publish-bump auto-rename    # Bump version (patch/minor/major)
just publish-status              # Show setup and npm status
```

## License

MIT