main

Pi Agent Configuration

Declarative configuration for pi coding agent.

Files

Declarative (Version Controlled)

  • auth-keys.json - API key providers with passage secret references
  • settings.json - Default settings template
  • AGENTS.md - Global agent instructions
  • keybindings.json - Custom keybindings
  • agents/ - Project-agnostic subagents
  • extensions/ - Custom pi extensions
  • prompts/ - Custom prompt templates

Runtime (Not Version Controlled)

  • ~/.pi/agent/auth.json - Generated, merges OAuth + API keys
  • ~/.pi/agent/settings.json - Generated, merges template + user prefs
  • ~/.pi/agent/sessions/ - Symlinked to ~/.local/share/ai-sync/pi-sessions/

Setup

# Install dotfiles (includes pi-agent target)
cd ~/src/home
make dots

# Or manually:
cd ~/src/home/dots
make pi-agent pi-agent-settings pi-agent-auth

Auth Management

API keys are declared in auth-keys.json with passage references:

{
  "google": {
    "type": "api_key",
    "key": "!passage show gemini/api_key"
  },
  "openrouter": {
    "type": "api_key",
    "key": "!passage show openroute/api_key"
  }
}

OAuth tokens (GitHub Copilot, Vertex, etc.) are managed by pi via /login command and preserved automatically.

The ensure-auth.sh script:

  1. Extracts existing OAuth tokens from ~/.pi/agent/auth.json
  2. Merges with declarative API keys from auth-keys.json
  3. Writes atomically with secure permissions (600)

Adding New API Keys

  1. Store secret in passage:

    passage insert provider-name/api_key

  2. Add to auth-keys.json:

    {
  "provider-name": {
    "type": "api_key",
    "key": "!passage show provider-name/api_key"
  }
}

  3. Re-run setup:

    make pi-agent-auth

Available Providers

Current passage-based API keys:

  • google - Gemini API (ai/gemini/api_key)
  • openrouter - OpenRouter API (ai/openroute/api_key)
  • deepseek - DeepSeek API (ai/deepseek/api_key)
  • groq - Groq API (ai/groq/wakasu)
  • mistral - Mistral API (ai/mistralai/api_key)
  • zai - Z.AI/GLM API (ai/zai/api_key) - Optional, ONLY for GLM-4.7-Flash (free API)

OAuth providers (managed by pi):

  • github-copilot - via /login github-copilot
  • vertex-anthropic - via /login vertex-anthropic

IMPORTANT - Z.AI Pricing Reality:

  • GLM-4.7-Flash - ✅ FREE API (only truly free GLM model)
  • GLM-4.7 - ❌ Requires Lite subscription ($10/mo minimum)
  • GLM-5 - ❌ Requires Pro subscription ($30/mo) or Max ($50+/mo)
  • “Limited-time free” is misleading marketing - models require paid subscriptions
  • Z.AI is NOT worth it - use free alternatives (DeepSeek-R1, Qwen, Gemini) instead

Settings Management

Required settings are declared in settings.json and merged into runtime config:

{
  "hideThinkingBlock": true,
  "quietStartup": true,
  "skills": ["~/.config/claude/skills"],
  "subagentProviderPreference": [
    "google-vertex-claude",
    "vertex",
    "google",
    "llama-cpp"
  ]
}

The ensure-settings.sh script merges these with user preferences, preserving:

  • Model selections
  • Custom providers
  • Theme preferences
  • Other user-specific settings

Session Storage

Pi sessions are symlinked to syncthing-managed directory:

  • Source: ~/.local/share/ai-sync/pi-sessions/
  • Link: ~/.pi/agent/sessions → source
  • Purpose: Sync raw JSONL conversation logs across machines

Curated markdown session summaries go to ~/.local/share/ai/sessions/ (also synced).

Extensions

Custom extensions in extensions/:

  • github/ - Enhanced GitHub integration
  • jira/ - Jira issue management
  • org-todos/ - Org-mode TODO integration
  • vertex-claude/ - Google Vertex AI Claude models
  • defaults/ - Default extensions wrapper
  • lsp/ - LSP integration
  • filter-output/ - Output filtering
  • shell-completions/ - Shell completion enhancements
  • threads/ - Thread/session management

Extensions are symlinked to ~/.pi/agent/extensions/ and npm dependencies are auto-installed.

Skills

Skills are shared with Claude Code via ~/.config/claude/skills/:

  • Pi loads via settings.json: "skills": ["~/.config/claude/skills"]
  • Enables unified skill library across AI coding tools

Keybindings

Custom keybindings in keybindings.json:

  • Ctrl+R: Reapply last edit
  • Ctrl+D: Show diff
  • See KEYBINDINGS.md for full documentation

Agents

Global agent instructions in AGENTS.md:

  • Core principles
  • Stack preferences
  • Response patterns
  • Git safety rules
  • Skills integration

Project-specific agents can be added to .pi/agents/ (not in dots).

Provider Recommendations

Best Free Models (Confirmed Forever Free)

  1. DeepSeek-R1 (OpenRouter) - Reasoning, matches OpenAI o1

    pi --provider openrouter --model "deepseek/deepseek-r1:free"
# or newer variant:
pi --provider openrouter --model "deepseek/deepseek-r1-0528:free"

    ⚠️ Important: Use the :free suffix - without it may route to paid providers!

  2. Qwen2.5-Coder-32B (OpenRouter) - Coding specialist

    pi --provider openrouter --model "qwen/qwen-2.5-coder-32b-instruct:free"

  3. GLM-4.7-Flash (Z.AI direct) - Fast coding, free forever

    pi --provider zai --model "glm-4.7-flash"

  4. Llama 3.3 70B (OpenRouter/Groq) - General purpose

    pi --provider groq --model "llama-3.3-70b-versatile"

  5. Gemini 2.0 Flash (Google) - 1M context window

    pi --provider google --model "gemini-2.0-flash-exp"

Z.AI subscription plans are expensive and not free:

Plan Price Models Worth It?
Free API $0 GLM-4.7-Flash only ✅ Use this
Lite $27-30/quarter GLM-4.7 (not GLM-5) ❌ No - use DeepSeek instead
Pro $81-90/quarter GLM-5 + GLM-4.7 ❌ No - GitHub Copilot Pro is $10/mo
Max $150+/quarter All models, high usage ❌ No - way overpriced

Avoid Z.AI subscriptions: Use free alternatives instead (DeepSeek-R1, Qwen, Gemini)

Avoid

  • ❌ Paid subscription plans unless you need higher rate limits
  • ❌ Models marked “limited-time free” for production use
  • ❌ Using OpenRouter for models that are cheaper direct (check pricing)

Cost Comparison: Why Z.AI Plans Don’t Make Sense

Service Monthly Cost What You Get Value
GitHub Copilot Pro $10 GPT-4o, Claude Sonnet 4.6, unlimited completions ⭐⭐⭐⭐⭐
Free Alternatives $0 DeepSeek-R1, Qwen2.5-Coder, Gemini Flash ⭐⭐⭐⭐⭐
OpenRouter Free $0 31 models, 50 req/day ⭐⭐⭐⭐
Cursor $20 GPT-4, Claude, unlimited ⭐⭐⭐⭐
Z.AI Lite $10 GLM-4.7 only, 400/week limit ⭐⭐
Z.AI Pro $30 GLM-5 + GLM-4.7, 400/5hrs ⭐
Z.AI Max $50+ All models, high usage ❌

Verdict: Z.AI plans are 3-5× more expensive than better alternatives. Use the free GLM-4.7-Flash API or stick with free alternatives.

OpenRouter Free Models: Important Notes

Always Use :free Suffix

OpenRouter has both free and paid routing for many models. To ensure you’re using the free tier:

# ✅ CORRECT - Explicitly free
pi --provider openrouter --model "deepseek/deepseek-r1:free"
pi --provider openrouter --model "qwen/qwen-2.5-coder-32b-instruct:free"
pi --provider openrouter --model "meta-llama/llama-3.3-70b-instruct:free"

# ❌ WRONG - May route to paid providers
pi --provider openrouter --model "deepseek/deepseek-r1"
pi --provider openrouter --model "qwen/qwen-2.5-coder-32b-instruct"

Free Tier Rate Limits

  • 20 requests/minute
  • 200 requests/day
  • No credit card required
  • No charges ever (with :free suffix)

List All Free Models

# In pi interactive mode
pi --provider openrouter
/model
# Filter for "(free)" models

Or check: https://openrouter.ai/collections/free-models