# Extensions

Extensions let you customize Voxcode behavior without forking core code. They are loadable modules that hook into the agent runtime.

## What Extensions Can Do

- register custom tools and slash commands
- hook into lifecycle events (session start, tool call, response)
- modify prompts and runtime behavior
- provide custom provider integrations
- add validation, logging, or telemetry

## Common Use Cases

- organization-specific helper commands
- guarded workflows (approval gates, policy checks)
- custom provider adapters
- telemetry/logging integration hooks

## Extension API

Extensions export an object (or default export) conforming to the extension interface:

```typescript
interface VoxcodeExtension {
  name: string;
  setup(context: ExtensionContext): void | Promise<void>;
}
```

The `ExtensionContext` provides access to:
- `pi.registerCommand(name, handler)` — add a slash command
- `pi.registerTool(name, schema, handler)` — add a custom tool
- `pi.on(event, callback)` — subscribe to lifecycle events
- `pi.config` — read resolved configuration

## How to Add an Extension

1. Create an extension module in your project or user extension directory
2. Export extension entrypoint using Voxcode extension API
3. Load extension via `extensions` config array or `--extend` CLI flag
4. Validate behavior with a dedicated test or sandbox session

Example:

```typescript
// my-extension.ts
import type { ExtensionContext } from "@voxcode-dev/voxcode";

export default {
  name: "my-extension",
  setup(ctx: ExtensionContext) {
    ctx.pi.registerCommand("summary", async (args) => {
      // custom slash command logic
    });
  },
};
```

## Loading Extensions

Extensions can be loaded from:
- local file paths (`./extensions/my-ext.ts`)
- npm packages (`@voxcode-dev/my-ext`)
- user extension directory (`~/.config/voxcode/extensions/`)

Specify in settings:

```json
{
  "extensions": ["./path/to/extension.ts"]
}
```

Or via CLI:

```bash
vox --extend ./path/to/extension.ts
```

## Extension Safety Guidelines

- Scope extension permissions to what is necessary
- Avoid hidden side effects
- Log critical actions for auditability
- Keep extension code versioned and reviewed

## Suggested Workflow

1. Prototype with a minimal extension
2. Add one capability at a time
3. Document inputs/outputs and error behavior
4. Share via internal package if reused across teams

See examples in `packages/voxcode/examples/extensions/`.
