devpit

Settings

Every section and what it controls.

Last updated

Settings takes over the window. Open it with ⌘, (Ctrl on Linux and Windows) or the gear in the sidebar; the back button or Escape leaves. Search settings at the top filters the sections, and it matches what a section is about, the titles of its rows and its name: "tailscale" finds Remote, "island" finds Notifications and "tokens" finds Usage. A search scrolls to the row it matched.

Every row is a card, and only its switch switches: clicking a row's words does not turn it on. The longer half of a row — what it does and what it does not — folds under How it works.

Application

  • General — opens on Local by default, which is a statement rather than a switch: "Projects, conversations and settings are kept on this computer." Then:
    • On this desktop: Open at login, Keep devpit in the tray when the window closes, Shortcut (keys that bring devpit forward from anywhere, none until you choose), Display, and Open in ("The apps offered when you open a project or a worktree somewhere else").
    • Updates and privacy: Automatic updates, on by default; the Updates row, with the version you have and Check now; Error reports, off unless you turn it on. See Staying up to date and Where your data lives.
  • Notifications — Island, on by default, with how it is drawn on this desktop and, where it would be an ordinary window on Wayland, Show the island anyway. Pause: quiet for a while or until you resume. Reminders, on by default. Focus mode: unfinished, and off until you turn it on. See The island, Notifications, Reminders and Focus mode.
  • Remote — Remote, off until you turn it on, with how to get in and each paired device; Allow remote MCP (read-only); and Calendar. See Remote.
  • Appearance — theme: System, Light or Dark. Terminal contrast: None, Readable or Strong; until you pick one it follows the ground. The terminal keeps its dark ground in every theme. Under Text: Text size and Code size (Small, Default, Large, Larger), for the conversation and for code and every diff; Contrast, Standard or More, which draws secondary text and borders closer to the main text in any theme; and LaTeX maths, off by default. Under Diffs: Diff layout, Whitespace in diffs, Diff colours and Files in a diff. See Files and changes.
  • Keyboard — every key the window listens for, each one changeable. See Keyboard shortcuts.
  • Maintenance — how hard devpit works in the background and what it keeps. Every default is what devpit did before:
    • Power saver, off by default. On, devpit looks at its panes, devpit.app and sync four times less often while nobody is at the window or the machine runs on battery.
    • Keep logs and run artifacts: Never by default, or 7, 14, 30 or 90 days. Older logs, and older Devflow runs and reviews, go ten minutes after start and every six hours, or at once with Delete now, which says how many went and what that freed. Of each card, the newest run stays.
    • Labs: Project agent and Canvas, both on by default. See The project agent and Excalidraw.
  • Diagnostics — what devpit itself is running and costing: its processes, with CPU and memory, sorted by memory, with the totals; the checks devpit diagnostics prints, each failing one with its fix; and the newest entries of devpit's error log, with where it is. It reads when the pane opens and on Look again, never on a timer.
  • About — the version and platform, and Open for the privacy policy, the licence and the open-source notices.

Workspace

  • Projects — every project, with Add project, and Open, Rename, Reveal, Open in and Remove on each row. See Projects.
  • Worktrees — where card checkouts are made, which kinds of checkout devpit counts, the Branch name pattern and Branch name for this project, Cleanup of merged ones, and each card's checkout with Remove. See Worktrees.
  • Storage — where each project's workspace folder lives, ~/.devpit/projects/<name>-<suffix>, and what is in it. See Where your data lives.
  • Archive — the open project's archived conversations, each with Restore. See Conversations.

AI capabilities

  • Providers — Default agent: "What a new terminal opens. A plain shell is an answer too." Agent status hooks: working, waiting and done on the island, in the sidebar and on a card. Installed, with a count of what was detected on this machine, each row opening its profile editor. Not on this machine, listing the rest with a link to each, and a Refresh button for after you install one. See Providers. Check sign-ins and MCP servers: every minute, or every 5, 15 or 30 minutes, 5 by default. Default model: the model a new chat starts with, for all projects or one (see For one project). A Claude Code profile, opened, has its models, an advisor model and a subagent model; see Profiles.
  • Sessions — Open the next card on its own, off by default: when a card is finished or lands in done, the next card of its epic that waited on it opens in a session of its own. Hand off a full session. Chat activity, the default for the chat's Activity menu. Ask before stopping a terminal (below). Send with, Enter or ⌘Enter, and While a turn runs, Queue or Steer; see Chat. Permission mode: the mode a new chat starts in, for all projects or one.
  • Skills — the skills your agent CLI has installed, read from its own configuration. See Skills and MCP.
  • Channels — where devpit reaches you away from the window, such as Telegram, and what goes there.
  • Voice — Voice messages: how a recording becomes words — This machine, A service or Off. Check again looks for a whisper you just installed, without reopening Settings. See Chat.
  • Devflow — Devflow's stages, reviewers and setup for each project.
  • Orchestrator — Guardrails: which of an orchestrator's actions wait for you, set for each orchestrator. See Guardrails.
  • Assistant — how often the Assistant mode heartbeat looks, every 5 to 60 minutes, and which of its checks are on.
  • Decisions — off unless you set it up: what judges evidence against a rubric, with its key.

Account

  • Account — who is signed in, and Sign out. See Account.
  • Accounts — your Claude Code accounts and their limits.
  • Usage — what your sessions cost, and your plan limits. See Usage and plan limits.

For one project

Three rows have Applying settings for, which chooses All projects or one project: Default model in Providers, Permission mode in Sessions and Branch name for this project in Worktrees. All projects sets this machine's value; a project's value is for that project only. Each row says where the value in use comes from, and a change writes only that one setting.

A repository can carry shared defaults in .devpit/settings.json, read from the project's root:

{
  "model": "sonnet",
  "permissionMode": "plan",
  "worktree": { "branchPattern": "feat/{number}-{slug}" }
}

A value set for the project wins over the repository's file, which wins over all projects. New chats start with the project's model and permission mode, though a model or mode picked in a conversation still wins and an orchestrator keeps its own. Cards' worktrees take the project's branch name. With nothing set, everything starts as it always did.

The file can ask for Supervised ("manual") or Plan ("plan"), never a mode that asks less: that one is yours to choose. A file that is not valid, is over 64 KB, is not a plain file or leads outside the project is left out whole, and the row says why.

Ask before stopping a terminal

The question devpit asks before it closes a terminal that is still running something has a Don't ask again of its own. Ticking it turns this switch off; turning the switch back on in Settings → Sessions brings the question back. See The terminal.