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 layout is roughly:

• General — desktop-wide defaults (image-paste budget, etc.).
• Applications — terminal, editor, git, gh CLI.
• Profiles — PwrAgent profile management; see Desktop → Multiple profiles.
• Archived threads — restore threads you archived; grouped by project.
• Worktrees — where worktrees get stored.
• Messaging — per-provider config; see Messaging → Setting up providers.
• Models — Codex App Server discovery, version, Codex auth profile selection.
• Agents — allowlisted ACP coding-agent registry entries and install/provenance status.
• Experimental — opt-in features that are still in flux.

General

Desktop-wide defaults that don’t fit anywhere more specific. Only one section lives here today (image patch budget); more land here as the desktop grows surfaces that don’t belong in any other panel.

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 Using Codex via Messaging → Image upload profile for the messaging-side knob.

Application discovery

PwrAgent shells out to several command-line tools you’ve already installed. On launch it discovers:

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

Codex App Server discovery is its own beast — see Models / Codex App Server below.

Profiles

PwrAgent has two profile mechanisms — PwrAgent profiles (this panel) for desktop-app state and Codex auth profiles (under Models / Codex App Server) 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.

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.

Models / Codex App Server

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

• Codex Desktop (the official Codex desktop app, if you have it installed).
• Homebrew-installed Codex CLI (brew install codex or equivalent).
• 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 version currently in use is shown in Settings → Models — same panel where you’d verify which models are available and which one PwrAgent thinks you’re logged into.

Keeping the App Server 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, consider updating the Codex CLI instead — brew upgrade 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.

Testing the connection

The Test button in Settings → Models 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 Test 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).

Agents / ACP registry

PwrAgent can install allowlisted Agent Client Protocol (ACP) coding agents as local backends. ACP agents are third-party executables that speak a coding-agent protocol; they are not raw model providers and they do not replace PwrAgent’s built-in Codex or Grok backends.

Settings → Agents shows the allowlisted registry entries PwrAgent is prepared to expose. Each row includes version, license, distribution source, install state, auth/setup state, verification state, and repository/website provenance when the registry provides it.

Install is a two-step flow:

1. Click Review install.
2. Read the source/trust disclosure and click Install.

PwrAgent supports npx, uvx, and platform binary distributions. Package-manager entries are stored as command/argument descriptors and launched without shell interpolation. Binary entries are installed from the allowlisted archive source; checksum/signature metadata is verified when present. If an allowlisted binary lacks integrity metadata, Settings calls that out before install.

The access-mode boundary is intentionally narrow: PwrAgent can mediate 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.

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

Currently allowlisted agents

Once installed, both show up in the Backend picker on the desktop launchpad and in messaging’s new-thread flow (see Using Codex via Messaging → New Thread starter) alongside Codex and Grok.

A couple of operator-facing wrinkles worth knowing:

• Mode mapping is per-agent. Codex / Grok expose Default and Full Access modes you set on the Start Card. ACP agents map their own runtime modes through to that picker — Gemini surfaces its native modes; Kimi reports only Default from session/new, and PwrAgent transparently issues a suppressed control prompt under the hood when you flip the Permissions cycle to Full Access, so the picker behaves the same as on Codex / Grok.
• Environments work across backends. .codex/environments setup hooks and command gating run for Kimi and Gemini 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.

Experimental

Opt-in features that are still in flux. Today the panel hosts:

• Diff condensation — when on, focused-diff requests fire an xAI judgment call to decide which hunks to elide. Useful when diff payloads bloat past comfortable model-context sizes; off by default.

Expect this section to grow as features cycle through the experimental phase before promotion.

See also

• Desktop — the app’s overall feature set, workspaces (Local vs. Worktree), per-thread model / fast / reasoning / permissions, multi-profile model.
• Messaging — messenger-specific Settings panels live under each provider setup page.