pi-provider-tama

Pi agent extension that auto-discovers models from a local tama server and registers them as a provider.

What it does

When pi starts (or on /reload), this extension:

1. Auto-detects tama on ports 11434 or 8080
2. Fetches available models from tama's API
3. Registers a tama provider in pi with all discovered models
4. Refreshes models on /reload (pi's built-in model store persists across sessions)

Models appear in /model immediately — no manual models.json editing needed.

Installation

Option A: npm (recommended)

pi install npm:pi-provider-tama

Option B: git

pi install git:github.com/danielcherubini/pi-provider-tama

Use -l to install to project scope (.pi/settings.json) instead of global:

pi install -l npm:pi-provider-tama

Option C: Local development

git clone https://github.com/danielcherubini/pi-provider-tama.git
cd pi-provider-tama
npm install

# Install from local path
pi install ./pi-provider-tama

Configuration

By default, the extension auto-detects tama on 127.0.0.1:11434 and 127.0.0.1:8080.

No configuration is needed if tama is running locally on the default port.

Remote tama server

Add the tama URL to ~/.pi/agent/settings.json:

{
  "packages": ["npm:pi-provider-tama"],
  "pi-provider-tama": {
    "url": "http://myserver:11434"
  }
}

Or use the TAMA_URL environment variable (takes priority over settings.json):

export TAMA_URL=http://myserver:11434

Priority order: TAMA_URL env var → settings.json → auto-detect localhost

Authentication

Interactive login (primary)

Run /login tama in the pi chat. You'll be prompted to choose a token source:

• Enter token — type or paste your tama API token interactively
• Use TAMA_TOKEN env var — delegates to the fallback path below

The stored credential is cached and reused on every provider registration until you run /login tama again.

Fallback sources (env var / settings.json)

If you prefer not to use interactive login, or as a backup when tama requires auth but no token was stored:

1. TAMA_TOKEN environment variable (highest priority):

   export TAMA_TOKEN=your-token-here

2. token field in ~/.pi/agent/settings.json:

   {
     "packages": ["npm:pi-provider-tama"],
     "pi-provider-tama": {
       "url": "https://tama.example.com",
       "token": "your-token-here"
     }
   }

The token is sent as Authorization: Bearer <token> on both model discovery and inference requests. When unset, no auth header is sent (fine for localhost).

Priority order: stored credential → TAMA_TOKEN env var → settings.json token → fallback "tama"

New in v0.81.0

Interactive auth via /login tama

The extension now supports interactive login through pi's auth system. Run /login tama to securely enter your API token without exposing it in environment variables or config files. The credential is stored and automatically resolved on every provider registration cycle.

See the Authentication section above for full details on the dual-path auth flow.

Backend-aware per-model compatibility

Each tama model now carries compatibility flags derived from its upstream backend metadata (llama.cpp, ONNX, etc.). The extension maps backends to the right compat settings automatically — for example, llama.cpp backends get maxTokensField: "max_tokens" and requiresToolResultName: false, while unknown backends receive sensible defaults.

No manual configuration needed; the flags are applied per-model at registration time.

Context overflow auto-compaction

pi v0.81.0 includes built-in context overflow detection (isContextOverflow()), which handles common overflow patterns from llama.cpp, Ollama, LM Studio, and other local backends. The extension no longer needs custom overflow handling — pi auto-compacts when the context exceeds available space.

Official package dependencies

This extension now depends on @earendil-works/pi-coding-agent (v0.81.0+) and @earendil-works/pi-ai (v0.81.0+), replacing the previous @mariozechner/pi-coding-agent fork. The migration brings native createProvider() support, cleaner auth wiring, and up-to-date type definitions.

How it works

The extension is an async factory: pi awaits it before resolving which models are available, so every tama model is registered before pi decides what's selectable.

On startup the factory:

1. Resolves the tama URL/token (env → settings.json → auto-detect localhost).
2. Fetches the live model list from /v1/opencode/models.
3. Creates a createProvider()-based provider and registers it with pi.

On /reload it re-fetches models from tama, so newly added models are picked up. Pi's built-in model store persists models across sessions. A new session ID is generated on each registration for Langfuse tracing.

Requires pi ≥ v0.81.0 with async-factory and createProvider() support (pi-mono ≥ Jan 2026). If tama is offline when pi boots, no tama models register — bring tama up and run /reload.

Discovered models are mapped to pi's provider format:

| Tama field | Pi field | Fallback | | ----------------------------------- | --------------- | ----------------------------- | | id (lowercased HF repo) | model id | — | | name (pretty display) | model name | id | | context_length or limit.context | contextWindow | 128000 | | limit.output | maxTokens | contextWindow / 16 or 8192| | modalities.input | input | ["text"] |

All models are registered with:

• api: "openai-completions" (OpenAI-compatible)
• reasoning: false
• cost: { input: 0, output: 0, ... } (local = free)
• compat: merged from default + backend-specific overrides (see Backend-aware compat)
• provider: "tama", api: "openai-completions" for pi's internal routing

Migrating from pi-tama

This package was previously published as pi-tama. To migrate:

1. Reinstall: pi install npm:pi-provider-tama
2. Rename the settings key in ~/.pi/agent/settings.json from "pi-tama" to "pi-provider-tama"
3. Uninstall the old package

Development

npm install
npm test          # Run tests in watch mode
npm run test:run  # Run tests once
npm run typecheck # Type check

Requirements

• tama running locally with tama serve
• pi ≥ v0.81.0 (with async-factory and createProvider() support)
• Peer dependency: @earendil-works/pi-coding-agent ^0.81.0, @earendil-works/pi-ai ^0.81.0

License

MIT