2026-10-23 10:09:18 -07:00
|
|
|
# The Plan2Code desktop app
|
|
|
|
|
|
|
|
|
|
One window for working with an AI agent. The app opens the Plan2Code dashboard as its main surface,
|
2026-10-25 12:50:11 -07:00
|
|
|
runs your agent (Claude Code, Devin or Codex) in a terminal panel it owns, and has a **New Session**
|
2026-10-23 10:09:18 -07:00
|
|
|
button that replaces the agent with a fresh one on a brief the app builds from its own record of the
|
2026-10-25 12:48:14 -07:00
|
|
|
session. The fresh agent gets a console session of its own, so the Session meter starts over with it.
|
|
|
|
|
It is an addition: `/plan2code` typed inside an agent works exactly as before, with or
|
2026-10-23 10:09:18 -07:00
|
|
|
without the app.
|
|
|
|
|
|
|
|
|
|
## Get it
|
|
|
|
|
|
|
|
|
|
The installer offers the app after the skills and the `plan2code` command:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Answer **Y** to "Also install the Plan2Code desktop app?" (it is the default). It downloads the file
|
|
|
|
|
for your system from the GitHub release, checks it against the release's checksum list and puts it in
|
|
|
|
|
`~/.plan2code/app/`. If a checksum does not match, the file is thrown away and nothing is installed.
|
|
|
|
|
If the download fails, the skills and the `plan2code` command are still installed; the installer says
|
|
|
|
|
so, and you can run the installer again later.
|
|
|
|
|
|
|
|
|
|
Releases carry one file per system:
|
|
|
|
|
|
|
|
|
|
| System | File |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| Windows (64-bit Intel or AMD) | `plan2code-app-<version>-windows-x64.exe` |
|
|
|
|
|
| macOS (Apple silicon) | `plan2code-app-<version>-macos-arm64` |
|
|
|
|
|
| macOS (Intel) | `plan2code-app-<version>-macos-x64` |
|
|
|
|
|
| Linux (64-bit Intel or AMD) | `plan2code-app-<version>-linux-x64` |
|
|
|
|
|
|
|
|
|
|
On any other system the installer says there is no build for it and carries on without the app.
|
|
|
|
|
|
2026-10-25 12:51:25 -07:00
|
|
|
Each of those is a plain executable, not an OS-level installer package (no `.msi`, no NSIS `.exe`
|
|
|
|
|
setup, no `.dmg` with a drag-to-Applications step): the installer above places it directly, already
|
|
|
|
|
verified. `plan2code-app`'s own `npm run build` can produce `.msi`/NSIS/`.dmg`/`.deb` bundles locally
|
|
|
|
|
(Tauri's bundler is on), but the release workflow does not build or publish them; nothing today
|
|
|
|
|
downloads or runs one.
|
|
|
|
|
|
2026-10-23 10:09:18 -07:00
|
|
|
You also need Node.js 18 or newer (the app checks at start and says what to install) and:
|
|
|
|
|
|
|
|
|
|
- **Windows:** the WebView2 runtime, which comes with Windows 11 and current Windows 10.
|
|
|
|
|
- **Linux:** WebKitGTK 4.1 (`libwebkit2gtk-4.1`) and a desktop session.
|
|
|
|
|
|
|
|
|
|
## Start it
|
|
|
|
|
|
|
|
|
|
Run `plan2code` in your project, as always. When the app is installed and a window can open,
|
|
|
|
|
`plan2code` asks which agent and model (as before) and then opens the app on that folder instead of
|
|
|
|
|
running the agent in your terminal. The desktop shortcut the installer can create runs the same
|
|
|
|
|
command, so it opens the app too.
|
|
|
|
|
|
|
|
|
|
Three things keep today's terminal flow:
|
|
|
|
|
|
|
|
|
|
- **`plan2code --classic`** runs the agent in your terminal even when the app is installed.
|
|
|
|
|
- **No display.** On Linux without a display (over SSH, in a container) `plan2code` falls back to the
|
|
|
|
|
terminal flow by itself.
|
|
|
|
|
- **An SSH or service session on macOS or Windows.** The same fallback applies there, since neither
|
|
|
|
|
has a desktop to open a window on either.
|
|
|
|
|
- **Not a project folder.** If the folder is not a git repository and has no `AGENTS.md` or `specs/`,
|
|
|
|
|
`plan2code` asks you to confirm before opening the app on it.
|
|
|
|
|
|
|
|
|
|
## What's in the window
|
|
|
|
|
|
|
|
|
|
The first time the app opens on a folder, a checklist confirms Node, the agent CLI, the project
|
|
|
|
|
folder and the skills version before anything else shows; a later launch skips straight past it.
|
|
|
|
|
|
|
|
|
|
A **launch card** then asks which agent (Claude, Devin or Codex), model and effort (Claude and Codex
|
2026-10-25 15:33:39 -07:00
|
|
|
only) to start on. Permission checks off is its own tick, on by default (see below; New Session
|
2026-10-23 10:09:18 -07:00
|
|
|
keeps whatever you picked); a CLI the app cannot find is named, with how to install it, instead of
|
|
|
|
|
just being greyed out. The card is skipped when the launcher already passed an agent to start.
|
|
|
|
|
|
2026-10-25 12:50:11 -07:00
|
|
|
The window's own title (and so its taskbar entry) reads **Plan2Code - <folder name>** once a
|
|
|
|
|
project is open, so two or more windows on different projects read apart without opening each one
|
|
|
|
|
to check.
|
|
|
|
|
|
|
|
|
|
A slim top bar reads, left to right: the project folder's name, a menu holding its full path and
|
|
|
|
|
**Change project**; **New Session**, whenever an agent exists; the agent's own menu, with a dot for its
|
|
|
|
|
state, an amber **checks off** badge while permission checks are off, and **Change agent** once it has
|
|
|
|
|
ended; a short line (why the agent ended, a New Session's brief, or what went wrong); and, at the right
|
|
|
|
|
end, the one next step for the console or the skills when there is one (**Reconnect the console**,
|
|
|
|
|
**Update skills**), with "+N more" if anything else is waiting behind it. The console itself, opening inside the
|
|
|
|
|
window (not only the dashboard — every console page, including Ask, Workspace, Notebook, Help,
|
|
|
|
|
Preferences and Git), already shows which page is open and its own **Session** meter (how much plan2code
|
|
|
|
|
work this session has done) in its own bar, so the app's bar does not repeat either. That Session meter
|
|
|
|
|
is the one place for "is this session getting long" under the app, too: the app does not keep a second,
|
|
|
|
|
separate context-window meter of its own, so there is only ever one gauge to read and only one place its
|
|
|
|
|
threshold is tuned. The terminal panel has its own toolbar: dock it to the bottom or the right, collapse
|
|
|
|
|
it to a thin strip, or maximize it; its size is remembered. An "agent may need you" badge appears on a
|
|
|
|
|
collapsed or small panel once the agent has sat quiet for a while. **Change project** (in the project
|
|
|
|
|
menu) asks first if an agent is running, then stops it and the console before opening the new folder.
|
|
|
|
|
|
|
|
|
|
If the console itself ever needs reconnecting (it stopped, or the skills were just updated), every path
|
|
|
|
|
to that offers the same **Reconnect the console** button — never "Restart the console" in one place and
|
|
|
|
|
"Start it again" in another for the same action — and only one shows at a time.
|
|
|
|
|
|
|
|
|
|
The console also knows when it is running inside the app (the agent it talks to carries that signal):
|
|
|
|
|
its session meter, the "Before you close this" guide on a finished step, and the dashboard's red-session
|
|
|
|
|
banner all point at the app's own **New Session** button instead of a command to paste into a new
|
|
|
|
|
conversation, since New Session already does that in one click; and the console's own "update available"
|
|
|
|
|
banner never shows, since the app's **Update skills** button (below) already covers it with no shell
|
|
|
|
|
involved. A slash command still offered to continue a step (such as `/plan2code-4-finalize`) stays
|
|
|
|
|
exactly as it would in a terminal: paste it into the app's own terminal panel, which runs the real
|
|
|
|
|
agent CLI.
|
2026-10-23 10:09:18 -07:00
|
|
|
|
|
|
|
|
## Keep it up to date
|
|
|
|
|
|
|
|
|
|
`plan2code update` brings the skills, the `plan2code` command and the app up together. If the app
|
|
|
|
|
and the installed skills ever differ in version, the app's top bar says so and offers **Update
|
|
|
|
|
skills**, which runs that same update when you press it. It never updates on its own.
|
|
|
|
|
|
|
|
|
|
## The first release is unsigned
|
|
|
|
|
|
|
|
|
|
The app is not code-signed yet, so your system may stop it the first time it starts. It is the same
|
|
|
|
|
file the installer verified against the release's checksum list.
|
|
|
|
|
|
|
|
|
|
**macOS.** If macOS says the app "cannot be opened because Apple cannot check it for malicious
|
|
|
|
|
software": open **System Settings**, then **Privacy & Security**, scroll to the message about
|
|
|
|
|
`plan2code-app`, and press **Open Anyway**. Start `plan2code` again and confirm.
|
|
|
|
|
|
|
|
|
|
**Windows.** If SmartScreen shows "Windows protected your PC": press **More info**, then **Run
|
|
|
|
|
anyway**.
|
|
|
|
|
|
|
|
|
|
**Linux.** Nothing to allow. If the file is not executable, run
|
|
|
|
|
`chmod +x ~/.plan2code/app/plan2code-app`.
|
|
|
|
|
|
2026-10-25 12:51:13 -07:00
|
|
|
## Permission checks are off by default, same as the terminal
|
2026-10-23 10:09:18 -07:00
|
|
|
|
2026-10-25 12:51:13 -07:00
|
|
|
The launch card's permission-mode tick is **on by default** (checks off), matching `plan2code` run the
|
|
|
|
|
plain way: the agent starts with checks off (`--permission-mode bypassPermissions` in Claude Code,
|
|
|
|
|
`--permission-mode bypass` in Devin, `--dangerously-bypass-approvals-and-sandbox` in Codex), reading,
|
2026-10-25 15:33:39 -07:00
|
|
|
writing and running commands in your project folder without asking; the agent's amber **checks off** badge in
|
|
|
|
|
the top bar says so while that agent runs. Untick it before pressing Start agent to keep the agent's normal approval prompts instead.
|
2026-10-25 12:51:13 -07:00
|
|
|
New Session keeps the same choice. Work in a folder you are happy for the agent to change, and keep it under
|
|
|
|
|
version control.
|
2026-10-23 10:09:18 -07:00
|
|
|
|
|
|
|
|
## Remove it
|
|
|
|
|
|
|
|
|
|
Choose **Uninstall** in the installer menu: it removes the app with everything else Plan2Code
|
|
|
|
|
installed. To remove only the app, delete the `~/.plan2code/app/` folder.
|