Settings

Non-messaging settings for the PwrAgent desktop app. Messaging configuration lives under each provider page — see Messaging → Providers.

Everything below is reachable from Settings in the desktop app. The left-nav panes, in the order the app lists them:

There is no separate “Models” pane. Codex discovery, Codex auth profiles, and the ACP agents all live under AI Providers.

General

Desktop-wide defaults that don’t fit anywhere more specific:

• Appearance — theme (dark / light / system), density (mission-control / compact), and separate text-size controls for the sidebar and the transcript. The theme / density pair is the same one the onboarding wizard sets, changeable any time.
• Attention lens — whether a thread is promoted into the Attention lens when its turn ends.
• Quit confirmation — the app asks before quitting while threads are mid-turn, sends are queued or scheduled, or integrated terminals are running. Opt out here.
• Notifications — the opt-in for native attention notifications.
• Updates — the release channel (Latest / Prerelease) and train (Stable / Beta), plus check-for-updates and (on macOS) restart-to-update from inside the app. Defaults are Latest and Stable.
• Pasted images — patch budget (below).
• PDF analysis — whether PwrAgent may read a bounded preview of a PDF you attach locally before handing it to the agent.
• Messaging acknowledgment — the acknowledgement state behind the onboarding wizard’s messaging step.
• Developer mode — unlocks diagnostics: renderer CPU profiling capture (works in packaged builds, saves .cpuprofile artifacts), bounded heap snapshots, and copyable process IDs for chasing idle resource usage. The capture controls themselves live under Troubleshooting.

Pasted images — patch budget

When you paste a large image into the composer (a screenshot, a diagram, a photo from your clipboard), PwrAgent resizes it before forwarding to the model so it costs a predictable amount of context. Images are converted into model-token-friendly 32×32 pixel patches; this setting caps the patch count before per-model multipliers apply.

Pick the budget based on the typical fidelity you need. Most screenshots read fine at the default; bump it up when the model needs to read small text (UI labels, code snippets in screenshots, tiny CLI output). Drop it down if you regularly paste enormous images and want to keep the per-turn token cost low.

The same patch budget affects messaging-side image attachments similarly. See Driving an agent from a messenger → Image upload profile for the messaging-side knob.

Application discovery

PwrAgent shells out to command-line tools you’ve already installed. Settings → Applications covers the two it opens on your behalf:

git and gh moved. They’re on the Git pane now, alongside the pull-request settings that depend on them.

If the auto-discovery picks the wrong binary or doesn’t find one, override the path here. Paths are per-tool; an explicit value beats the auto-discovered one.

Agent-backend discovery is its own thing — see AI Providers below.

Plugins

Settings → Plugins inspects and repairs the MCP servers configured for this PwrAgent profile’s selected Codex profile. The pane shows which Codex profile it’s reading, that profile’s CODEX_HOME, and one row per configured server.

Per server: Relogin replaces expired OAuth credentials, and Remove deletes only that server’s configuration from the selected Codex profile. The pane-level Reload config button re-reads the installed MCP configuration and exposes it to loaded threads on their next turn — the fix for “I added a server and the agent can’t see it.”

If you change the selected Codex profile, restart PwrAgent before managing MCP servers for the new one; the pane says so rather than writing to the wrong profile.

Profiles

PwrAgent has two profile mechanisms — PwrAgent profiles (this panel) for desktop-app state and Codex auth profiles (under AI Providers → Codex) for isolating Codex CODEX_HOME directories. Both compose; see Desktop → Multiple profiles for the full conceptual model.

The Profiles panel lets you list, create, switch between, and delete PwrAgent profiles. Each row shows the on-disk profile dir, the Codex auth profile bound to it, and which one’s active / configured to launch by default.

Launches via --profile <name> (or PWRAGENT_PROFILE=<name>) still override the startup default — see Desktop → Launching a profile from the command line for the CLI launch flag.

Archived threads

Threads you archive disappear from the sidebar but stick around on disk — Settings → Archived Threads is where you go to restore them.

Threads are grouped by project folder. Within each project, archived rows sort by most-recently-archived first, capped at 20 threads per project to keep the list scannable. Each row carries the thread’s title, the branch it last lived on, the date it was archived, and a Restore button that puts the thread back in the active list (back to whichever workspace — Local or Worktree — it was in when it was archived).

The grouping is resilient to older corrupted managed-worktree rows — paths like ~/.codex/worktrees/<id>/PwrSnap collapse back under the PwrSnap project header instead of fragmenting one section per worktree id.

The list is scoped to the active PwrAgent profile. Switching profiles (Settings → Profiles, or the Profiles app menu) shows only that profile’s archived threads.

Thread Management

Settings → Thread Management moves Codex threads between Codex auth profiles — the escape hatch for “I started this in the wrong profile” or for splitting a shared profile into work / personal.

Pick the source Codex profile, select threads, and Copy or Move them into the target profile. Transfers are validated by replaying the thread’s history into the target before anything is removed from the source, and archived threads are safeguarded along the way. After a move, the thread shows up in the target profile’s list the next time you’re running under it.

Worktrees

PwrAgent stores managed worktrees outside of your repo so they don’t clutter your working checkout. The default storage location is ~/.pwragent/worktrees/.

You can change the location in Settings → Worktrees → Worktree storage location. Pick a path on the same filesystem as your repos — git worktree requires that, and putting the storage on a different volume will produce surprising errors at handoff.

When PwrAgent creates a worktree for a thread, it lands at <worktree-storage>/<hash>/<project-folder-name> where <hash> is a short timestamp-derived directory. You’ll see the full path on the thread’s status card.

AI Providers

Settings → AI Providers is the one screen for every coding agent PwrAgent can drive. Codex is the default and sits at the top; below it, one section each for the Agent Client Protocol (ACP) agents — Gemini CLI, Grok, Kimi Code, and Qwen Code. See Agent backends for what each one is, what it needs installed, and what differs between them.

The pane has three parts.

New thread defaults

Per-provider baselines — default model, reasoning effort, access mode, and service tier — applied to new threads and launchpads. They never override a choice already saved on an existing thread. There’s also a thread-migration tool here for moving existing threads onto a different model in bulk.

Codex

PwrAgent is a client of Codex App Server — it doesn’t ship its own copy. The desktop discovers Codex from any of:

• Codex Desktop (the official Codex desktop app, if you have it installed — found even if you renamed the ChatGPT.app bundle).
• Homebrew-installed Codex CLI (brew install --cask codex or equivalent — found even when the launching shell has a sparse PATH).
• Other Codex CLI install paths PwrAgent knows to check.

On launch, PwrAgent scans those sources, picks the newest working version it finds, and uses that as the Codex App Server backing your threads. The section shows the Codex path (blank means auto discovery), Available paths with the discovered candidates and their versions, the Auth profile picker, and a Connection test.

Keeping Codex up to date

Because PwrAgent uses the newest working install it finds, it inherits whatever updates you apply to the underlying Codex installation. That means:

• If you never run Codex Desktop (and don’t update via the CLI path), your PwrAgent stays pinned at whatever Codex App Server version was current when you last updated either source.
• The most reliable way to keep PwrAgent current is to run Codex Desktop periodically and let it self-update.
• If you do all your dev in PwrAgent and never open Codex Desktop, update the Codex CLI instead — brew upgrade --cask codex on Homebrew, or whatever your install path’s update mechanism is.

Either source on its own is fine. You don’t need to keep both current; PwrAgent picks whichever is newest at launch.

Authentication

PwrAgent does not ship its own Codex authentication flow. It piggybacks on whatever Codex auth state your underlying install has.

If you need to log out and back in, or your tokens have expired and PwrAgent shows you signed out:

1. Open Codex Desktop.
2. Sign in / re-authenticate there.
3. Restart PwrAgent (or wait for it to pick up the refreshed credentials).

There’s no equivalent flow in PwrAgent’s UI — by design, since duplicating the auth state would mean it could diverge from Codex Desktop’s truth.

The same principle applies to every ACP agent: you sign in to the CLI itself (/login in Kimi, /auth in Qwen, a browser round-trip for Gemini and Grok), and PwrAgent inherits it.

Testing the connection

The Connection test calls the discovered Codex App Server’s health endpoint and reports the version, the authenticated account (if any), and any error from the App Server itself. If it fails:

• Confirm Codex Desktop or the Codex CLI is actually installed at one of the paths PwrAgent scans.
• Confirm you’re authenticated — open Codex Desktop and check.
• Confirm the App Server binary is executable on your account (rare, but Gatekeeper / xattr -d com.apple.quarantine can come into play on freshly-downloaded binaries).

The ACP agents

ACP agents are third-party executables that speak a coding-agent protocol. They are not raw model providers and they do not replace the built-in Codex backend. PwrAgent does not install them — you install the CLI yourself (see Agent backends → What each one needs installed), sign in to it, then come back and click Refresh.

Each provider gets its own section, headed by its name and a status chip:

The controls that matter day-to-day:

• Enabled — “Show this agent in the model picker and launch threads with it.” A disabled provider is never launched, which matters because probing an agent can kick off its own browser sign-in flow. Disabled providers are also hidden from the Provider picker.
• Detected paths — every binary PwrAgent found: PATH matches, well-known install directories, and any manual path you added, each with a version chip. The one in use is marked; click Use to pin a different one.
• Manual path — point a provider at an install discovery can’t see. A manual path wins over everything else.
• Refresh re-runs discovery; Re-probe forces a fresh capability check instead of reusing the cache. Capability metadata is cached, so opening Settings doesn’t launch every agent just to re-ask what it supports.
• PwrAgent build (Grok only) — “Use managed PwrAgent Grok builds” downloads verified releases from pwrdrvr/grok-build and prefers the newest for new threads. Packaged macOS and Windows apps require platform signing; a manual path still wins.

Kimi has one extra wrinkle: if you ever installed the retired Python kimi-cli, PwrAgent flags the Provider collision, excludes those binaries from model discovery, and offers a copyable install command for the current Kimi Code.

The access-mode boundary is intentionally narrow: PwrAgent can mediate the ACP filesystem and terminal requests that pass through the client protocol, but it cannot sandbox what a third-party agent process does internally outside those requests. Install only agents whose source and behavior you trust.

Enabled providers show up in the Provider picker on the desktop launchpad and in messaging’s new-thread flow (see Driving an agent from a messenger → New Thread starter).

Operator-facing wrinkles worth knowing:

• Mode mapping is per-agent. Codex exposes the Default Access and Full Access modes you set on the Start Card. Most ACP agents ship their own runtime mode selector and PwrAgent defers to it entirely rather than stacking a second, mirrored dropdown on top. Grok has no selector of its own, so it gets PwrAgent’s pair — and PwrAgent drives Grok’s always-approve control for you when you flip it.
• Environments work across backends. .codex/environments setup hooks and command gating run for ACP threads the same as Codex threads — pick an environment on the launchpad and the setup hook fires before the first turn regardless of which agent you picked.
• What each agent can do varies. Steering a turn mid-flight and PwrAgent-managed /review are not universal. The per-provider table is at Agent backends → What differs.

Contributor-facing implementation details live in the app repository at docs/acp-registry-backends.md.

Usage & Pricing

Settings → Usage & Pricing controls how thread costs are shown and which usage patterns interrupt you. This is where thread pricing lives now — it graduated out of Experimental.

• Show thread pricing (on by default) — the Pricing tab in the thread context rail. Turn it off and the tab disappears.
• Price displays — a segmented control with two independent choices: List Price (each provider’s published rates) and Codex Credits (Codex’s token-based credit rate card). Pick one, both, or neither. Pricing is estimated and may differ from what you’re actually billed.
• Alerts — which costly or lossy patterns should interrupt you:
  • Active turn spend — off by default, threshold $5.
  • Thread spend — on by default, threshold $25.
  • Tool-output patterns — output-cap hits, repeated large outputs, and repeated queued checks. All three off by default; collection runs either way, the toggles only control alerting.

Tool-call tracking (the rail’s Tool calls tab and the incident explorer) is a separate Experimental toggle — see below.

Access Control

Settings → Access Control is role-based access control for messaging: which actors may invoke which capabilities against which destinations. The pane renders an Authorization graph over the capability catalog so you can see the permissions rather than infer them, and every decision is auditable.

It is fail-closed on invalid policy — a policy the app can’t parse denies rather than defaults open. Existing setups keep working unchanged until you define a policy; this is opt-in, not a migration that locks you out.

Git

Settings → Git owns the two CLI tools PwrAgent shells out to for repository work, plus everything pull-request-shaped:

• Git — the git binary. Repository inspection, worktree creation, branch metadata.
• GitHub CLI (gh) — GitHub-specific actions. Also the prerequisite for everything below.
• Background pull request status (on by default) — keeps PR status fresh across every open project instead of only the thread you have selected. The project you’re viewing refreshes about every minute; other open projects refresh less often; PRs with no activity for a day stop being checked until you open their thread again. Merged and closed PRs are skipped. Requires gh to be signed in.
• Pull request automation — Allow Auto-fix PR lets PwrAgent schedule one bounded repair turn for a linked pull request that fails CI or becomes conflicted. It’s gated behind background PR status being on. A second switch sets whether new threads and launchpads start with Auto-fix PR enabled (they do, by default); existing threads keep their saved choice. Dispatch runs on a budget so a thrashing CI job can’t spawn unbounded turns.

Federation

Settings → Federation connects this PwrAgent profile to other PwrAgent instances so they can see and drive each other’s work. Enrolled identities are exchanged over an encrypted control channel.

The pane walks setup end to end: Configuration (the federation mode), PwrAgent Encrypted Transport, Invites and Gateway Enrollment for enrolling a peer, Connection for runtime state, Federation Instances for the peers themselves, Recent Federation Activity for diagnostics, and per-transport setup for Tailscale Serve / Funnel and Cloudflare.

Federation is off until you configure it. Connected peers appear in the Profiles app menu, and federated threads open in remote viewer windows alongside your local ones.

Experimental

Features that may change shape or be removed without notice. The panel currently hosts:

• Tool Call Tracking — per-thread tool-invocation accounting: the rail’s Tool calls tab, the tool-output incident explorer, and the replay-cost warnings that go with them.
• Markdown Math Rendering — LaTeX math in the transcript and the composer.
• Lightweight Navigation Refresh — cheaper thread-list polling while the window is focused.
• PwrAgent-managed Code Review (off by default) — routes desktop and messaging /review requests through a PwrAgent-managed child turn instead of Codex’s native review lifecycle. Off “while failure handling and usage attribution are validated.” Existing threads aren’t migrated; turning it off restores native Codex review for the next review. This is also what makes /review work on Grok and Kimi.
• Codex Skill Questions — lets Codex skills pause an ordinary turn to ask you a structured question, when the installed Codex build supports it.

And a Soon to be discontinued group for features being phased out:

• Diff Condensation — xAI-judged elision of oversized diff payloads.
• Live Transcript Event Filtering — filters unrelated live events so background threads don’t churn the open transcript.

Features cycle through this panel before promotion — thread pricing graduated to its own Usage & Pricing pane this way.

Troubleshooting

Settings → Troubleshooting is the diagnostics drawer:

• Chrome DevTools — open DevTools against the app window.
• Codex protocol capture — record the App Server protocol traffic behind a thread, for filing a bug with something reproducible attached.
• CPU and heap monitoring — hot-CPU profiling with a configurable start delay and trigger mode, plus bounded heap snapshots. Works in packaged builds and writes .cpuprofile artifacts.

Most of this needs Developer mode on under General.

See also

• Agent backends — what Codex, Gemini, Grok, Kimi, and Qwen each need installed, and what differs between them.
• Desktop — the app’s overall feature set, workspaces (Local vs. Worktree), per-thread provider / model / fast / reasoning / permissions, multi-profile model.
• Messaging — messenger-specific Settings panels live under each provider setup page.