Config¶

Pegg is configured with a single JSON file per machine plus a few project-local files. There is no YAML or TOML variant.

File locations¶

The global file is created with defaults on first run. A missing file is not an error — Pegg falls back to built-in defaults. An unparsable file is an error.

pegg files prints every resolved path and whether it exists.

Viewing the config¶

pegg config show

Prints the resolved configuration as pretty-printed JSON with every API key masked. There are no config get / config set subcommands — edit the file directly.

Reference¶

providers[]¶

Configured LLM providers. See Providers & Models.

Either provider or driver must be set.

logger¶

cache¶

session¶

notification¶

Desktop notifications while the app is in the background. See Notifications.

server¶

Used by pegg serve. See HTTP and ACP.

theme¶

See TUI themes for the list.

permission¶

Controls when tools may run. See Permissions.

compaction¶

Controls how Pegg manages context window pressure. Configurable from the TUI in Settings → Session → Compaction.

Strategies:

• tool-clearing — truncates individual tool output messages exceeding max_tool_output_chars. Applied passively on every LLM call.
• sliding-window — when the threshold is reached, keeps only the most recent N messages (calculated from token budget, falling back to max_messages).
• summarization — when the threshold is reached, uses a dedicated LLM agent to compress the conversation history into a summary. Falls back to sliding-window on failure.

Persistence: When a compaction runs, Pegg does not overwrite the original conversation. Instead, the compacted messages are stored in a new session linked to the previous one (a linked-list chain of sessions). The original session keeps its full history; the newest session in the chain holds the compacted messages and everything that follows. Loading a session always opens the newest session in its chain first — the compacted view — and scrolling up walks back through earlier (pre-compaction) conversations. When a session is resumed, compaction thresholds are re-checked against the loaded history, so sliding-window and tool-clearing also apply to resumed sessions.

smart_router¶

Selects the best model per agent and task instead of using one model for everything. When enabled, a decision model (JEV by default) picks a model from your configured providers for the orchestrator and each subagent. Pick Smart Router in the TUI at Settings → General → Model (listed above the regular models when enabled), or pass --model smart-router on the CLI for a single run.

Each agent entry accepts:

Routing behavior:

• Routing is a system hook (OnModelResolve) registered by the router and applied by every agent at run start, before the provider check — so it works uniformly in the CLI, TUI, HTTP/ACP servers, and the SDK without per-entry-point code. The routed model is what appears in sessions and usage records.
• The candidate list is built from every configured provider that has an API key. Per-agent preferences are offered first (by ID or display name), then all remaining models. Preference resolution: images when the task has attachments, else the difficulty bucket, else default.
• When the run has image attachments, models without image input support are dropped from the list (even beyond the images preference).
• The decision model's pick is always accepted — there is no confidence threshold.
• Resolution order: difficulty score question (when difficulty is configured for the agent) → decision model choice question → LLM selection (using the preferred model) → the preferred model itself.
• The orchestrator is routed when its run model is Smart Router (picked in the TUI model list or --model smart-router); subagents are always routed when the router is enabled.

memory¶

Persistent, markdown-based memory for coding agents. A background observer distills each run's tool uses into observations, a librarian curates them into markdown files, and a memory panel is injected into future runs. See Memory for the full guide.

mcp_servers¶

Map of server name to MCP server config.

language_servers¶

Map of server name to language server config.

Complete example¶

{
  "providers": [
    { "provider": "openai", "api_key": "sk-..." },
    {
      "provider": "openrouter",
      "api_key": "sk-or-..."
    },
    {
      "provider": "groq",
      "api_key": "gsk_...",
      "timeout": 60,
      "headers": { "X-Custom": "value" }
    },
    {
      "driver": "openai",
      "base_url": "http://localhost:11434/v1",
      "api_key": "ollama"
    }
  ],
  "logger": { "driver": "sqlite", "max_log_count": 1000 },
  "cache": { "driver": "sqlite" },
  "session": { "driver": "sqlite" },
  "server": {
    "host": "127.0.0.1",
    "port": 8080,
    "required_headers": { "Authorization": "Bearer secret" },
    "headers": { "X-Served-By": "pegg" }
  },
  "theme": "dark",
  "permission": {
    "default": "semi-ask",
    "judge_provider": "openrouter",
    "judge_model": "typesafe/jev-1.13",
    "judge_threshold": 0.8,
    "rules": { "bash": "ask", "write": "allow" }
  },
  "compaction": {
    "enabled": true,
    "strategy": ["tool-clearing", "sliding-window"],
    "threshold": 80,
    "max_messages": 50,
    "max_tool_output_chars": 4000
  },
  "smart_router": {
    "enabled": true,
    "agents": {
      "orchestrator": {
        "default": ["deepseek-v4-flash"],
        "difficulty": {
          "trivial": ["deepseek-v4-flash"],
          "moderate": ["deepseek-v4-flash"],
          "complex": ["deepseek-v3", "deepseek-r1"]
        },
        "images": ["deepseek-v4-flash-vision-exp"]
      },
      "planner": {
        "default": ["qwen3-coder", "qwen2.5-coder-32b"],
        "difficulty": {
          "trivial": ["qwen2.5-coder-7b"],
          "complex": ["qwen3-coder", "qwen2.5-coder-32b"]
        }
      },
      "developer": {
        "default": ["qwen2.5-coder-7b"],
        "difficulty": {
          "complex": ["deepseek-v3", "claude-sonnet"]
        },
        "images": ["claude-sonnet"]
      }
    }
  },
  "memory": {
    "enabled": true,
    "gate": "auto",
    "threshold": 0.6,
    "context_budget": 8000,
    "max_results": 5,
    "consolidate": true
  },
  "mcp_servers": {
    "db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DEBUG": "true" }
    },
    "remote": {
      "url": "https://example.com/sse",
      "headers": { "Authorization": "Bearer token" }
    }
  },
  "language_servers": {
    "gopls": {
      "command": "gopls",
      "filetypes": ["go"],
      "rootMarkers": ["go.mod"]
    }
  }
}

Project-local configuration¶

Only MCP and LSP servers support project-level files. Other settings are global.

{
  "mcpServers": {
    "db": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"] }
  }
}

{
  "languageServers": {
    "gopls": { "command": "gopls", "filetypes": ["go"], "rootMarkers": ["go.mod"] }
  }
}

Project entries override global entries with the same name. Setting "enabled": false on a project LSP entry removes an inherited server.

Environment variables¶

Pegg does not read API keys or config paths from environment variables. The only variable that affects behavior is HOME (via the OS home directory), which determines where ~/.pegg/ lives. Spawned MCP and LSP subprocesses inherit the parent process environment plus any env entries you configure.