# @typewhisper/pi

Native [Pi](https://pi.dev) tools for [TypeWhisper](https://typewhisper.com), running locally or on a remote host.

The extension gives Pi direct access to transcription, history, models, and dictionary automation. With local discovery, no separate API key configuration is required.

## Requirements

- TypeWhisper on a reachable macOS or Windows host with the local API enabled under **Settings > Advanced**
- Pi 0.80.6 or newer
- Node.js 20 or newer

## Install

```bash
pi install npm:@typewhisper/pi
```

Then restart Pi. The extension discovers the running TypeWhisper app automatically on macOS and Windows.

To try it for one session without installing:

```bash
pi -e npm:@typewhisper/pi
```

## Tools

- `typewhisper_status`
- `typewhisper_list_models`
- `typewhisper_transcribe_file`
- `typewhisper_search_history`
- `typewhisper_list_dictionary_terms`
- `typewhisper_upsert_dictionary_terms`
- `typewhisper_delete_dictionary_term`
- `typewhisper_list_dictionary_corrections`
- `typewhisper_upsert_dictionary_correction`
- `typewhisper_delete_dictionary_correction`

Example requests:

```text
Transcribe ./meeting.m4a with TypeWhisper and summarize the decisions.
Search my TypeWhisper history for "release checklist".
Add "TypeWhisper" and "FluidAudio" to my recognition dictionary.
```

Relative file paths are resolved from Pi's current project directory. The extension also accepts absolute paths.

## Configuration

Normal installations need no configuration. These environment variables override automatic discovery when needed:

- `TYPEWHISPER_API_BASE_URL`
- `TYPEWHISPER_API_PORT`
- `TYPEWHISPER_API_TOKEN`
- `TYPEWHISPER_DEV=1` to connect to TypeWhisper Dev

Automatic discovery reads:

- macOS: `~/Library/Application Support/TypeWhisper/api-discovery.json`
- Windows: `%LOCALAPPDATA%\\TypeWhisper-UserData\\api-discovery.json`
- Windows legacy fallback: `%LOCALAPPDATA%\\TypeWhisper\\api-discovery.json`

Development builds use `TypeWhisper-Dev` on macOS and `TypeWhisper-DevUserData` with a `TypeWhisper-Dev` fallback on Windows.

## Remote TypeWhisper Host

The Pi extension can run on any platform supported by Pi and Node.js. TypeWhisper currently binds its API to the host's loopback interface, so connect through a private tunnel instead of exposing the API publicly:

```bash
ssh -N -L 18978:127.0.0.1:8978 user@typewhisper-host
```

Start Pi with the forwarded URL and the bearer token from the TypeWhisper host's `api-discovery.json`:

```bash
TYPEWHISPER_API_BASE_URL=http://127.0.0.1:18978 \
TYPEWHISPER_API_TOKEN="your-token" \
pi
```

Status, models, history, and dictionary tools work directly through the tunnel. For `typewhisper_transcribe_file`, the path must also exist on the TypeWhisper host, for example through a shared or synchronized directory.

## Development

```bash
npm install
npm run typecheck
npm test
pi -e .
```

The reusable API client and discovery logic live in [`@typewhisper/mcp`](https://www.npmjs.com/package/@typewhisper/mcp).