- [New here? A two-minute tour](#new-here-a-two-minute-tour)
- [Quick start](#quick-start)
- [What you get](#what-you-get)
- [Using it](#using-it): the dashboard, no agent found, your role, your workspace, subagents, your notebook, Activities, the session meter, building, review, ending a session, attachments, Ask, updates, keyboard
<img src="../docs/screenshots/dashboard-light.webp" alt="The Plan2Code dashboard: a Set up card, then the steps in order as cards, one of them marked Suggested.">
<img src="../docs/screenshots/dashboard-utilities-light.webp" alt="The utility cards: Get a PR ready, Write missing tests, Clear out dead code, Prototype a screen, Changelog, and Git, which notes that the folder is not a git repository yet and offers to start one.">
- **Every question laid out**, with the trade-offs next to each option, a progress bar ("4 of 9 settled") and Previous and Next under each card.
- **Help with the answer.** An *Autofill suggestion* button puts an example in the box for you to edit, and *Ask for suggestions* in the notes panel asks Plan2Code what it would pick and why. Some pick lists open with the suggestion already ticked; an empty pick is an answer too.
- **Settled answers read as answers**: what you chose, in words, with the rest locked. A question you have sent is held until Plan2Code answers it, and the page carries on working meanwhile.
- **Nothing is sent until you press Send**, and nothing gets lost: close the tab, reload, restart the machine, and your half-typed answers are still there.
<img src="../docs/screenshots/question-light.webp" alt="A Plan question card, How tasks are paged, with three options, the first marked Suggested, each with its trade-off underneath.">
- **The document taking shape**, in a tab, with the parts that are still guesses marked as guesses. A spec's **Overview**, **Map**, **Plan draft** and **Prototypes** tabs appear when the files exist: read-only, and read fresh from disk each time you open one.
- **A brief, on demand** (Pathfinder). *Write a brief*, choose how far back, and a plain-English report of what is decided, open and next opens in its own tab with Print and Save. It is the thing you take to a meeting.
- **It tells you when the other half stops listening.** The terminal and the page fail separately, so the page says so and what to do; answering anyway still works, because what you send is held on disk until something comes for it.
- **Whose turn it is, at a glance.** A chime plays when new questions arrive or a tab joins (a *Play sounds* switch and a box per moment are in User Preferences, with a menu of 19 sounds for seven of them). The tab icon's bar is dashed amber while Plan2Code works, solid green on your move and solid red when it has gone quiet or the connection is lost. After about 30 silent seconds, Planny asks whether it is still working or waiting on an approval in your terminal.
- **Yours to set up.** Light or dark and a highlight color, a **Card width** of Narrow (720px), Comfortable (880px, the default), Wide (1080px) or Ultra wide (1440px), and a role that puts the most useful starters first (see *Your role*). All remembered on your machine.
- **Files in your notes, and a notebook of your own.** Attach a screenshot or a document to any note or quick question (see *Attachments in notes and questions*), and keep a private notebook per folder (see *Your notebook*).
- **Where you are, at the bottom.** The footer names the folder and its git branch; click it to open the Workspace dialog (see *Your workspace*).
- **Help.** The **?** at the top right opens a Help dialog with 23 topics, one per tab, opening on the one for where you are. It is part of the page, so it reads fully even when the page has lost its program.
An Implement phase ends on a sign-off card: read the completion report, then review the code first, approve the phase, or ask for changes. Implement + Review has already reviewed the code, so its card has no review button. Finalize always offers one last review of the whole feature after its checks, before the summary is written and the spec is archived.
<img src="../docs/screenshots/signoff-light.webp" alt="The Approve this phase card, with a button to read the completion report and three choices: Review the code first, Approve this phase, and I want changes.">
The **Ask** tab is a chat beside the cards, for a quick question at any point. When a question is really a new task, the answer ends with a ready-to-paste prompt in a block with a Copy button.
The easy way in is the dashboard: type `/plan2code` in your agent, or run `plan2code` in your project. A page opens with every skill as a card (the setup pair, the pipeline in order, the utilities alongside), a note about what it made of your project, and a *Suggested* flag on the card it would pick. Click a card and the same page becomes that skill's console, already running.
- **Specs and their states.** The picker at the top chooses the spec. A diagnosed bug reads *Bug diagnosed* (Quick task suggested, Plan lit), then *Bug fixed* once Quick task has fixed it; a held-back upgrade from Update dependencies reads *Upgrade ready*, then *Upgrade done*. A finished one can be archived, or deleted from its chip.
- **Handoffs.** Handoffs this folder has not picked up follow the specs as dashed chips. Select one to preview it, then **Pick it up here**, **Read it all**, **Copy for a new conversation** or **Delete**. They live in `~/.plan2code/handoffs/`, written by *Stop with a handoff* (below) and by the Handoff skill.
- **Git and the utilities.** **Git** opens a board with three tabs (Changes, Branches, Sync) and asks before every push, publish and delete; outside a repository it offers to start one. **Codebase X-ray**, **Diagnose a bug** and **Update dependencies** are always available too.
- **Learning.** A row shows *Not set up*, *Off*, *On* or *Paused for you*; **Pause for me** pauses it for you alone. A banner offers **Review** while lessons are waiting. Kept lessons go to `.plan2code/lessons/` in the project; waiting lessons and your pause stay on this machine, and nothing is committed for you.
- **Planny wakes up.** A fresh dashboard starts with him asleep; click to wake him (**Skip** or Escape skips it, and reduced motion shows the awake dashboard at once).
Or start any step by its command (the full list is in the README's [Prefer the terminal?](../README.md#prefer-the-terminal) section), and add `--web` to open the console without being asked: `/plan2code-1-plan --web plan a lunch voting app`. Without it, the first question is "In your browser (suggested)" or "Here in the terminal". The page opens straight away at a `127.0.0.1` address, with a starting screen while the skill reads your project. You can switch to the terminal at any point: the files under `specs/` are the same either way.
While the page is open, the agent's messages in the terminal end with `→ Look at the web console` and, while it waits on you, say *Waiting on your answer in the web console*.
The link only works on your own machine, by design, so to work through a session together, share your screen. For the same reason an agent in a cloud VM, a container or over SSH stays in the terminal.
The **die** in the top bar opens **Activities**: thirteen small games to play while you wait, say through a long build (Snake, Mini golf, Light Trails, Bug Hunt, Sunset Drive, Stack Deploy, Bumper Ring, Rapids Run, Hot Potato, Crossing Rush, Bounce Road, Ghoul Rush and Flock Dash). A game pauses the moment it is your turn, and only you resume it. Best scores stay in `~/.plan2code/console/looks.json` on your machine and never reach the agent. User Preferences → Sounds & activities hides the die and the sounds. Every game, with its rules and controls, is in [the Activities guide](activities.md).
| In User Preferences: arrow keys, `Home`, `End` | Move between its four tabs (up and down in the side list, left and right in the strip on a narrow window) |
The gear button in the top bar opens **User Preferences**, always on its first tab. Its four tabs sit in a side list, or in a strip along the top on a window narrower than 720px, and the arrow keys, `Home` and `End` move between them:
On Appearance and Sounds & activities each change saves the moment you make it, and a small **Saved** mark shows beside it. **Close** (or `Esc`) shuts the dialog. **Reset this tab** resets only the tab on screen, and offers **Undo** for a few seconds: Appearance's four settings (Role back to *Not set*), or every sound and the two Activities switches (Show Activities and Play activity sounds); Activities best scores stay. It is not shown on Agents & models or System, which have nothing to reset.
Most people never need this tab: Plan2Code finds the agents installed on the machine and ships an up-to-date model list with every release. It opens on a roster of cards, one per agent, each showing whether its command was found on this machine, the model Thrifty, Balanced and Best use, and how many models it has. Opening a card puts that agent's form in a drawer over the roster, with two tabs: **Models & strengths** and **Launch** (a built-in's Launch tab only reads, because Plan2Code ships and updates its command). **Add agent** opens a chooser: the same starter templates the setup page has (GitHub Copilot CLI, OpenCode, Gemini CLI, Pi), each saying whether its command is installed here, or a **Custom agent**. Picking a template opens the new-agent form prefilled rather than saving anything behind your back; a template whose command an agent already uses is shown as *Already added*. Nothing on this tab saves as you type: each form has its own **Save** and **Discard**, and shows an **Unsaved** badge while it holds a change. Leaving a form with an unsaved change (another tab, **Close** on the drawer or a click outside it, **Close** on the dialog, `Esc`) asks first: save it, discard it, or keep editing. `Esc` backs out of the chooser, then the drawer, before it closes Preferences. Saving one agent never sends another's half-typed edit.
**Models.** The `plan2code` launcher's model menu comes from `models.json`, which every install overwrites with the authors' curated list. Each built-in agent's form (Claude, Devin, Codex) shows that list under *Comes with Plan2Code*, and below it **Models you added**, each a model id and the name shown in the menu, for a model that came out before Plan2Code was updated. Additions are kept in `~/.plan2code/models.json` and survive updates, unless the curated list now includes them; **Remove** takes one out. Restart `plan2code` to see a change. You can always run `plan2code --model <id>`, or switch model inside your agent before running a skill. Devin ids ending `-xhigh` or `-max` are refused. Maintainers refresh the curated list, and the shipped agent list's install data, with the repo-local `/plan2code-launcher-update` skill, which shows a diff and changes only what they approve.
**Strengths in the loop.** On the *Models & strengths* tab, an **In the loop** box shows the model **Thrifty**, **Balanced** and **Best** use for that agent (and an effort, for agents that take one), and tapping a word on a model in the list below it makes that model the pick, one per word. Rows you have not changed show as shipped, tagged *default*; a changed row has **Reset**. The Implementation Loop's **Strength per phase** setting reads these three words to start each phase, its retry and its subagents on the model you chose (see the Implementation Loop in the desktop app's guide). Saved with the agent's form in `~/.plan2code/models.json`.
**Agents.** An agent you add is an agent CLI Plan2Code did not find on its own, which the `plan2code` command and the desktop app can then start. Each one has a name, the command to run (a bare name looked up on `PATH`, or a full path), and optional fields:
- **Arguments**: one per row. `{prompt}` is replaced by the start prompt (for example `--message={prompt}`); with no `{prompt}` anywhere, the prompt is added last.
- **Bypass arguments**: added when permission checks are off.
- **Model arguments**: added when a model is chosen, with `{model}` replaced (`--model` and `{model}` by default).
**Test** beside the command shows where it is found, or "Not found on PATH", and never runs it. Saving a duplicate name, a blank command or a built-in id marks the field and writes nothing. **Delete agent** asks once more on the form before it removes one. The list is plain text in `~/.plan2code/agents.json`, shared by the `plan2code` command and the desktop app; this page is the only thing that writes it, and a broken file or entry is skipped with a warning shown on the tab, never a crash. If the file holds something the page could not read, saving asks first (**Save anyway**). `/plan2code` works only in agents that load the installed Plan2Code skills.
**Cleanup** lists what Plan2Code does not need in `~/.plan2code/`, with sizes, before anything is deleted (**Find files to clean up**, then tick what to delete and press **Delete N items**: sessions, named by skill, title and age, and strays start ticked, Notebooks and old completed specs start unticked); what it offers and what always stays is under *Or clean up on demand* below.
**Desktop app** appears only when the page is open inside the desktop app. Its switch, **Show on the taskbar when Plan2Code needs me** (on by default), controls the app's taskbar signal: on Windows a green dot on your move and a red one when it needs attention, plus one short burst of flashes when the window is not focused (the button stays lit until you look); on macOS a red `!` dock badge when it needs attention and one bounce; on Linux a badge where your desktop supports it. Turning it off clears the dot and stops flashes. The choice is kept by the app in its own `~/.plan2code/app.json`.
| You closed the tab | Open the link again. Everything is where you left it. After about two minutes with no tab open the link stops working: ask the agent to resume the session for a new one. |
| The link stopped working | Tell the agent. It restarts the session and gives you a new link. |
| Your agent session died while you were mid-answer | Press Send anyway. Your answers are written to disk and are never discarded, including when the session is restarted. The next session picks them up. |
| The page says Plan2Code is not running | It has not checked in for a few minutes. Look at the terminal: it may have finished its turn, hit an error, or be waiting on you there. If it is idle, type `continue` in the terminal and it picks your answers up (in the desktop app, the **continue** or **Reconnect to agent** button in the sidebar, beside Send on the Ask tab, and on a saved launch types it for you). Answering here still works, and what you send is held for it. |
| You are not sure anything is connected | The **?** at the top right opens Help. Its *What this page is* tab says what keeps the page alive and whether both halves are talking at that moment, and *When something looks stuck* covers what to check. |
| You would rather use the terminal after all | Say so. Nothing is lost. |
The console is a local server on `127.0.0.1`, bound to your own machine, that reads files in your project and never writes to it. Its state lives in your home folder, and every request needs a per-session token. The full model, with every route, is in [the internals guide](web-console-internals.md#security).