v0.14.0 - One home directory and managed worktrees

One home directory and managed worktrees

Paneflow 0.14.0 moves everything it keeps for you under one directory, ~/.paneflow (%USERPROFILE%\.paneflow on Windows), the way ~/.claude and ~/.codex do: paneflow.json, session.json, window-state.json, the managed worktrees/, the helper binaries under bin/, shell integration, and caches. The first launch copies the configuration, session, and window state from the previous locations and leaves the originals in place, so a downgrade still finds them.

Worktrees stop living beside your repository. Managed worktrees now go under ~/.paneflow/worktrees/<repo>-<hash>/, a new Settings > Worktrees page sets the root, the automatic removal, and a keep limit, and every removal first saves the checkout's uncommitted changes as a snapshot you can restore from that page. The New branch form gains a "Worktree" toggle, a "From" base picker, detached worktrees, and .worktreeinclude. Custom agent profiles run a built-in agent with extra environment variables and arguments, for example a second Claude Code account through CLAUDE_CONFIG_DIR, and the AI Agent settings page is rebuilt as Agents. Menus fade into place.

No configuration key is removed. The session format stays at v2, the terminal engine is still libghostty on every target, and the packaging contract, the IPC and MCP method names, and the paneflow CLI are unchanged. Two things move on disk, the home directory and the worktree root; both are in the upgrade notes.

Behavior changes

Every per-user file lives under ~/.paneflow

The layout is owned by the new paneflow-home crate:

File	Before (Linux / macOS / Windows)	Now
paneflow.json	~/.config/paneflow/ / ~/Library/Application Support/paneflow/ / %APPDATA%\paneflow\	~/.paneflow/paneflow.json
session.json	~/.cache/paneflow/ / ~/Library/Caches/paneflow/ / %LOCALAPPDATA%\paneflow\	~/.paneflow/session.json
window-state.json	~/.config/paneflow/ and platform twins	~/.paneflow/window-state.json
helper binaries, shell integration, caches	~/.local/share/paneflow/ and platform twins	~/.paneflow/bin/, shell/, cache/

On Windows the home is %USERPROFILE%\.paneflow. Debug builds use ~/.paneflow-dev. PANEFLOW_HOME moves the whole directory when set to an absolute path, for a second profile or a test machine:

PANEFLOW_HOME=/srv/paneflow-lab paneflow

The first launch of 0.14.0 copies paneflow.json, session.json, window-state.json, and the telemetry id from the old locations into the new home, skipping any file that already exists there, and leaves the originals untouched. Nothing is deleted. An agent's MCP config that still points at the old helper path is repaired by running the installer again:

paneflow mcp install

Settings > Plugins reports whether it is needed.

Managed worktrees move to ~/.paneflow/worktrees/

New worktrees are created under ~/.paneflow/worktrees/<repository>-<hash>/<branch>/ instead of <repo>.worktrees/ next to the checkout. Worktrees already sitting in the old sibling directory keep working where they are and stay listed, tracked, and removable. The root is worktrees.dir in paneflow.json, or the field at the top of Settings > Worktrees, and applies to worktrees created from then on:

{
  "worktrees": {
    "dir": "/home/me/.paneflow/worktrees",
    "auto_remove": true,
    "keep_limit": 15,
    "for_new_branches": true
  }
}

auto_remove (default true) removes a clean managed worktree when its workspace closes. keep_limit (default 15) trims the oldest unopened managed worktrees past that count. for_new_branches (default true) remembers the last position of the "Worktree" toggle in the New branch form. paneflow up and flows take the same root through their worktree field.

Nothing of Paneflow's sits inside a worktree any more

The owner marker that identified a Paneflow-created checkout was written as .paneflow-worktree at the checkout root, untracked, so git status never came back clean: "Remove worktree" refused every checkout as dirty, the automatic teardown on close never fired, and git worktree remove itself needed --force. The marker now lives in the worktree's own git dir (.git/worktrees/<name>/ in the main repository), invisible to git status and gone with the worktree. Existing markers are moved there and deleted from the checkout the first time the repository's worktrees are listed, so a 0.13.0 worktree needs no action.

Snapshots before removal

Removing a managed worktree, whether from the keep limit, a closing workspace, the tab menu, or Settings, first saves its uncommitted changes as a snapshot commit under refs/paneflow/snapshots/ in the main repository: tracked edits, new files, and the branch it was on. Settings > Worktrees lists the snapshots with Restore, which recreates the worktree with those changes uncommitted on the same branch, and Delete. A clean worktree leaves no snapshot, and the branch is never deleted. The refs are plain git refs, so they survive Paneflow and can be read with git for-each-ref refs/paneflow/snapshots/.

The AI Agent settings page is Agents; MCP Servers is Plugins

Settings > AI Agent is now Settings > Agents. The agent list leads with Claude Code, Codex, OpenCode, Pi, and Grok and folds the other eleven behind "Show 11 more"; each row states whether the CLI is installed, its binary, and its version (probed off-thread with --version), and the toggle stays inert for agents that are not on PATH. Full access, AI free access, and the injection fence moved here from General. Settings > MCP Servers is now Settings > Plugins; it does the same thing, installing or repairing the bundled paneflow-mcp bridge. No configuration key changed for either rename.

Menus fade into place

Every menu, select popup, context menu, and submenu opens with a 140 ms fade and a 4 px drop, the same easing as the sidebar slide, and the "New branch" form in the pane palette folds in and out the same way. reduce_motion in Settings > Appearance turns it off.

Added

Custom agent profiles

Settings > Agents > Profiles, or the agent_profiles list in paneflow.json, adds launcher entries that run one of the built-in agents with extra environment variables and arguments:

{
  "agent_profiles": [
    {
      "name": "Claude (work)",
      "agent": "claude",
      "env": { "CLAUDE_CONFIG_DIR": "/home/me/.claude-work" },
      "args": ["--model", "opus"]
    }
  ]
}

A profile shows up in the pane palette and the worktree launch pad next to the built-in agents and keeps the base agent's status tracking, hooks, and sessions. Environment variables are set on the agent process, not typed on the shell line, so the same profile works in bash, zsh, fish, and PowerShell. The page edits profiles in place with one key/value line per environment variable.

A "Worktree" toggle and a "From" base in the New branch form

The branch picker in the "New pane" palette starts with a "New branch…" item that unfolds a name field and a "From" select, defaulting to the branch the project is on; picking a preset then creates the branch and its worktree from that base and opens the pane there. The tab context menu offers the same entry, and the Launch Pad gains the same "From" select. paneflow up and flows take a matching from field next to worktree on a pane:

[[panes]]
agent = "claude"
worktree = "feat/login"
from = "main"

With the toggle off, the palette switches the workspace's own checkout to the branch instead of creating a worktree (git switch -c, or git switch for an existing branch, --detach with no name), and the pane opens at the repository root. Paneflow refuses the switch while an agent is working in that checkout. A branch that is already checked out is reused by every path, where the Launch Pad used to refuse it, and typing the name of an existing branch checks that branch out instead of failing.

Detached worktrees and "Create branch here…"

Leaving the branch name empty in the palette starts a worktree detached at the chosen base, named <base>-<sha7>, so an experiment that goes nowhere leaves no branch behind. The tab's context menu then offers "Create branch here…" to name it, keeping uncommitted changes.

.worktreeinclude

A file at the repository root lists the git-ignored files and directories to copy into every new worktree, one path per line. Without it Paneflow copies the top-level .env* files as before, plus AGENTS.override.md when present. The copy_env field of paneflow up and flows follows the same rule.

Fixed

• The shim honors CLAUDE_CONFIG_DIR when it checks for a persistent Claude Code hook, so a second config directory without one still receives the project-local hook. paneflow mcp install and its status and uninstall paths target the same directory, so CLAUDE_CONFIG_DIR=... paneflow mcp install hooks a second account.
• Worktrees created from the branch picker are tracked like those from the Launch Pad and paneflow up: a clean one is removed when its workspace closes, a dirty one is kept.
• "Remove worktree", the automatic teardown on close, and git worktree remove no longer see a Paneflow-created checkout as dirty (see "Nothing of Paneflow's sits inside a worktree any more").
• With the indent guide on, tab title and checkout meta rows in the sidebar sit under the guide instead of reserving a blank icon slot, and the ellipsis lands at the right edge.

Upgrade notes

• The home directory is ~/.paneflow (%USERPROFILE%\.paneflow on Windows, ~/.paneflow-dev for debug builds, PANEFLOW_HOME overrides it). The first launch copies paneflow.json, session.json, window-state.json, and the telemetry id from the 0.13.0 locations and leaves the originals in place. Run paneflow mcp install once if Settings > Plugins reports a stale helper path.
• New worktrees are created under ~/.paneflow/worktrees/; existing ones under <repo>.worktrees/ keep working and stay managed. worktrees.dir, worktrees.auto_remove (default true), worktrees.keep_limit (default 15), and worktrees.for_new_branches (default true) are added.
• agent_profiles is added, default empty. Each entry has name, agent, env, and args.
• paneflow up and flows take a new from field. copy_env now honors .worktreeinclude.
• The .paneflow-worktree marker is moved out of the checkout into the worktree's git dir the first time the repository's worktrees are listed. Snapshots are plain refs under refs/paneflow/snapshots/ in the main repository.
• The session schema stays at v2. The terminal engine, the packaging contract, the IPC and MCP method names, and the paneflow CLI are unchanged.
• Downgrading to 0.13.0 works. The old files are still in their previous locations, so a 0.13.0 build reads the state it left behind and ignores worktrees and agent_profiles; changes made to paneflow.json under 0.14.0 are not carried back.

Install and validation

Download the signed artifacts from this release or use the installation instructions.

Every primary artifact carries a .sha256 sidecar and a minisign .minisig; each AppImage also ships an .AppImage.zsync for delta updates. 35 assets in total.

Pipeline: run 34324445415.

Legs that passed:

• Build: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-pc-windows-msvc
• Release test gate on Linux x86_64: cargo fmt --check, cargo clippy --workspace --locked -- -D warnings, cargo test --workspace --locked
• Package smoke tests: Debian 12 and Ubuntu 22.04 (.deb postinst), Fedora 40 and openSUSE Tumbleweed (.rpm postinst), Arch Linux (tar.gz binary), Windows MSI install and relay
• Auto-update end to end on Linux x86_64

Full Changelog: v0.13.0...v0.14.0