Configuration reference

Every file Agentty keeps, and every key in settings.json.

Agentty stores everything in ~/.agentty/. Most of it is easier to change in Settings (⌘,).

Files#

PathPurpose
~/.agentty/settings.jsonPreferences
~/.agentty/workspaces.jsonWorkspaces, tabs, splits and groups
~/.agentty/themes/*.itermcolorsImported color themes
~/.agentty/pricing.jsonPrices for non-Claude models
~/.agentty/handoffs/Context documents from Orchestration (session links) and agent migration
~/.agentty/connectors.jsonAPI connector definitions (no secrets)
~/.agentty/agent-auth.jsonSign-in method for new agent tabs (no secrets)
~/.agentty/codex-home/Private Codex home for API-key sign-in
~/.agentty/worktrees/Worktrees created per session
~/.agentty/plugins/Installed plugins
~/.agentty/plugin-data/<id>/Each plugin's own data
~/.agentty/prompts/Long prompts handed to agents as files
~/.agentty/install_idRandom installation identifier for usage statistics
agentty.json (project) or ~/.agentty/commands.jsonCustom command palette entries

Secrets are never in these files. They live in the operating system's credential store.

settings.json#

json
{
  "language": "en",
  "theme": "Agentty Dark",
  "fontFamily": "JetBrains Mono",
  "fontSize": 13.0,
  "lineHeight": 1.25,
  "cursorShape": "block",
  "scrollback": 10000,
  "askDirectory": true,
  "autoWorktree": true,
  "agentTasks": true,
  "orchestration": true,
  "orchestrationProfile": "balanced",
  "orchestrationHelpersOff": [],
  "orchestrationConfirmPlan": true,
  "orchestrationInTab": false,
  "analytics": true,
  "agentBarPosition": "top"
}
KeyValues
languageen, ko, ja, zh, de
themeA built-in theme name, or an imported .itermcolors file name without the extension
fontFamily, fontSize, lineHeight, paddingAppearance
cursorShapeblock, beam, underline; cursorBlink toggles blinking
letterSpacingExtra width added to every terminal cell, in points (0–8)
boldTextDraws ordinary terminal text at bold weight; what the agent marks bold goes heavier still
colorBackground, colorForeground, colorCursor, colorSelectionTheme colours replaced by hand, as a 0xRRGGBB number — JSON has no hex literal, so 0x121212 is written 1184274. Left out: the theme's own
scrollbackLines kept per terminal
askDirectoryAsk for a folder for new workspaces; askDirectoryForTabs does the same for tabs
resumeBarOffer earlier sessions when a terminal enters their folder
autoWorktreeA second session in a busy project gets its own worktree
agentTasksAgents may ask to start parallel tasks; you confirm each one
orchestrationUse orchestration: off hides every way to start one and the orchestration marks
orchestrationProfileModels a new orchestration starts with: balanced, quality or economy
orchestrationHelpersOffOther agents installed (codex, gemini, agy) a new orchestration leaves out
orchestrationConfirmPlanThe orchestrator shows its plan and waits for Start
orchestrationInTabNew orchestrations open as a tab of the workspace in front
agentGuideAgents started here get a short guide to Agentty's commands
stopServersOnCloseClosing a pane stops the servers started in it
confirmCloseAsk before closing something that was used
trashRetentionDaysDays a deleted workspace stays in the trash before it is deleted for good (7 by default)
agentBarPositiontop or bottom
workspaceSearchBarSearch box above the workspace list, over names and the conversations held in them (on by default)
sortFinishedToTopMove a workspace to the top when its agent finishes (off by default; off keeps the order you arranged yourself)
hudStatus bar items in order: model, context, usage, status, elapsed, links, spacer, ports, worktree, branch
browser.autoOpenServersOpen a dev server in the in-app browser once it answers
linkOpenerWhether ⌘-click opens links in-app or in your default browser
externalEditorauto, vsCode, cursor, system
harnessDetect, harnessPatterns, harnessSubmit, harnessAgentHarness detection and behavior
systemNotifications, notifyWhenFocused, notifyAnswerRequests, chatNotifyNotifications
chatNotify.slackBot, chatNotify.discordBotSend through a bot token and a channel instead of a webhook URL
chatNotify.slackChannel, chatNotify.discordChannelThe channel a bot writes to — Slack takes #general, general or a channel id; Discord takes a channel id
analyticsConsent to anonymous usage statistics. false, or DO_NOT_TRACK=1, sends nothing
menuBarMenu bar icon (macOS)
advisorStatusThe advisor's chip in a Claude tab's status bar (off by default)
hiddenAgentsAgent ids turned off in Settings → Agents (claude, codex, gemini, …): left out of the launcher, the start page and the palette
preventSleep, preventSleepAgentsKeep the machine awake always, or only while an agent works

Custom commands#

agentty.json in a project, or ~/.agentty/commands.json for all projects, adds entries to the command palette:

json
{
  "commands": [
    { "label": "Run tests", "command": "npm test" },
    { "label": "Deploy staging", "command": "./scripts/deploy.sh staging" }
  ]
}

pricing.json#

USD per million tokens, for models whose prices are not built in:

json
{
  "some-model": { "input": 1.25, "output": 10.0, "cacheRead": 0.125 }
}

cacheRead, cacheWrite and cacheWrite1h are optional and default to 10%, 125% and 200% of input.