For teams: coding agents on the self-hosted models you're allowed to run - see early access →

Configuration

Run polyglot init for a guided way to create ~/.polyglot/settings.json - it runs automatically on a fresh install. Everything below is the full reference for editing it by hand.

Configuration is resolved from, in increasing precedence:

~/.polyglot/settings.json (global)
.polyglot/settings.json in the current project
environment variables
launch flags (a few settings can be tightened, never loosened, by a CLI flag)

Lists and maps (models, permissions.allow, permissions.deny, mcpServers, pricing) are merged across the global and project files, not replaced.

`settings.json`

{
  "provider": "openai-compatible",
  "model": "qwen2.5-coder",
  "baseURL": "http://localhost:11434/v1",
  "apiKey": "",
  "structuredOutput": false,
  "probeCapabilities": false,
  "subAgents": true,
  "subAgentModel": "qwen2.5-coder:7b",

  "routing": {
    "failover": ["claude-sonnet-5", "qwen3-coder"],
    "summaryModel": "qwen3-coder",
    "planModel": "claude-opus-5"
  },

  "permissions": {
    "mode": "manual",
    "allow": [],
    "deny": ["bash:rm -rf *"]
  },

  "persistTranscripts": true,
  "retentionDays": 30,

  "audit": { "enabled": false, "hashArgs": true },

  "redaction": { "mode": "warn", "pii": false },

  "hooks": {
    "preToolUse": [{ "command": "./hooks/policy.sh", "tools": ["bash"] }],
    "allowProjectHooks": false
  },

  "pricing": {
    "my-local-model": { "input": 0, "output": 0 }
  },

  "webSearch": {
    "provider": "duckduckgo",
    "apiKey": "",
    "baseURL": ""
  },

  "models": [
    { "provider": "anthropic", "model": "claude-sonnet-4-5", "label": "Claude Sonnet" }
  ],

  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/an/allowed/dir"]
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_MCP_TOKEN}" }
    }
  },

  "autoUpdate": true
}

Key	Type	Default	Notes
`provider`	`"anthropic"` \| `"openai-compatible"`	-	Required.
`model`	string	-	Required. The id the provider expects.
`baseURL`	string	`http://localhost:11434/v1`	`openai-compatible` only.
`apiKey`	string	-	Required for `anthropic`. Optional for local `openai-compatible`. Prefer env vars.
`structuredOutput`	boolean	`false`	`openai-compatible` only. What it does.
`probeCapabilities`	boolean	`false`	`openai-compatible` only. On startup, ping the endpoint once to learn its real context window (for Ollama, from its own API) and whether it honors structured output, cached in `~/.polyglot/capabilities.json`. `--probe` forces a fresh probe.
`subAgents`	boolean	on for `anthropic`, off for `openai-compatible`	Whether the `task` sub-agent tool is offered. Multi-agent.
`subAgentModel`	string	- (use the parent’s model)	Model id/label for `task` sub-agents to run on - a cheaper one is an easy cost win. Multi-agent.
`routing.failover`	string[]	`[]`	Ordered fallback models. If the active model errors or stops producing valid tool calls mid-turn, the turn continues on the next one. Model routing.
`routing.summaryModel`	string	-	Model to run `/compact` and automatic compaction on.
`routing.planModel`	string	-	Model to run plan-mode turns on (off for the session after a manual `/model` switch).
`pricing`	object	`{}`	Per-model price overrides for the `/cost` estimate, keyed by model id: `{ "input": <USD/1M>, "output": <USD/1M>, "cachedInput"?: <USD/1M> }`. Wins over the built-in Anthropic table; the way to put a rate on a local model.
`audit.enabled`	boolean	`false`	Write a JSONL record of every tool call, permission decision, result, usage and stop reason to `~/.polyglot/audit/<session>.jsonl`.
`audit.hashArgs`	boolean	`true`	`true` stores tool-call arguments and results as SHA-256 hashes; `false` keeps them raw.
`audit.path`	string	`~/.polyglot/audit`	Override the audit directory.
`redaction.scanOutput`	boolean	`true`	Scan every tool result for secrets before it reaches the model. Secret scanning.
`redaction.mode`	`"warn"` \| `"redact"`	`"warn"`	`"warn"` flags findings; `"redact"` replaces them with `[redacted:<label>]`.
`redaction.pii`	boolean	`false`	Also scan for email / SSN / card / phone.
`redaction.extraPatterns`	array	`[]`	`{ "label": string, "regex": string }` entries - your own patterns.
`hooks.preToolUse` \| `hooks.postToolUse` \| `hooks.userPromptSubmit`	array	`[]`	Shell commands run at lifecycle points. `{ "command": string, "tools"?: string[], "timeoutMs"?: number }`. Hooks.
`hooks.allowProjectHooks`	boolean	`false`	Global file only. Whether hooks in a project `.polyglot/settings.json` run at all.
`permissions.mode`	`"manual"` \| `"auto"` \| `"plan"`	`"manual"`	Permission modes.
`permissions.allow`	string[]	`[]`	Rule syntax.
`permissions.deny`	string[]	`[]`	Checked before everything else.
`persistTranscripts`	boolean	`true`	`false` = ephemeral, nothing written to `~/.polyglot/`.
`retentionDays`	positive integer	- (keep forever)	Delete transcripts & plans older than N days on startup.
`webSearch.provider`	`"duckduckgo"` \| `"searxng"` \| `"tavily"` \| `"brave"`	`"duckduckgo"`	Web search.
`webSearch.apiKey`	string	-	Required for `tavily` / `brave`.
`webSearch.baseURL`	string	-	The SearXNG instance URL.
`models`	array	`[]`	Multiple models.
`mcpServers`	object	`{}`	Each entry is local (`command`, `args`, `env`) or remote (`url`, optional `transport` `"http"`/`"sse"`, optional `headers` with `${VAR}` read from the environment). MCP servers.
`autoUpdate`	boolean	- (asks on first run)	Global file only; never merged from a project file.

Environment variables

Variable	Overrides
`POLYGLOT_PROVIDER`	`provider`
`POLYGLOT_MODEL`	`model`
`POLYGLOT_BASE_URL`	`baseURL`
`POLYGLOT_API_KEY`	`apiKey` for `openai-compatible`
`ANTHROPIC_API_KEY`	`apiKey` for `anthropic` (the standard Anthropic variable)
`POLYGLOT_STRUCTURED_OUTPUT`	`structuredOutput` (`true`/`1`/`false`/`0`)
`POLYGLOT_PROBE`	`probeCapabilities` (`true`/`1`/`false`/`0`)
`POLYGLOT_SUB_AGENTS`	`subAgents` (`true`/`1`/`false`/`0`)
`POLYGLOT_SUB_AGENT_MODEL`	`subAgentModel`
`POLYGLOT_ROUTING_FAILOVER`	`routing.failover` (comma-separated)
`POLYGLOT_SUMMARY_MODEL`	`routing.summaryModel`
`POLYGLOT_PLAN_MODEL`	`routing.planModel`
`POLYGLOT_AUDIT`	`audit.enabled` (`true`/`1`/`false`/`0`)
`POLYGLOT_NO_INSTRUCTIONS`	Set to `1`/`true` to skip loading `AGENTS.md` / `POLYGLOT.md` entirely. Project instructions.
`POLYGLOT_NO_AGENTS`	Set to `1`/`true` to skip loading `.polyglot/agents/`. Agent definitions.
`POLYGLOT_NO_SKILLS`	Set to `1`/`true` to skip loading `.polyglot/skills/`. Skills.
`POLYGLOT_NO_OUTPUT_SCAN`	Set to `1`/`true` to turn off secret scanning of tool output.
`POLYGLOT_REDACT_OUTPUT`	Set to `1`/`true` to force `redaction.mode: "redact"` for the run.
`POLYGLOT_NO_HOOKS`	Set to `1`/`true` to disable all hooks.
`POLYGLOT_PERMISSION_MODE`	`permissions.mode`
`POLYGLOT_NO_PERSIST`	forces `persistTranscripts` off (`1`/`true`)
`POLYGLOT_RETENTION_DAYS`	`retentionDays`
`POLYGLOT_WEBSEARCH_PROVIDER`	`webSearch.provider`
`POLYGLOT_WEBSEARCH_API_KEY`	`webSearch.apiKey`
`POLYGLOT_WEBSEARCH_BASE_URL`	`webSearch.baseURL`

Project instructions

Polyglot reads AGENTS.md and POLYGLOT.md from the project root (and from ~/.polyglot/ for global rules) and prepends them to the system prompt, so you can give the agent standing project context - build commands, conventions, “don’t touch generated/”. This is a file, not a settings.json key. See Project instructions for the load order, precedence, and size cap; POLYGLOT_NO_INSTRUCTIONS=1 disables it.

Agents and skills

Two more file conventions under .polyglot/, also not settings.json keys:

.polyglot/agents/<name>.md - a named sub-agent (system prompt + optional tool allowlist and model), invoked with @name <task>. Agent definitions.
.polyglot/skills/<name>/SKILL.md - an instruction bundle switched on for a session with @name. Skills.

Both also load from ~/.polyglot/ for definitions available in every project, and are disabled by POLYGLOT_NO_AGENTS=1 / POLYGLOT_NO_SKILLS=1.

Secret scanning and hooks

Two settings.json blocks that gate what the agent sees and does:

redaction - scans every tool result for secret-looking values before they reach the model. On by default in warn mode. See Secret & PII scanning.
hooks - shell commands run at preToolUse / postToolUse / userPromptSubmit that can block an action or add context. Hooks in a project .polyglot/settings.json are ignored unless the global file sets hooks.allowProjectHooks: true. See Hooks.

Model routing

The routing block wires up three behaviours, all opt-in, all resolving model ids/labels against models[] the same way /model <query> does:

failover - an ordered list. When the active model errors out or stops producing valid tool calls in the middle of a turn, the turn continues on the next model instead of stopping. The switch is sticky for the rest of the session.
summaryModel - runs /compact and automatic compaction (bulk summarisation) on a cheaper model.
planModel - runs plan-mode turns on a dedicated model; disabled for the session once you switch models manually with /model.

Full details and examples: Model routing.

Prompt caching

With the anthropic provider, Polyglot marks the system prompt (persona + tool docs

project instructions) as cacheable. It’s identical on every turn of a session, so from the second turn on Anthropic serves it from cache at roughly a tenth of the input-token price and with lower latency. Nothing to configure; /cost already reflects the discount.

Auto-update

On first run Polyglot asks whether it should update itself when a new version is published, and stores the answer as autoUpdate in the global settings file. From then on, every startup does a quick non-blocking npm-registry check:

true → runs the appropriate global reinstall in the background (npm/pnpm/yarn/bun, auto-detected) and tells you to restart.
false → prints a notice with the manual update command.
Offline or a registry hiccup → fails silently, never blocks startup.

Change it any time by editing autoUpdate in ~/.polyglot/settings.json.