Documentation

User-facing guides for Painted Wolf Code — the local-first AI coding desktop app. For contributor and engine docs, see the product repository on GitHub.

Every guide is on this page. Read straight through from Getting started, or use the rail to jump — it tracks where you are as you scroll. Building on top of the app — custom workflows, rules, packs, MCP — lives in the SDK.

New here? Getting started is the tour. Installation and the command-line tool cover setup beyond first launch. Projects & chats, Working in chat, Runs, workers & progress, Search & replace, Editing code, Verification & edit review, Keyboard shortcuts, and Git cover the everyday workspace.

For connections, recovery, and diagnostics, see Web research, MCP servers, Accessibility, and Backups, diagnostics, and reports.

These guides describe Painted Wolf Code v1.

Painted Wolf Code is a local-first AI coding app. You choose the model provider, attach the projects it may work in, and control its approvals. It collects no telemetry; see Security & privacy for what can leave your machine.

First run

1. Install the app.
2. Follow the first-launch setup: add an AI provider, choose your strongest tool-calling model as the default model, and optionally choose a smaller summarizer. The provider guide has provider-specific steps.
3. Open or clone a repository from Home, then type what you want done.

You can change models later under Settings → AI Providers. Readiness cards call out missing local tools before a run depends on them.

Everyday work

• Just type for direct changes. Use /plan when you want research and a Blueprint approved before implementation; type / to browse other workflows.
• Open cited files. Citations land on the exact line in Files, where Mod+I requests a focused edit and Review shows the finished diff.
• Check the evidence. Answers cite their sources, scanners supply findings, and Progress, Worklog, and Workers show longer runs without interrupting them.
• Change your mind. Edit or rewind one of your messages to restore the source files captured for that turn.

Press Mod+K to search chats, files, code, evidence, and app commands. Mod+F searches the view you are using now. See Keyboard shortcuts for the full map.

Arrange the workspace

Chat can sit beside a Context view or either can open in another window.

Open Layout at the bottom of the workspace to choose Single view or Split view, place the Context view on either side, or reset the split size. Drag the sidebar edge, split divider, pane divider, or list-column boundary to resize it. The main workspace remembers these choices. Each secondary window keeps its own layout.

When a window is too narrow for both split columns, Painted Wolf Code temporarily shows one view without changing your choice. The split returns when the window has enough room.

Right-click the Context list to hide, reorder, or open a view in another window. For isolated work, choose Git → Work on a branch…; see Git for landing that work back into the project.

Continue with

• Projects & chats for folders, drafts, and project trust.
• Command-line tool to open projects from a shell.
• Working in chat for queues, recovery, and attention.
• Editing code and Verification for making and reviewing changes.
• Plans & Blueprints and Runs & workers for larger work.
• Approvals for the safety controls.

Installers

The v1 desktop app runs on macOS 13 (Ventura) or later, Apple Silicon. Its release build is a Developer-ID-signed and notarized .dmg, with a Homebrew cask alongside. See Download for current availability.

The source is Apache-2.0. To build and run it yourself, follow the contributor setup in the product repository.

Command-line tool

The installed app already includes the pw binary inside the bundle. Choose Install pw command in Search or run or on Settings → Advanced, or add it to your PATH manually. Then use it to open projects from a terminal (pw .), set up shell completion, or browse local logs. See Command-line tool.

Updates

Use Settings → General → Updates to allow or stop update checks and to check now. Turning checks off is remembered after you quit; no check is made while it is off.

A direct DMG install can download, verify, install, and restart from that panel. If an install is interrupted, the app reports it after reopening without claiming the update succeeded. Homebrew installs stay managed by Homebrew: the app reports an available version and asks you to run brew upgrade --cask painted-wolf-code.

Next: Providers & API keys to connect a model, then Configuration.

The app bundle includes a command-line tool named pw. It is the same binary the desktop app already ships — not a second installer. With it on your PATH, pw . opens the current folder the way code . opens VS Code.

Put it on PATH

Recommended: in the app, open Search or run (Mod+K) and choose Install pw command. That symlinks pw and pw-logs into /usr/local/bin, which is already on the default macOS PATH. macOS may ask for an administrator password.

The Install pw command action on Settings → Advanced does the same.

Manual: the binary lives beside the app:

Painted Wolf Code.app/Contents/MacOS/pw

Add that Contents/MacOS/ directory to your PATH, or symlink pw and pw-logs into /usr/local/bin yourself.

Check that it resolves:

which pw
pw .
pw ls

The app should be installed and able to run. Commands that talk to the desktop app need it available on this machine; authoring verbs such as workflow validate work against files on disk without an open window.

Everyday commands

Opening projects

Pass a folder or a project name. A folder (or any path with a separator, or one that starts with ~) opens the project that already owns it — including when you are in a subdirectory. A bare name looks up projects by the label the app shows.

Repeating pw . in the same repo always returns to the same project. Use --new only when you intentionally want a second project on that folder. If several projects share a name, the command lists them instead of guessing. Passing a single file asks you to pass its folder instead.

Opening never silently creates or rewires a project. When the folder is new, the desktop app shows a proposal so you can confirm.

Shell completion

# zsh — add to ~/.zshrc
eval "$(pw completion zsh)"

# bash — add to ~/.bashrc
eval "$(pw completion bash)"

Completion reads a name cache refreshed by pw ls. Run ls after you rename or create projects so the cache stays current.

Authoring and diagnostics

The same binary validates packs, workflows, rules, and prompt overlays you keep under .paintedwolf/. The verbs, flags, and exit codes are in the SDK Reference. The end-to-end author loop is in the SDK tutorial.

Next: Projects & chats · Installation · SDK

A project holds folders, chats, Blueprints, findings, cost history, and configuration. A chat is one conversation inside it.

Starting a project

You can start typing on Home before choosing a folder. The first message creates a draft in an app-managed private workspace. Choose Save as a project or Save to folder… to save it through a restart-safe transition into an empty folder; the private draft remains intact until the saved project is durably committed.

For existing code, choose Open folder. The confirmation summarizes the repository and any guidance or capabilities it contributes. Guidance such as AGENTS.md is readable immediately; MCP, extensions, and project settings wait for your review.

If the repository or its capability settings change while that review is open, the app applies nothing from the stale decision and refreshes the review. Revoking previously approved capability remains available.

Choose Clone a repo… when the code is not on this device. Enter its Git URL and an empty destination folder. The app clones and opens it, then asks you to review repository capabilities normally.

A folder already registered with a project opens that project. Open as new project creates a separate project deliberately.

Folders and repositories

A project may hold several folders. One is primary for unqualified paths and new Blueprints. Short labels such as @api/ or @web/ let you name another root in chat.

Attach, detach, rename, or choose the primary folder from Project configuration. Detaching the last folder keeps the project, its chats, and saved approvals, but file and command tools stay unavailable until you attach another one.

Painted Wolf Code refuses the filesystem root, your whole home folder, credential stores such as .ssh, and broad folders that contain them. Choose the source folder itself. The same check runs whenever a tool uses an attached folder. If a folder is refused, the action stops and the project is left unchanged; attach a narrower source folder in Project configuration.

Several roots may belong to one Git repository, and one project may contain several repositories. Files and Git keep those scopes distinct.

Managing projects

Home separates Recents, Drafts, Starred, and All. Select several rows to star, unstar, or delete them together. View all opens the complete list.

Deleting a project removes its chats, source history, findings, and local project records. It does not delete the folders or repositories on disk.

Managing chats

Use the chat menu to:

• Rename or Pin it in the working list.
• Archive it while preserving history and search results; sending a message unarchives it.
• Delete it permanently after stopping the run and unbinding any worktree.
• Export it as Markdown or JSON.

The sidebar is a working set, not the full inventory. All chats searches and sorts every chat in the project, including archived ones.

Open a project from the terminal

From a shell, pw . reaches the project for the current folder, and pw ls lists projects on this device. Put the bundled binary on your PATH first — setup, completion, logs, and the full command list are in Command-line tool.

Next: Working in chat · Git · Configuration

Web research runs from your device. Painted Wolf Code can search through built-in public sources, providers you add, and a local index filled by earlier research.

Open Settings → Web research. The master Allow web research switch removes outbound search, page, and research-worker tools when it is off; the agent cannot turn them back on for itself.

Choose providers

The Providers tab starts with keyless Direct search. Its bundled public sources remain usable without credentials; a source may also expose an optional key when that service offers higher limits or additional access. Choose Add provider for a supported search service or a SearXNG endpoint you operate.

Open a provider to add its API key or endpoint, save its settings, and run Test search. The status distinguishes a key stored by the app from a supported environment credential; environment values are detected but never copied into the credential store or displayed. Optional keys stay optional, and providers that share a credential slot reuse that one stored value. Stored keys are shown only as present, never read back into the interface. Removing a provider also removes credentials owned only by that provider.

Guess domains tries likely publisher sites when ordinary results are thin and turns on index warming.

Local index

Searches fill a local index so repeat topics remain fast when a provider is slow or unavailable. Under Local index you can:

• Turn Warming on or off. It expands the index from session titles and web activity while the app is in use.
• See storage, health, search timing, and recent background activity.
• Clear every indexed page and its warming history. Later searches rebuild it from scratch.

The index is rebuildable local data, not chat history. Clearing it does not remove sessions, settings, or credentials.

Privacy and approvals

The site or search provider receives the request from your network and can see your IP address. Direct page fetches and search providers follow their own terms. Outbound credential screening runs before queries and fetched URLs leave the app, and your approval posture decides when a new destination asks.

See Security & privacy for the full data path and Approvals for destination and credential controls.

Painted Wolf Code uses a provider you bring. Cloud requests go directly to the account you pay for; local backends need no API key. Provider credentials stay on your device and outside project folders.

Connect a provider

Open Settings → AI Providers, choose Add AI provider, and select a provider. Most cloud providers ask for an API key. Bedrock accepts either a Bedrock API key or your normal AWS credential chain; Vertex uses Google Application Default Credentials; local backends such as Ollama use their local endpoint. oMLX is macOS-only.

Cloud services often show a new key only once. Copy it immediately, keep it like a password, and replace it if you think it was exposed.

Choose a provider below for its current setup steps:

After saving, use Test connection. A backend reports configuration, authentication, model discovery, and assignment readiness separately, so a reachable service can still explain that its credential is missing or that no compatible model is available. Credentials marked stored came from the app’s credential store; cloud credentials means the backend selected its documented ambient AWS or Google chain.

If a provider accepts a request but returns a broken or incomplete stream, the app reports that response as failed. It does not silently send the prompt a second time, which avoids duplicate work and charges.

Choose your models

Only the default model is required. Use your strongest conversation model with reliable tool calling; every other role inherits it until you choose an override.

Set device defaults under Settings → AI Providers. Use Project configuration → AI Providers for one project, including its worker pool. Chats in that project use those models unless the chat itself has an override. You can mix backends—for example, a cloud coordinator with a local summarizer.

A local backend loads a model into memory the first time you use it, so a first request can take minutes on a large model while later ones are quick. The app allows for that wait instead of giving up on the model.

The model list is refreshed from the provider and its public catalog metadata. The picker hides embedding and image-only models from conversation roles and filters out models that are known not to support the selected role. Unknown capability data is not treated as proof of support. Settings → General → Display → Show all models reveals conversation-capable models hidden by preference and context filters; it does not restore a model known to lack chat or required tool calling.

Vision matters for interpreting screenshots and images. Without it, the agent can still use page text, console output, structure, and measured geometry, and the app tells you when an attached image cannot be seen.

Troubleshooting

To file a report, save diagnostics from Backups, diagnostics, and reports. Filing one does not entitle you to a reply or a fix.

Search covers local conversations, attached project trees, and the evidence behind agent answers. It also runs app commands from the same front door.

Search or run

Press Mod+K to open Search or run. Type to match app actions, recent chats, file names, code, messages, and evidence. Tab moves between result types. Choose Show all results for the full Search stage.

Mod+F finds text only in the active view. Find everywhere or Mod+Shift+F carries that query into Search.

Full search

The Search stage adds facets, a result timeline, a detail inspector, and query filters. Results can span every open project or stay within the project where the search began.

Use field filters such as kind:code, project:, path:, lang:, before:, after:, trust:, and verified:. Match case, whole word, regex, and include or exclude paths are available beside the query.

Select a result to open its source: messages return to the matching conversation, evidence opens its receipt, and file or code hits open at the matching line.

Exports are available as JSONL or CSV. SARIF export is available when the query is limited to scan findings (kind:scan).

Replace across files

Press Mod+Shift+H or choose Replace in project. Search shows a preview capped at 500 files and 5,000 hunks. Review individual hunks or clear a whole context class before applying.

Each file applies only if it still matches the revision used for the preview. Changed files are skipped and reported. A completed batch can be reverted from its receipt; files changed after the batch are skipped rather than overwritten.

Project-wide rename from F2 uses the same preview and apply path with case-sensitive whole-word matching.

Next: Editing code · Projects & chats

Open Files to browse the project, edit source, and review changes beside the conversation. Citations open at the referenced line; Mod+K finds a file by name; F12 or Mod-click goes to a definition.

Files, folders, and tabs

A single click opens a preview tab that the next browsed file can reuse. Editing, saving, or pinning turns it into a regular tab. Pinned tabs stay at the front.

The Files tree can create, rename, duplicate, drag, and trash files or folders. Renaming a file or folder keeps its open tabs connected to the new path. Deletion confirms first and uses the operating-system Trash. Open folders and scroll position are remembered. .git stays hidden; .paintedwolf/ is listed so you can open blueprints and verify.yaml from Files.

Right-click a path to reveal it in your file manager, copy its path, or add it to chat. To use another editor for citations, set Settings → General → Editor → Open citations in.

Ask from the editor

Select code and press Mod+I to request a focused edit. With no selection, the app uses the enclosing symbol or nearby lines. Unsaved work must be saved or discarded first.

Right-click a selection for common requests:

These focused turns cannot use the shell, network, or MCP. Press Mod+L instead when you want to attach the selection to a chat without sending it.

When the agent edits an open file

Agent changes play into the open buffer. If you have unsaved work, the app offers a three-way merge rather than overwriting it. If an edit reaches the line where your caret is active, you can let it write, hold it, or cancel that write.

The gutter marks scanner findings and the turn that produced changed lines. Hover a change mark for the turn that wrote it, open that turn in chat, or reject the change. F8 and Shift+F8 walk the caret down and up the findings in the file.

Review changes

Switch from Files to Review for changed files and diffs. Choose Working changes, This turn, Everything in this chat, a saved pin, or Since last commit when Git is available. Git affects only the commit comparison; the other scopes work without it.

The same scope marks changed lines in open source tabs. Marks appear only when the tab matches the revision being reviewed, so they never point at stale lines.

Review keeps your changes, AI changes, and changes from outside the app in one file list. Use All contributors for the complete history or Needs review for AI work that still needs your attention. Mark reviewed clears only the revision you saw, so a newer edit stays pending.

Choose Save current state to pin a comparison point you want to return to later. Pins belong to the project and remain available across chats. Step through the run follows one file-changing action at a time and keeps its diff and tool call together.

Explain in Review opens a briefing pinned to the file’s current revision. Its structure and key declarations appear immediately, followed by a bounded explanation with source-line evidence. Reopening the card restores the briefing, and another file change marks it stale. For review before selected writes reach disk, see Verification & edit review.

Layout and file behavior

Files can sit beside chat or open in another window. Every window sees the same document and unsaved work. One window edits it at a time. Closing the file hands editing back, so the next window picks it up on its own; while a window still has it open, choose Edit here to take over.

Unsaved work is recovered after an app restart. Tabs, cursors, scroll positions, and folds are restored separately. If the file changed on disk, the draft stays available and the editor asks you to reload or merge instead of overwriting the newer file.

The editor handles text files up to 4 MiB and preserves common Unicode encodings, byte-order marks, and line endings. Larger files and binaries are metadata-only.

Editor actions share the app shortcut registry: find them in Mod+K or rebind them under Settings → General → Keyboard. See Keyboard shortcuts for the main bindings.

Next: Search & replace · Verification & edit review

A normal message starts direct work; a slash command starts a structured workflow with visible stages and controls.

Sending and steering

Type a request and press Enter to send. Shift+Enter adds a line. The composer keeps an unsent draft for each chat, including staged attachments, so switching chats or windows does not lose it.

With an empty composer, ↑ and ↓ move through recent prompts. Editing one creates a new turn; it does not change the old message.

If you send while the chat is busy, the message joins that chat’s queue. Open the queue above the composer to manage what happens next:

• Reorder or edit messages, and link adjacent messages that should arrive as one turn.
• Use Send next to move one to the front, or Pause to hold the queue.
• Interrupt & send stops the current turn and sends the selected message immediately.

Queued prompts normally run in order after the current turn becomes idle. Removing one affects only that waiting message.

Questions and approvals

When the agent needs information, its question appears above the composer. Answer there and the paused turn continues with your response.

An approval card also sits above the composer, but it authorizes a specific action. Typing before you answer sends direction with the denial or approval; it does not grant broader access. See Approvals.

Stop, retry, and re-send

Stop cancels work still in flight and keeps every message, tool result, and file change already committed. If the turn had not begun work, your prompt returns to the composer.

A failed turn shows Retry, which sends the last prompt again as a new turn. Re-send on a previous message does the same without removing anything from the conversation.

Edit and rewind

Hover or focus a message you sent:

Recovery snapshots include project-authored .paintedwolf/ files. Files too large to capture remain unchanged. Rewind is available while the chat is idle.

Leaving work running

Commands that need to stay alive run as background jobs. Their cards show the process handle, recent output, and stop control; the agent can read more output without filling the conversation with it.

When the window is unfocused, native notifications can tell you that a turn finished, needs input, or needs approval. Configure them under Settings → General → Notifications.

Attention follows the chat across projects. Needs you appears in Mod+K and on Home; chat lists mark running, failed, and waiting work. Notifications return to the chat that raised them.

Hold Ctrl+Tab to cycle through recently visited chats across projects; release to open one. Ctrl+Shift+Tab moves backward and Escape cancels.

Next: Runs, workers & progress · Attachments & artifacts · Plans & Blueprints

The composer accepts uploaded files and references to things already inside the project. Both arrive as visible chips before you send, so the turn contains exactly what you staged.

Adding something to chat

Use the paperclip, paste, or drag onto the chat. Add to chat is also available from Files, Search results, selected source, folders, and existing visual artifacts.

Executables, unknown binaries, archives, active SVG images, and folders outside the project are rejected rather than silently dropped. The app extracts document text but does not render pages or run OCR, so an image-only PDF has no readable text.

Limits

A turn accepts eight uploaded files, including four images, plus 64 project references. Individual files, combined content, and document extraction are bounded; the attachment chip reports anything shortened or rejected.

What leaves your machine

Uploaded images and extracted attachment text become part of the model request when the turn needs them. They go to the AI provider configured for that chat, under that provider’s terms. Project path and folder references stay local until the agent reads the referenced content; any content placed into model context then follows the same provider path.

Outbound credential screening runs before model requests, searches, fetches, and MCP calls. See Security & privacy and Approvals.

Artifacts

Screenshots, mockups, attached images, and other visual outputs are durable project artifacts. A capture on a tool card and a featured image on an answer each render in full. A later mention of the same image in the same place points back instead of repeating it.

Open Context → Artifacts to browse by source or chat and return to the message that created an item. Artifacts belong to the project, not to one chat, so deleting a chat leaves its screenshots in the gallery.

An artifact stays stored as long as something still points at it — a message that shows it, a prompt you attached it to, a tool result, or the project cover. Unreferenced items may be pruned when the project’s image cache fills.

Deleting an artifact

Right-click a tile in the gallery and choose Delete artifact. The confirmation names what currently refers to it, so you can see the cost before you decide.

Deleting removes the image for good. Places that already showed it keep their reference and read as deleted rather than going blank, because an image the agent has already seen cannot be unshown.

Visual browser checks

For a website or local web app, the agent can open the browser surface, capture a page, and return screenshots or a short filmstrip as evidence. It can work from static project files or a running app on a loopback address. Ask it to check a route, viewport, interaction, or exact visual question rather than simply saying “look at the site.”

The browser can inspect structure, console output, screenshots, and geometry. Without model vision it can still verify elements, interactions, and measurements; appearance and composition may still need your review.

Open a returned capture as an artifact, or use the read-only live preview while the development server is running. The preview does not turn the page into an editor; request the source change in chat or make it in Files, then capture again to verify it.

Next: Working in chat · Editing code

Most device-wide setup lives in Settings. Choices for only the open project live in Project configuration.

Device and project settings

Project configuration covers AI Providers, approvals, MCP, scanners, edit review, and test commands. Device settings remain the defaults. Project cost controls are under Context → Cost; shared team behavior belongs in committed project customization.

What you can configure

Appearance and themes

Settings → General → Display sets whether the app matches your system appearance or stays light or dark, and which theme each one uses. A range of light and dark themes ships with the app; extension packs can add more, and installing a pack that contains one adds it to the list.

Your appearance choice belongs to this device. The themes are there whether or not a project is open, and your choice follows you between projects — a project can offer a theme, but opening one never changes how the app looks. If a theme’s pack is removed or disabled, the app falls back to the one it ships with and tells you which theme is missing, keeping your choice for when the pack comes back.

What a project may change

A repository can contribute guidance, such as AGENTS.md and project skills, or capability, such as MCP, extensions, and settings overlays. Guidance does not grant access. Capability waits for your project-specific review, and a later repository change may require review again.

A project’s approval rules can only make things stricter. The one thing it can relax is a detection pack, which it may switch off for its own tree — that returns the tree to the normal boundary rather than below it, since detections only ever add a check. Extension unit kinds follow the same floor: shared and additive kinds may land from a trusted project pack; device-only kinds do not — see Unit kind properties. Disable any repository-contributed surface device-wide under Settings → Advanced → Project settings from repos.

Host resources

Settings → Host resources lists detected command-line tools and local services. Choose Refresh after changing one, then leave its normal policy, Ask before use, or Block it. This can add a check or denial; it never bypasses containment.

Shared project behavior

Put reusable project instructions in a SKILL.md folder under .paintedwolf/skills/ or .agents/skills/. Commit it when the team should share it. Skills are guidance, not scripts or access grants.

For custom workflows, rules, and extension packs, use the SDK.

MCP servers let the agent use tools supplied by another application or service. Add and manage them under Settings → MCP servers.

Add a server

1. Choose Add server and enter the connection details supplied by the server.
2. Add environment variables, headers, or a bearer token when the server requires them. A remote server may instead open a browser for sign-in.
3. Turn the server on. Painted Wolf Code connects to it and reads its tool list.
4. Choose Test connection to check the connection, authentication, and tool discovery before relying on it in a chat.

Inspect discovered tools in the server details and choose Resync after they change. A changed tool definition asks again before use.

Turning a server on registers its tools. Workflows that accept all tools receive them; restricted profiles stay restricted. There is no separate attach step.

Local and remote servers

Local servers can receive environment variables. Remote servers can use headers, a bearer token, or OAuth. Secrets stay in device configuration and are hidden when settings are read back.

A local server starts inside the active project’s process boundary and receives the attached roots through MCP. Its filesystem and mediated network access last for the server session. A remote server runs outside this device boundary, so its own operator controls its process and storage.

Project MCP

A repository may include .paintedwolf/mcp.yaml, but project entries are limited to unauthenticated loopback servers and wait for your review. They cannot start a program, send credentials, or expand a restricted tool profile.

A project entry is visible for review and Test connection, but it does not register callable agent tools. Only servers enabled in device settings do that.

Use Project configuration → MCP servers to review what the current project contributes. If you do not want repositories to contribute MCP settings at all, turn off Project MCP under Settings → Advanced → Project settings from repos.

When a tool asks

MCP calls follow the same approval posture as other tools. Strict mode asks on MCP use until you allow it. Credential screening also checks arguments before they leave your machine, and a changed tool definition always asks again.

For pack authors who need typed facts from MCP results, see MCP bindings in the SDK.

Painted Wolf Code uses one shortcut system across the app, the native application menu, the command list, and the built-in editor. Press ? when you are not typing—or Mod+/ anywhere—to open the complete shortcut list for your device.

In this guide, Mod means Command on macOS and Ctrl on Windows and Linux. The app displays the right keys for the computer you are using.

Everyday shortcuts

Use Mod+K when you do not remember a key; app commands appear beside search results with their current bindings. Recent-chat cycling crosses projects: hold Ctrl, tap Tab, and release on the chat you want.

Chat and lists

• Enter sends a message; Shift+Enter adds a line.
• With an empty composer, ↑ and ↓ recall recent prompts.
• Arrow keys move through menus and results; Enter chooses and Escape closes the topmost layer.
• On a resize separator, arrow keys adjust the size. The split divider also accepts Shift+arrow for a larger step, Home or End for its limits, and Enter to reset.
• In Search, Tab and Shift+Tab move between modes. Alt+C, Alt+W, and Alt+R toggle case, whole-word, and regular-expression matching.

Files and editing

Commands are context-aware. More editing and navigation commands are available through Mod+K and the complete shortcut list.

Moving around with the leader key

Press Mod+;, release it, then press one letter:

Type the second key without a modifier. A hint appears if you pause; Escape cancels.

Changing shortcuts

Open Settings → General → Keyboard. Filter by command, click a shortcut, then press the replacement. Changes apply immediately and persist on this device.

You can change the leader key as one unit. The app refuses operating-system and accessibility shortcuts and ambiguous conflicts. Use Reset on one command or Reset all for the defaults.

Next: Search & replace · Editing code · Configuration

Settings → Extensions installs and updates extension packs for this device. Context → Extensions controls which packs are active for the current project and shows its checked-in extension configuration.

Use project settings for one repository and device settings for behavior that follows you everywhere. Commit project behavior when the team should share it.

Which pack unit kinds a project may add, disable, or replace is fixed by kind — shared, additive, or device-only. See Unit kind properties before assuming a repository can override a machine guardrail.

Use what ships with the app

Type / in a chat to browse the built-in workflows, or start one by name. The v1 workflow catalog is:

Extensions add workflows, agents, and rules. Install them in Settings → Extensions, then activate and configure them for a project in Context → Extensions. Keep the project configuration in the repository when it should be shared with your team.

Install and maintain extensions

Settings → Extensions manages extensions for this device:

• Install from Git… clones a pack; Check for updates and Update refresh it.
• Install from folder… links an authoring folder in place. After editing it, choose Reload from disk; removing the extension never deletes that source folder.
• Enable or disable individual packs and community suites. The built-in suite stays enabled.
• Open diagnostics to see validation errors, missing dependencies, unit conflicts, and the effective result before relying on the pack.

Install and update resolve the pack and its dependencies as one set. The app shows dependency changes and publishes the complete set together; a validation or write failure leaves the previous installed resolution active.

Installation and project activation are separate: Settings controls what is available, while Context → Extensions controls the current project. Checked-in capability waits for your review.

Extension changes are available to open chats on their next turn. No restart is needed.

Reusable project know-how

For a procedure, checklist, or team convention, add a folder containing SKILL.md under .paintedwolf/skills/ or .agents/skills/ in your project. Skills use the open Agent Skills format, so the same instructions can travel between compatible tools.

The agent sees the available skill names and reads one when it is useful. A skill is guidance, not a script: it does not run on its own or grant any additional access. Commit project skills when you want the whole team to use them. Keep the description to one line of what and when; put the procedure in the body. Pack skill authoring is in the SDK.

Go further

The SDK explains how to author custom workflows, rules, and extension packs. Keep secrets in Settings, never in files you commit to a project.

Longer work has more than a transcript. The rail beside chat shows the run’s Progress, Workflows, Git, and Workers so you can see what is happening without asking for a status summary.

Follow progress

Open Progress for the current phase, steps, and context-window use.

Open Worklog for completed steps, findings, worker coordination, and approvals waiting on delegated work.

Control a structured workflow

The Workflows tab shows the active workflow and its current stage. Depending on the workflow, you can:

• Pause, Resume, or Advance between stages.
• Open Review when a plan or result needs your decision.
• Jump or change workflows when allowed, Exit to the ambient build workflow, or download the report.

These controls operate on the run state. A message in chat can give direction, but it does not replace an approval or workflow button.

Starting another workflow replaces the current structured run while keeping its transcript and any Blueprint. Controls apply only to the run state shown on screen; if it changes first, the app refreshes and asks you to act on the current state.

Inspect workers

Workers lists delegated tasks. Select one for its assignment, budget, activity, transcript, and evidence, or cancel it without stopping the rest of the run.

A worker can pause to ask the coordinator for a decision. The coordinator usually answers without interrupting you; when it needs your input, the chat becomes Needs you and shows the question above the composer. The question survives an app restart, and answering it resumes the same worker.

A worker that reaches an approval boundary pauses. Its Waiting for your approval state appears in Workers and the Worklog, and the chat keeps an approval card above the composer. Resolve it there just as you would an approval from the main agent.

If you leave the chat

Runs keep their state when you move elsewhere. Chat lists mark work as Running, Failed, or Needs you; Mod+K and Home surface work waiting across projects.

When the app is unfocused, a notification can take you back to the chat that finished or needs input. Configure those under Settings → General → Notifications.

Next: Plans & Blueprints · Working in chat · Approvals

Use normal chat for direct work. Use /plan when you want the agent to research first, write down the intended change, and wait for your approval before building it.

Running /plan

The workflow moves through a visible sequence:

Approval is a button in the review workspace or review bar. A sentence in chat does not approve the Blueprint.

Reviewing a Blueprint

The review workspace previews or edits the Markdown. Request changes sends direction through chat, Run critique adds another review pass, and Approve starts the build.

A Blueprint opens with a short YAML block above the headings, holding its status and title and a research_depth of none, light, or thorough. The workflow reads that value to decide whether the research stage has anything left to do, so keep the block when you edit — without it the Blueprint reads as incomplete and the agent is asked to write it back.

The review bar stays above the composer while approval is waiting, so closing the workspace does not hide the decision.

The Blueprints library

Context → Blueprints lists the project’s durable plan files under .paintedwolf/blueprints/. Edit, rename, rerun, or commit one when it should travel with the repository.

Starting another catalog workflow replaces the active structured run as one action and keeps its transcript and Blueprint. If the run changes while you are acting on it, the app refreshes instead of applying the older action. /exit leaves the current structured workflow and returns the chat to the ambient build workflow.

Use the Workflows tab to pause, resume, advance, review, exit, or download a report. Progress, Worklog, and Workers show what happens inside a larger run; see Runs, workers & progress.

Other structured workflows

Type / to browse every workflow available in the current project. v1 includes focused recipes for reconnaissance, bug bashes, security surveys, and other bounded work. Extensions can add more without changing the chat engine.

See Customizing behavior for the installed catalog and SDK for authoring your own.

Next: Runs, workers & progress · Verification & edit review · Working in chat

Painted Wolf Code has three different review moments. Use the project test command to check that a change works, Edit review to pause selected writes before they land, and Files → Review to inspect the completed diff.

Set the project test command

Open Project configuration → Tests. The app may detect a likely command from the repository’s own documentation, but it never applies that suggestion silently. Choose Use detected command, or enter the command your project actually uses, then save it.

The command is normally stored in .paintedwolf/verify.yaml. Commit it when the team should share the same gate; Clear removes it.

Keep the command representative and non-interactive: a focused test suite or normal CI entry point works better than a server that never exits.

After an agent edits your files, this command has to pass before the work is treated as finished. If it fails — even when you asked for something that will not pass yet — the change is held back until the command succeeds or you discard it.

Once you set it, that is the command the assistant runs when it verifies. It cannot swap in a different one and present the result as your project check. The assistant can still run narrower checks while it works; those are reported as checks, not as a verdict on the project.

When a check could not run

A check that never reached a verdict is reported as unverifiable rather than as a failure. The usual cause is the sandbox stopping the command — a build tool trying to write to a cache outside the project, for example.

The distinction matters because the two call for different responses. A failure means the code has a problem. Unverifiable means nothing was learned about the code either way, and running a different command will not help; either approve the access it needs when prompted, or run the check yourself. A run that ends this way is recorded as unverified rather than as passing.

Pause selected edits before disk

Open Project configuration → Edit review and add a path glob such as infra/**. An optional tool name narrows the rule further.

Matching edits pause before disk; everything else continues normally. Use this where seeing the patch first matters more than uninterrupted automation.

Edit review is not the same as an approval posture and does not make the matched area writable. Containment and approvals still apply underneath it.

Review the finished change

Open Files → Review to inspect all current changes after they have landed. Filter the review to a file or folder when a large change is easier to understand in pieces, then step through each changed file. From there you can open the source at the exact line or hand the selection back to chat.

For an isolated piece of work, bind the chat to its own worktree from Git → Work on a branch… before the run starts. See Git for landing and unbinding it.

Next: Editing code · Git · Runs, workers & progress

The Git panel uses the same repository and hardened Git engine as the agent. It reads and writes one repository at a time, so status, commits, and branch actions always have an explicit scope.

Choosing a repository

A project may contain several roots in one repository or roots from several repositories. The scope selector follows the chat’s active root by default. Pin a repository when you want the panel to stay there.

All repositories shows branch, changed-file count, and ahead/behind state for every repository in the project. It is an overview only; choose one repository before a write action. A folder outside Git offers Initialize repository.

Reviewing and committing

The changed-files list opens project files in Files and shows paths elsewhere in the same repository without granting the project access to them.

Review the changes, write a message, and choose Commit. Commit stages every change in the selected repository and creates one commit. The message assistant can draft from the diff; you remain the author of the commit action. A commit never spans repositories.

Commits made here are not signed — the app holds no signing keys, and a commit it made will not claim a signature it cannot produce. Sign from your own terminal when a repository requires it.

Use Stash to set all current changes aside and Discard to remove all current changes. Discard confirms before removing local work. The Review view in Files remains the deeper place for line-by-line change review.

Branches and remotes

Open the branch picker to switch branches or create one. Pull fast-forwards from the configured upstream. Choosing Push in the Git panel immediately publishes the current branch as a human action. Pushes attempted by the agent use the normal approval policy.

Repository-owned configuration cannot replace the app’s Git binary, install hooks into these operations, or supply external diff and pager programs. Credentials remain in the normal SSH agent, credential helper, or provider flow outside the agent sandbox.

Giving one chat its own checkout

Choose Work on a branch… to bind the chat to a new branch in an app-owned worktree outside the project folder. That chat’s agent, commands, Files view, and Git panel all use the worktree; other chats keep using the project checkout.

Commit the work in the worktree before landing it. Land merges those commits into the branch the chat started from when the project checkout is clean and still on that branch. A conflict aborts the merge and leaves the project checkout unchanged.

Unbind removes the extra checkout and keeps its branch and commits. A missing worktree never falls back silently to the project folder; unbind it before the chat continues. A bound chat must be unbound before that chat can be deleted.

Next: Editing code · Approvals

Most file edits, commands, and Git work happen without interruption. Painted Wolf Code asks when an action would be hard to undo, cross a boundary, or send something sensitive away from your machine.

Approval cards appear above the composer. Each names the action, who requested it, and what it affects.

Answering a card

• Enter takes the recommended action; Escape says no.
• Type before answering to send direction such as “use the staging bucket instead.” Direction is not authorization, and the replacement action goes through the same checks.
• Open the caret beside the main action when you want to remember a choice for this task, project, device, or period of time. Available scopes depend on the action.

Remembered choices appear under Settings → Approvals → Saved approvals and can be revoked there. The conversation also shows Revoke while its grant remains active. A changed action, destination, credential, or tool definition may ask again.

How often it asks

Choose a posture under Settings → Approvals, or a stricter one under Project configuration → Approvals:

A project may require a stricter posture, never a looser one. Turning device approval checks off under Settings → Advanced → Approvals does not remove containment, hard denials, project requirements, or the rule that the agent cannot change its own settings.

Some actions always ask, including disabling an audit control, granting lasting access, irreversible cloud destruction, credential-shaped command arguments, and direct disk writes.

Credentials on their way out

Before model requests, searches, page fetches, and MCP calls leave your machine, the app screens them for credential-shaped values. Nothing has been sent when the card appears. You can:

• Send redacted — replace the matched value in the outbound request.
• Send unchanged — allow this exact value for this request or a displayed repeat scope.
• No — send nothing. The chat continues: the agent is told you declined, along with any direction you attached, and takes the turn again.

Command and terminal arguments cannot be rewritten safely, so their cards omit redaction. Redaction never changes the source file. This check runs at every posture.

Strict adds a broader safeguard: after a chat reads a credential file such as .env, it asks before that chat sends anything out, even when no recognizable credential appears in the outgoing text.

Folders outside your project

Strict asks whenever an action leaves the attached roots. Balanced asks for sensitive locations such as personal document folders, startup configuration, key material, and credential stores. Light does not add folder prompts.

Approving a path grants only the access printed on the card, for the displayed scope. One file does not grant its parent folder, and read access does not grant writes. The path remains outside your project and the grant stays visible in Saved approvals.

Network and local services

Ordinary command traffic is mediated per action. The app reviews the requested host before connecting, and the command can reach only its private mediation endpoints. Hosting a local server, reaching a service on this machine, or using unmediated networking each receives its own card when policy requires one.

Local service sockets are a separate permission. Approval covers the exact socket shown on the card, not its containing folder or everything the service can do. Ending the process closes its command-scoped network endpoints; revoking a remembered local-service or direct-network grant applies to the next process start.

Beyond your own machine

Local containment cannot protect a cloud account or external service from a consequential action. Detection packs inspect command lines and structured tool calls, including MCP tools, before they run. A detection can add a prompt, never remove one, and a missed detection is not a safety guarantee.

Manage them under Settings → Approvals → Detections: inspect rules and recent asks, enable or disable packs, and import a custom device pack. A repository may turn a pack you already have on or off for that tree if you granted Project settings from repos; it cannot add a rule of its own.

Balanced asks when the agent chooses a new destination — including a project’s Git host the first time it is used. After a chat reads a web page or MCP result, cards label it External content. The label is context; the checks above still apply to what the chat tries to do next.

Authoring and the approval ledger live in the product repository: detection packs and authorization. See Security & privacy for the data path and Working in chat for undoing a completed turn.

You pay providers directly. Painted Wolf Code estimates spend from published prices and can stop a session at a ceiling you choose.

Seeing what you’re spending

A cost chip under the project name opens the session breakdown. Context → Cost shows project totals, role and session comparisons, price sources, and CSV export.

When a model has no published price, token counts remain visible but the total is marked partial or unavailable rather than understated.

Stopping a turn mid-answer usually means the provider never says what it used. Those tokens are counted here anyway, from what was sent and received, and the figure says it is approximate. A call to a local backend that goes unreported is listed on its own: its tokens are missing from the counts, but nothing was charged for them, so the amount stays whole.

Tracking is on by default. Settings → Cost manages price sources or turns tracking off; recorded estimates remain.

Stopping a runaway session

Separate from watching cost, there is one brake: a per-session spend ceiling. It’s off until you set one.

Set a device default under Settings → Advanced → Budgets, or a project limit under Context → Cost. A project ceiling applies separately to each chat.

When a session reaches the ceiling:

• New prompts and workers do not start.
• A running turn finishes what is in flight, summarizes what remains, and goes idle — that soft landing is on by default under Settings → Advanced → Budgets. Turn it off there if you want the session to stop without that extra round.
• Files and results are kept. Raise or remove the ceiling, then prompt again to continue.

The warning before the stop

Before the stop—80% by default—the cost chip warns you and offers to raise the ceiling. The agent is told to finish its current work and name follow-ups. You can adjust the warning threshold.

Where it doesn’t apply

If usage cannot be priced, the ceiling is not enforced and the app says so.

Keeping the bill down

• Mix models by role. The coordinator needs your strongest tool-calling model; the summarizer and worker pool usually don’t. Set them separately in Providers & API keys.
• Run a local backend for the roles that don’t need a frontier model — an Ollama summarizer costs nothing per token.
• Reach for a structured workflow on big changes. Approving a plan before the build costs less than three rounds of rework.

Related: Providers & API keys · Approvals

Painted Wolf Code runs scanners against the project and gives their findings to the agent as evidence.

Three jobs, covered on the first scan

Scanning is organized around three questions. The built-in scanner for each job runs when you open a project without additional setup.

Exactly one tool holds each job; choosing another replaces the current scanner for that job.

Findings appear in Context → Security with their severity, rule, and location, and the agent gets them as evidence it can act on. Results stay on your machine.

Bring the scanners you already trust

Install a supported scanner, then choose it for a job under Settings → Security scanners. The app detects it, runs it, and reads its report. The install check shows missing or unhealthy tools.

These are the tools you can install and select:

Some names appear both here and in the defaults table above, which is deliberate. The built-in code and secret scanners are OpenGrep and Gitleaks running inside the app against our rules; the rows here are your copies of those tools, running your rules and your configuration. Picking one trades our curated rule set for full control of it.

Your own rules

Scanners run without network access, so a static-analysis tool has to read its rules from disk. Registry rulesets — Semgrep’s p/default and similar — cannot be fetched and will not work. Put your rules in the directory the scanner’s row names, before you select it:

• OpenGrep reads .opengrep/ in the project
• Semgrep reads .semgrep/ in the project

A scanner that cannot find its rules is treated as a failed scan, not a clean one.

A tool that isn’t listed

Settings → Security scanners → Add → Custom scanner… takes any CLI that prints a SARIF report to stdout. Give it an id, the exact command to run — {{project_dir}} stands in for the project path — and a display name. It then competes for a job like any other scanner. Commands run without a shell, so pipes and redirection are not available, and the program itself must live outside the project it scans.

When scans run

Built-in scanners run when a project opens. The selected static-analysis scanner also runs after worker changes land, including when you choose an external replacement. By default it scans only the files those workers landed, not unrelated working-tree edits. If several workers contribute to one run, the latest scan covers their accumulated landed paths. Choose Whole project under Settings → Security scanners → After changes land when you want every landing to scan the full tree.

On-demand and workflow scans cover the whole project unless you request a narrower scope. Scanner processes can read the project they scan but cannot use the network.

You can turn scanning off completely with the Use Security scanners switch, which also hides Context → Security.

Fixing what they find

Findings appear in Context → Security and beside affected editor lines. Fix this finding asks for a targeted, reviewable edit; rerun the scan to verify it.

Secrets, in the repository and on the way out

The secrets scanner finds credentials in the repository. Separate outbound screening checks model, search, fetch, and MCP requests; scanner settings do not disable it. See Approvals.

For the wider story — what leaves your machine, and what scanning does and doesn’t prove — see Security & privacy.

Painted Wolf Code uses the same workspace and transcript with assistive technology; there is no separate accessibility mode.

Text size on macOS

The app follows System Settings → Accessibility → Display → Text size and updates while it is open. Painted Wolf Code does not add a second text-size slider, so the system setting remains the single source of truth.

Linux source builds do not currently bridge the operating system’s text-size setting. Display scaling and the operating system’s own magnification tools still apply. There is no Windows build in v1.

VoiceOver and spoken content

VoiceOver and macOS Spoken Content read the real chat transcript, controls, status changes, and dialogs. New run activity is announced without moving your focus away from what you are doing. Standard dialog focus is contained until you close or answer the dialog.

Motion and keyboard use

When your system requests reduced motion, the app removes non-essential animation. It keeps state changes and progress understandable without depending on motion alone.

Every app command is available from Mod+K, and ? opens the complete shortcut list. You can rebind shortcuts under Settings → General → Keyboard; the app refuses operating-system and accessibility combinations that would interfere with assistive controls.

Resize separators expose their current value to assistive technology and work with arrow keys. Split layout, pane sizes, and list columns do not require dragging.

See Keyboard shortcuts for navigation, editing, and the leader-key map.

Painted Wolf Code collects no telemetry: no analytics, crash reporting, usage beacons, account, or device identifier.

What can leave your machine

Dependency advisories come from the public OSV database; your dependency list stays local. Any provider or website you contact can see your IP address and handles the request under its own terms.

For control over search providers and the local index, see Web research. For what an attachment sends, see Attachments & artifacts.

What stays local

Chats, settings, project records, keys, and local indexes stay on your device. Keys are stored outside project folders and never pass through a Painted Wolf service.

On macOS, commands run in an operating-system sandbox. Writes are limited to attached project roots, temporary or cache locations, and paths you explicitly approve. The app refuses broad roots such as your home folder and credential stores, and its own settings and provider keys stay unavailable to agent commands. Linux source builds have no kernel sandbox: containment there is the approval layer only. There is no Windows build in v1.

When the sandbox stops a command, the result says so. If the refusal names what was blocked, the app can offer the approval that would allow it. If it does not, there is nothing to approve, but the failure is still attributed to the sandbox rather than left looking like a broken build.

On macOS, each command receives its own network boundary. Ordinary connections pass through private, command-scoped endpoints so the app can review the destination before connecting. Hosting a local server, reaching a service on this machine, or using unmediated networking each goes through a separate approval.

The agent cannot change the settings that control its access. Settings → Approvals decides when crossing a boundary asks. See Approvals for the cards and postures.

Containment reduces risk; it does not prove a command is safe or protect an external account from every mistake. The threat model, outbound inventory, and sandbox contract live in the product repository: security and privacy.

Your data

• Export a conversation as Markdown or JSON from its ··· menu.
• Back up or restore under Settings → Advanced → Data.
• Clear rebuildable caches without removing chats or credentials.
• Save a scrubbed diagnostic bundle or file a report; nothing uploads automatically.

See Backups, diagnostics, and reports for recovery, diagnostics, and how to file a report. There is no support contract. Report vulnerabilities through the project’s private security instructions.

Painted Wolf Code keeps its working data on your device. Its recovery tools save files for you to control; they do not upload diagnostics or backups to Painted Wolf.

There is no support contract. Reports are welcome; a reply, a fix, and a timeline are not guaranteed.

Back up and restore

Open Settings → Advanced → Data and choose Back up now to save the durable installation as a zip. Backups exclude API keys and tokens. Restoring on the same device leaves its separate credential store in place; a fresh installation needs those secrets entered again.

Restore… replaces chats, projects, and durable settings. The app first saves a recovery copy and shows its path; restart to finish, and keep that copy until you check the result.

The app validates the complete archive before staging a restore, and only one restore can wait for restart. At startup it checks the staged data again and records progress while replacing files. An interrupted restore resumes on the next launch; data that no longer matches keeps the app in recovery instead of opening the installation partway through the restore.

An invalid archive is rejected without replacing anything. If the backup came from a newer app version, update the app first and try again.

Clear rebuildable data

Use Settings → Advanced → Cache to clear named scratch-data buckets. This does not remove chats, credentials, projects, or durable settings.

The web research index also has its own Clear button under Settings → Web research → Local index.

Diagnose a problem

Settings → Advanced → Diagnostics offers System information, logging controls, and a scrubbed diagnostics bundle (Save diagnostics bundle). The bundle stays local until you share it. From a shell, pw logs opens the same local capture browser — see Command-line tool.

To file a report, open Settings → General → About → Report a bug…. The guided dialog explains the bundle, saves it where you choose, then can reveal the file and open the public GitHub Issues page. Nothing is sent automatically. Filing a report does not entitle you to a reply or a fix.

How to route a report, and what not to expect: the product repository’s REPORTING.md.

After an update

Home may show a What’s New card after an update. Read more opens the full notes. Choose Got it to dismiss the card for that version; simply closing the reader leaves it available. A brand-new installation does not show old release notes as an update.

Settings → General → About → Third-party software opens the license notices bundled with the installed release.

For a security vulnerability, use the private security reporting instructions rather than a public issue.