Skip to content
OpenWaggle

Configuration files

Every file OpenWaggle reads its configuration from, with its JSON Schema.

This page lists every file OpenWaggle and Pi read configuration from, where it lives, what it holds, and its JSON Schema. <project> is the project’s root folder. ~ is your home folder. For when to use a project file instead of Settings, see Per-project configuration. For logs, the session database and other data OpenWaggle writes, see Data and file locations.

OpenWaggle files

FilePurposeWritten byJSON Schema
<project>/.openwaggle/settings.jsonProject settings: worker limits, the project’s access mode, saved approvals, source control hosts, and Pi settings in a pi object.You, and Settingsproject-settings.schema.json
<project>/.openwaggle/actions.jsonShared project actions, setup profiles, and worktree setup and cleanup.Settings > Project actions, when you share an actionproject-actions-v1.schema.json
<project>/.openwaggle/mcp.jsonThe project’s MCP servers.You, and Settings > MCPmcp.schema.json
~/.openwaggle/mcp.jsonYour MCP servers for every project.You, and Settings > MCPmcp.schema.json
<project>/.openwaggle/agents/*.mdThe project’s agent definitions.Youagent-definition-v1.schema.json, for the frontmatter
<project>/.agents/agents/*.mdMore project agent definitions, shared with other tools.Youagent-definition-v1.schema.json, for the frontmatter
~/.openwaggle/agents/*.mdYour agent definitions for every project.Youagent-definition-v1.schema.json, for the frontmatter
<project>/.openwaggle/skills/, extensions/, prompts/, themes/Skills, extensions, prompts and themes for OpenWaggle only.YouNone
<project>/AGENTS.mdInstructions the agent reads in every session. See Project instructions.YouNone

Every schema lives at https://openwaggle.ai/schemas/ followed by its file name.

Pi files

Pi is the agent engine inside OpenWaggle, and it reads its own files too. Paths under ~/.pi/agent/ move to the folder in PI_CODING_AGENT_DIR when you set that variable.

FilePurposeWritten byJSON Schema
~/.pi/agent/settings.jsonPi’s global settings, such as the default thinking level, defaultTools and cacheWarming.Pi, and youNone. See Pi’s settings reference.
<project>/.pi/settings.jsonPi’s settings for one project.YouNone
~/.pi/agent/auth.jsonProvider API keys and sign-ins. Keep it secret.Settings > Connections, and PiNone
~/.pi/agent/models.jsonCustom providers and models. See Custom providers.Youmodels.schema.json
~/.pi/agent/mcp.jsonYour MCP servers, shared with Pi.YouNone
<project>/.pi/mcp.jsonThe project’s MCP servers, shared with Pi.YouNone
<project>/.mcp.jsonThe project’s MCP servers, in the file other tools also read.YouNone
~/.pi/agent/waggle-presets.jsonYour Waggle presets for every project.Settings > Waggle Modewaggle-presets.schema.json
<project>/.pi/waggle-presets.jsonThe project’s Waggle presets.Settings > Waggle Modewaggle-presets.schema.json
<project>/.pi/skills/, extensions/, prompts/, themes/Pi skills, extensions, prompts and themes.YouNone
<project>/.agents/skills/, extensions/, prompts/, themes/Skills, extensions, prompts and themes shared with other agent tools.YouNone

New OpenWaggle sessions never take their thinking level from a project file. They ignore defaultThinkingLevel in <project>/.pi/settings.json and in the pi object of .openwaggle/settings.json. The exception is a session started with the pi command whose conversation never set a level. Continuing it in OpenWaggle uses the defaultThinkingLevel in the .pi/settings.json of the folder it ran in, then the global one, as pi --resume does. See Thinking levels.

The $schema key

File"$schema" key
.openwaggle/settings.jsonAllowed. OpenWaggle keeps it when it writes the file.
mcp.json in ~/.openwaggle/ or .openwaggle/Allowed. OpenWaggle keeps it when it writes the file.
Agent definition frontmatterAllowed. See Agent definitions.
.openwaggle/actions.jsonNot allowed. OpenWaggle rejects any unknown key, "$schema" included.
waggle-presets.jsonRemoved when Settings saves the file.

For the two files that cannot keep the key, point your editor at the schema instead. See Get completion in your editor.

.openwaggle/settings.json keys

Top-level keys belong to OpenWaggle. Pi’s own settings go in the pi object, with Pi’s names.

KeyTypeWhat it does
$schemastringThe file’s JSON Schema.
sessionHost.multiAgentEnabledbooleanLets agents create worker sessions in this project. Overrides Agent-created Workers.
sessionHost.parentConcurrencyLimitinteger, 1 or moreThe most runs one parent session’s direct workers can have at the same time. Overrides Workers per parent.
preferences.authorizationModeyolo or ask-for-approvalThe project’s access mode, written by Settings > Permissions > Selected project.
authorizationGrantsarraySaved approvals, written when you choose Always allow. Revoke them in Settings > Permissions.
sourceControl.hostsobjectThe provider of each host, github or gitlab, by host name.
sourceControl.changeRequestOpenDestinationinspector or websiteWhere pull and merge requests open for this project: in OpenWaggle or on the provider’s site.
piobjectPi settings for this project. The schema does not check it.
actionsarrayAn older format for project actions. OpenWaggle reads it only to move the actions to their new home.
preferences.modelstringNo longer used. OpenWaggle moves it into its own storage the next time it writes the file.

A value in this file wins over a value saved in the app, which wins over the app-wide default.

These pi keys affect OpenWaggle:

KeyWhat it does
treeFilterModeThe Session Tree filter to start with.
branchSummary.skipPromptSkips the summary question when you go back to an earlier point in the conversation.
compaction.enabledTurns automatic compaction on or off.
compaction.reserveTokensTokens compaction keeps free for the model’s reply.
compaction.keepRecentTokensRecent tokens compaction keeps without summarizing.

OpenWaggle ignores these, and sets them elsewhere instead:

KeySet it in
pi.compaction.thresholdPercentSettings > General > Context compaction, for every project.
pi.defaultThinkingLevelThe thinking-level menu beside the message box.
preferences.thinkingLevelThe thinking-level menu beside the message box.

Appearance, the default for New Sessions run in, and how long the background Session Host stays running when idle are app-wide and cannot be set in a project file.

MCP file order

OpenWaggle reads MCP servers from these files in this order. For a server name that appears in more than one file, the later file wins, so a project file beats a global one.

OrderFile
1~/.pi/agent/mcp.json
2~/.openwaggle/mcp.json
3<project>/.mcp.json
4<project>/.pi/mcp.json
5<project>/.openwaggle/mcp.json

Only the two OpenWaggle files can hold SSE and WebSocket servers and secret references. Names that differ only in - and _ count as the same server. See MCP connections.

Resource folder order

When a skill, extension, prompt or theme with the same name is in more than one project folder, the first folder wins:

OrderFolder
1<project>/.openwaggle/
2<project>/.pi/
3<project>/.agents/

Skills match by the name in their frontmatter, not by folder name. Enabled OpenWaggle extension packages can add skill folders between .openwaggle/skills/ and .pi/skills/. See Skills.

Agent definition order

Agent definitions match by the name in their frontmatter. When two have the same name, the first location wins, and an invalid file there does not fall through to the next one:

OrderLocation
1<project>/.openwaggle/agents/*.md
2<project>/.agents/agents/*.md
3~/.openwaggle/agents/*.md

See Agent definitions.