Pi

Pi is a minimal, MIT-licensed terminal coding harness from earendil-works/pi. Its core stays deliberately small and everything else is an extension — skills, prompt templates, custom tools, AGENTS.md context. Sessions are tree-structured, so you can branch mid-conversation and switch back, and /model swaps the active model at any point without restarting. Melious isn't one of its built-in providers, so you declare us once in models.json — after that, export a key and our tool-capable chat models show up in the picker.

Setup

melious tools install pi
melious launch pi

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

export MELIOUS_API_KEY=sk-mel-<YOUR_API_KEY>

{
  "providers": {
    "melious": {
      "name": "Melious",                                
      "baseUrl": "https://api.melious.ai/v1",           
      "api": "openai-completions",                      
      "apiKey": "$MELIOUS_API_KEY",                     
      "compat": { "supportsDeveloperRole": false },     
      "models": [                                       
        {                                               
          "id": "<MODEL_ID>",                           
          "name": "<Display Name>",                     
          "reasoning": true,                            
          "contextWindow": 203000,                      
          "maxTokens": 203000
        }                                               
      ]                                                 
    }                                                   
  }
}

pi

Picking a model

Your models.json decides what the picker holds — pi fetches nothing on its own. List every Melious model you want there, and filter the catalog to ones that serve chat and handle tool calls, the two things a coding agent needs. glm-5.1 is a solid all-rounder; qwen3-coder-next is a good deal cheaper if your work is mostly code and you don't need a reasoning model.

Pi's thinking-level picker offers seven levels — off, minimal, low, medium, high, xhigh, and max — on any model you mark "reasoning": true. Which of them actually change the request depends on the model. Sending an explicit "none" silences some of our models and is ignored by others, so going non-reasoning is the reliable path to no thinking at all.

Browse melious.ai/hub/models for current IDs, context windows, and capability flags.

Steering routing

Append a routing flavor to the model ID:

pi --model melious/glm-5.1:eco

• :speed — latency-biased provider selection
• :price — cheapest available provider
• :eco — greenest energy mix
• (no suffix) — balanced, our default

Pi reads a colon as a thinking level first — melious/glm-5.1:high sets effort — and falls back to treating an unrecognized suffix as part of the model ID. So a flavor works, but pi prints Warning: Model "glm-5.1:eco" not found for provider "melious". Using custom model id. on the way through. The request itself is fine.

One catch worth knowing: that fallback borrows its metadata from the first entry in your Melious model list. Flavor that model itself and the context window and pricing are correct. Flavor any other model and pi sizes and prices it as if it were the first one, which throws off the context meter and the session cost readout.

To fix that, and to get the flavored entry into the /model picker, declare it in ~/.pi/agent/models.json. New entries are added to what's already there rather than replacing it, so the rest stay put:

{
  "providers": {
    "melious": {
      "compat": { "supportsDeveloperRole": false },     
      "models": [
        {
          "id": "kimi-k3:eco",                          
          "name": "Kimi K3 (eco)",
          "reasoning": true,
          "contextWindow": 1000000,
          "maxTokens": 1000000
        }
      ]
    }
  }
}

The compat block is not optional here. It has to be repeated on any second models.json write, because pi doesn't merge it across entries — without it pi sends a developer role and we reject the request with Invalid role 'developer'.

What's different

• The model list is yours to keep current. Pi doesn't ship a Melious catalog and doesn't fetch one, so a model we add today won't appear until you add it to models.json. The Melious CLI writes that file from the live /v1/models on every launch, which is the way around it.
• Costs are shown in USD. Pi's session cost readout is dollar-denominated and we price in EUR, so the rates in your models.json are converted figures. Your usage dashboard is the euro-accurate source.
• Tool calling on supported models only. Pi sends OpenAI-shape tool_calls to our Chat Completions endpoint. Only list models that handle tools — check _meta.capabilities.function_calling on GET /v1/models?include_meta=true first.
• No explicit cache control. There's no field to mark a prefix as cacheable. Transparent prefix caching still happens on our side and comes back as usage.cached_tokens, billed at the cheaper cache-read rate. See Models.
• Custom response fields. With api: "openai-completions", non-streamed responses and the final usage chunk of a stream carry environment_impact and billing_cost, though pi's UI doesn't surface them — they're aggregated in your usage dashboard.

When it breaks

• Error: unknown tool: pi — your Melious CLI predates pi support, which arrived in v0.2.0. Update the CLI, or follow the manual setup above.
• pi --list-models melious is empty — either ~/.pi/agent/models.json is missing the provider entry above, or no key resolved. Pi hides models it can't authenticate.
• MELIOUS_API_KEY set but pi still won't authenticate — a stored credential beats the environment variable. Run /logout and pick Melious to drop it, or /login melious to replace it.
• Model "<MODEL_ID>:eco" not found ... Using custom model id — expected when you append a routing flavor. The request works; the context meter and cost readout borrow the first list entry's numbers. Declare the flavored ID in models.json to make them accurate.
• Rate limit errors during long sessions — you're on a plan with a per-minute token cap and the session's context is big. Rate limits explains which plan lifts which limit.

Errors and retry patterns: Errors.