How Authentication Works
PuzldAI doesn’t handle your AI credentials. It orchestrates the official CLI tools you already have installed:
| What PuzldAI Does | What PuzldAI Doesn’t Do |
|---|
Calls claude, gemini, codex binaries | Store your API keys |
| Passes prompts, receives responses | Handle OAuth flows |
| Respects each CLI’s auth state | Piggyback on private OAuth clients |
Log in once per CLI (e.g., claude login), and PuzldAI just orchestrates.
Model Selection
Pick specific models for each agent. Aliases like sonnet, opus, haiku point to the latest version.
TUI
/model # Open model selection panel
/model claude opus # Set Claude to use Opus
/model gemini gemini-2.0-flash # Set specific Gemini model
CLI
puzldai model show # Show current models
puzldai model list # List all available models
puzldai model list claude # List models for specific agent
puzldai model set claude opus # Set model for an agent
puzldai model clear claude # Reset to CLI default
Per-Task Override
puzldai run "task" -m opus # Override model for this run
puzldai agent -a claude -m haiku # Interactive mode with specific model
Router Configuration
The router decides which agent handles each task.
/router claude # Use Claude for routing decisions
/router ollama # Use Ollama (local, fast)
Settings Toggles
| Command | Description |
|---|
/sequential | Toggle: compare runs one-at-a-time vs parallel |
/pick | Toggle: auto-select best response from compare |
/execute | Toggle: auto-run autopilot plans |
/interactive | Toggle: pause between pipeline steps |
Configuration File
Settings are stored in ~/.puzldai/config.json:
{
"defaultAgent": "auto",
"fallbackAgent": "claude",
"routerModel": "llama3.2",
"adapters": {
"claude": { "enabled": true, "path": "claude", "model": "sonnet" },
"gemini": { "enabled": true, "path": "gemini", "model": "gemini-2.5-pro" },
"codex": { "enabled": false, "path": "codex", "model": "gpt-5.1-codex" },
"ollama": { "enabled": true, "model": "llama3.2" },
"mistral": { "enabled": true, "path": "vibe" }
}
}
Data Storage
PuzldAI stores data in ~/.puzldai/:
~/.puzldai/
├── config.json # User preferences
├── puzldai.db # SQLite database (sessions, memory, observations)
├── sessions/ # Legacy JSON session files
└── templates/ # Saved workflow templates
Project Instructions
PuzldAI auto-injects project instructions into prompts:
| File | Purpose |
|---|
AGENTS.md | Project-wide instructions |
CLAUDE.md, CODEX.md, etc. | Agent-specific instructions (root level) |
.cursorrules | Cursor IDE rules (also supported) |
.puzldai/claude.md, .puzldai/gemini.md | Per-agent custom instructions |
