Just a moment
Opening the console
Getting everything ready…
Click to wake Planny
Connecting…
Just a moment
Getting everything ready…
A page for answering Plan2Code's questions, reading what it has written and approving things, instead of typing it all into the terminal.
New here?
A small program running on your own machine, started for you by Plan2Code in your terminal. Nothing here goes over the internet, and there is no account and nothing to install.
The address starts with 127.0.0.1, which always means "this computer". Nothing you type leaves your machine, and a colleague cannot open your link from theirs. To work through a session together, share your screen.
It stays up while this tab is open. Close the tab and it shuts itself down 2 minutes later. It also stops after 30 minutes without hearing from anyone, and after 4 hours regardless. Reopening the same link brings everything back: nothing you typed is kept in the browser alone.
The terminal is the other half. This page collects your answers; Plan2Code, in the terminal you started it from, is what reads them and writes the files. Both have to be running for a question to reach you or an answer to reach it.
If it stops. Press Send anyway. Answers are written to disk the moment they leave this page and are held until something collects them, so starting Plan2Code again picks them up where you left off. Nothing is lost by closing this tab either.
This page and Plan2Code in your terminal are two programs, and either can stop without the other. Nothing you have typed is lost either way.
If nothing seems to be happening, look at your terminal. Plan2Code often stops there to ask your permission, and this page cannot see it.
continue there."Reading Planny" shows every mood side by side.
Plan2Code sometimes stops in the terminal to ask your permission before it runs a command or changes a file, and this page cannot see that. After about 30 seconds of silence while it is working, the line beside Planny asks "Still working, or waiting on an approval in your terminal?" Have a look at the terminal: answering there sets it going again.
If it stays quiet a couple of minutes longer, the line changes to "Still working on it. Longer tasks can go a few minutes between updates", with Planny still in his working pose. It may be busy, or still waiting on you in the terminal; the terminal is where to look. A build that said a task may take longer gets that long before the line changes.
Hands-off modes, such as auto mode in Claude Code or
smart mode in Devin, cut down on those stops, though some
may still need you.
You can keep answering and press Send while Plan2Code is not running. What you send is written to disk and held until something collects it, so starting Plan2Code again picks it up where you left off.
The program behind this page shuts itself down:
To get it back, ask Plan2Code in the terminal to resume the session, or run the step's command again, and use the new link it gives you. Everything you typed, sent or not, is still there.
resume the session and print the web console address here
The page is laid out the same way in every session: a bar across the top, the outline on the left, the question or document in the middle, your notes on the right and the Send button at the bottom.
Planny sits at the top, with a line beside him saying whose turn it is and what Plan2Code is doing. Below him the outline lists the session's topics and every question in them, with how many are settled. Click any question to jump to it.
Under the top bar: Questions first, then Overview when the session is working on a spec, then one tab per document Plan2Code has written, and Ask, always last. Each tab remembers where you scrolled for as long as this browser tab stays open.
Previous and Next under each card walk the questions still waiting for you, so you never have to hunt for the next one in the outline.
Notes on this shows the back and forth about the question you are on, with a box for a note of your own. See "Notes and attachments".
The folders Plan2Code uses as context in this session: the folder you started in, plus any others you add, such as a shared library or a design folder next door.
Click the folder name in the middle of the bottom bar. It shows your folder's name and branch, such as shop · main, and shop + 2 folders · main once you have added some. It carries across steps you start from the dashboard.
workspaces.json in your own
Plan2Code settings folder, beside your look and feel, never in the
project. Finalize offers to forget a spec's list when it archives the
spec.
../shared counts from the folder you started in.
Type @ in the Ask box, a note or a typed answer and a list of your folder names appears. Pick one, and Plan2Code knows exactly which folder you mean, for example "use the button styles from @shared".
It reads the added folders for reference, and changes them only if you ask it to. Before it first uses one, it reads that folder's own notes for agents, so it follows that folder's rules as well.
/add-dir followed by the path: copy it and run it in the
terminal.
Planny, the little box with a star for an eye at the top left, shows at a glance whose turn it is, and the line beside him says it in words.
Leaning in and waving, his star lit in your highlight color. Something on this page is waiting for you: a question to answer, or answers ready to send.
Star turning, arms pumping, feet walking on the spot. Plan2Code has your answers and is thinking, or is busy building. The line beside him says what it is doing. After about 30 seconds of silence it asks "Still working, or waiting on an approval in your terminal?", because the terminal may have stopped to ask your permission for something, and this page cannot see that.
A green star. Nothing is waiting on either side: every question is answered and Plan2Code has nothing new yet.
A green star and both arms up. The session is finished. You can close the tab.
Grey, still, arms down out of sight. This page is fine, but Plan2Code has not checked in for 3 minutes. Anything you answer is still saved.
Faded, arms hanging, his star shut in red. This page cannot reach its program, after 8 seconds without contact. Your answers are saved.
For what to do about the last two, see "When something looks stuck".
Each question is a card, and every card works the same way: answer it, add a note if you like, and send when you are ready.
A settled card reads as an answer: what you chose, stated in words, with everything else locked.
A card you have sent is held until Plan2Code replies, showing what you sent. It unlocks by itself when it answers. The rest of the page keeps working, so you can read ahead or answer the next question meanwhile.
If a card has been held for a long time, Take this back and answer again puts your answer back in the box so you can change it and send again.
Nothing leaves this page until you press Send to Plan2Code, so you can answer, change your mind and answer again without committing to anything.
Press Send to Plan2Code, or Ctrl+Enter (⌘+Enter on a Mac).
A note lets you say more about any question, and an attachment lets you show instead of describe.
The Notes on this panel on the right belongs to the question you are on. Type in Add a note, attach a file, or ask something and it goes with your next send. A note qualifies your answer without replacing it: "B, but keep the header row" is an answer and a note together. Plan2Code's replies appear in the same panel.
Three ways, whichever is handiest:
Each file uploads straight away while you keep typing, and sits in a tray with a remove button. A failed upload offers to retry or remove, and holds back only that note, so the rest of your answers still send.
.docx, files that are too large, and dotfiles such
as .env, which is where secrets tend to live.
With the session, in
~/.plan2code/console/sessions/<id>/uploads/, never in
your project. They are removed along with the session after
30 days untouched.
The exception is a note attachment Plan2Code cites in a spec file.
Before it writes that file, it copies the attachment into
specs/<idea>/attachments/, so the link still works
after the session is gone. Files attached on the Ask tab always stay
in the session.
What Plan2Code writes appears here as it takes shape, one tab per document, so you can read along without opening a file.
Each document has its own tab beside Questions, with its version number next to the title. It is built from sections, and each section tells you how firm it is:
Out of date by the title means answers have landed that the document does not reflect yet.
When the session is working on a spec that has an
overview.md, the Overview tab shows it. It
is read-only, and read fresh from disk each time you open the tab, so an
edit shows up straight away. No file, no tab.
Write a brief, in the top bar, asks how far back to go: Today, This week, Since a date or Everything so far. Press Write the brief and Plan2Code writes a plain-English report of what has been decided, what is still open and what happens next. It opens in its own tab, ready to print or hand to someone who has not been in the room. Save as HTML, beside Print, downloads it as a single web page that opens in any browser, formatting and images included.
The front door: run /plan2code and every step Plan2Code
can take is laid out as a card. Pick one and it starts right here, on
this page.
Until you pick a role, a one-line banner at the top asks for it, so the starter templates can be ordered for you. Set up preferences opens User Preferences; Not now puts the banner away. Either way it does not come back, and you can change your role any time from the swatch button.
When a newer Plan2Code release is out, the dashboard shows
UPDATE AVAILABLE at the top. Click it for the command
to run in your terminal; × hides it until the next
/plan2code. The version at the bottom of Help links to
the Releases page.
They come in three groups.
First, the project
The steps, in order
Useful any time
Once your project has specs, Pick up a spec, or start fresh, at the top, lists every spec folder with where it stands, plus Start from scratch for a new idea. The one you pick is what a step works on, and it decides which cards make sense: a spec that is half built has no use for Pathfinder, and a new idea cannot be implemented yet. Cards that do not fit are greyed out with the reason why.
Hide unavailable workflows, under the picker, hides them instead. It is on to begin with, and remembered on this machine.
One card may carry a Suggested flag: where Plan2Code would start, given what it found in your project. No AGENTS.md yet suggests setting up; a spec part way through suggests its next step, with a line on the card saying where it stands.
Click a card and it asks you to confirm: what the step does, which spec it is for, and a Start button named after the step, such as Start Plan (Back, or Esc, returns to the cards). Press Start and Planny flies while it gets ready. A few seconds later this same page is that step, already running. No command to type, no second window.
When a step finishes, its last screen has a Back to the dashboard button that turns the page back into the cards, so the next step can start straight away. See "Stopping and finishing".
The small ring in the top bar counts how much work this console session has done, and tells you when a fresh one would serve you better.
Each step you run here adds points: a plan or a set of documents weighs more than a quick task, and a built phase more still, by how many tasks it completed: a big phase adds more than a small one. Every two questions you answer within one step add a point too (rounded down, so a single answer adds nothing), so a long back-and-forth counts for more than a short one. Click the ring to see the count and a list of each step that added points, with what it added. It is a rule of thumb, not a reading of Plan2Code's real memory: long sessions tend to make it miss things, and the ring is there to remind you.
Starting a new console session will keep Plan2Code sharp: stop this one, then start Plan2Code again in a new conversation. Resuming this session carries its count along, so it does not help. Your work is all on disk, so nothing is lost.
The meter never blocks anything. Red is advice; you can keep going.
Implement, Implement + review and Quick task spend most of their time building rather than asking, so the page shows you the build as it happens.
The line beside Planny says what Plan2Code is working on, for example "Task 5 of 9: the rate limiter". Tasks are counted within the phase, and the progress bar counts the same way: "5 of 9 done".
phase-3.md, is in the tab
beside it: what has to be true before the phase starts, and every
task in full, not just the checklist.
Anything the build needs from you, such as which phase to do next, a clash in the spec or tests that are failing, arrives as an ordinary card. Answer it like any other.
When the phase is built, a Completion report tab says what was done, which files changed and how to check it, and an Approve this phase card asks for your approval. Nothing is marked complete until you give it.
Some tasks take a while without anything to show. The build tells the page how long it may go quiet, and Planny only says it has stopped checking in once that time has passed.
The Git card opens one board for your repository: branches, pull, push and commits in one place. Every button is a request to Plan2Code, which runs the git commands and says what each one did.
While Planny works on a click, the bar is locked, so nothing queues up behind it. When it is done, a result line says what happened, with the commit hashes, and the board redraws from the repository as it now stands.
Done ends the session. If anything happened, the last screen lists the commits, pushes and branches created or deleted, with Back to the dashboard. If nothing did, the page goes straight back to the dashboard.
The same skill takes plain instructions, such as
/plan2code-git switch to main or
/plan2code-git commit and push, and asks the same
questions before every push, publish and delete.
On a build, a review and Pathfinder, Plan2Code can hand independent pieces of work to helpers (subagents) while it keeps the conversation with you. The Subagents button in the top bar, after Stop session, is lit while helpers are on.
The Ask tab, always the last tab, is a chat for anything you want to know, without waiting for a card to ask it on.
Ask about this project's files, or about anything at all. Plan2Code answers at its next check-in (during a build, once it finishes the task it is on), and the work carries on meanwhile. Asking never holds up your answers to the cards, and sending those never holds up a question.
The box starts with no context, so a question is a general one unless you say otherwise. + Add context, beside + Attach file, lists the last three places you visited (question cards, document sections, and a spec you picked on the dashboard) and This spec. Pick one and a chip, About: followed by its name, sits above the box. Press × on it to remove it. It clears after each send, so pick it again for a follow-up.
An empty conversation offers a few starter questions for this step, with the ones most useful to your Role first. Clicking one fills the box for you to edit; it never sends by itself. They come back with New conversation.
Enter starts a new line in the Ask box. Ctrl+Enter (⌘+Enter on a Mac), or Send, sends the question. It sends only the question, never your answers to the cards.
Ask for a change to a file and Plan2Code replies with a summary and
the list of files it would touch, with Approve and
Decline buttons. Nothing changes until you approve.
Afterwards it lists what changed, with line counts. Nothing is
committed, and it never touches the running step's own files under
specs/.
A chat message never answers a card or moves the work on. That is what the cards are for.
Either way, the conversation above stays readable.
If you are on another tab when a reply arrives, a dot appears on Ask and a chime plays once (if sounds are on).
Every session ends with a screen that says what happened and what to run next, whether it finished on its own or you stopped it.
Stop session, at the top, ends the session and saves your place. Any answers you have ready go with it, and Plan2Code gives you a command to pick up where you left off, in a new conversation.
The triangle left of Stop session leaves the step you are in for the dashboard, in this same session. Your place is saved the way a stop saves it, with any answers you have ready going along, and the menu appears here instead of a finish screen. From there, pick the same step again to carry on, or pick another one. It follows Stop's rules: it only works on your turn, it asks first, and it shows the same warning where nothing is saved yet.
Paused means there is more to do and your place is kept. Finished means this step is over.
Press Copy, then paste the command into the terminal
where you started Plan2Code, in a new conversation. When the next
step is another Plan2Code step, the command already ends with
--web, which asks Plan2Code to open this page again, so
you carry on here rather than in the terminal.
A finished screen (never a paused one) has a Back to the
dashboard button. It turns this page back into the cards, in
the same conversation, so the next step starts right here.
Plan2Code listens for it for as long as the session is open.
Once the session has closed, the button becomes the
/plan2code command to run in a new conversation
instead.
After a long step, a new conversation is the better choice anyway: it
starts with a clean slate.
Everything on the page works from the keyboard, and the gear button lets you make it look and sound the way you like.
| Keys | What they do |
|---|---|
| Ctrl+Enter (⌘+Enter on a Mac) | Send your answers (not while this Help is open). In the Ask box, send the question. |
| Enter in the Ask box | Start a new line. |
| Esc | Close a dialog, this Help included. On the dashboard, back out of a card you picked. |
| Tab / Space | Move between options, and pick one. |
| Arrow keys, Home, End in Help | Move between topics. |
Every control is a real button, option or checkbox, so screen readers and keyboard-only use work too.
The gear button at the top, beside ?, opens User Preferences:
~/.plan2code folder: sessions nobody has opened for
30 days, and files or folders that ended up there by mistake. It
also lists this project's specs--completed/ folders
nobody has touched for 30 days; deleting one is permanent, since
that folder is usually gitignored and git can't restore it. It
shows each one with its size, and Delete these
removes exactly that list. Your preferences, saved folders, models,
the launcher and the session you are in always stay.
Your choices are remembered on this machine and carry over to every session you open here.
The page has no motion switch of its own. It follows your computer's "reduce motion" setting, and with it on, the animations stay still.
Nothing on this page leaves your machine, and nothing it keeps lives in your project.
The page is served on 127.0.0.1, which only this computer can reach. It is not visible on your network, so sharing the link with someone on another machine will not work, by design. To work through a session together, share your screen.
The link carries a long private code. The first time it is opened, the page swaps that code for a cookie in this browser and takes it out of the address bar, so it does not linger in your history or show in a screenshot. Treat the link like a password all the same: anyone on this machine who has it can open the session.
Everything lives under ~/.plan2code/console/ in your home folder:
sessions/<id>/;
uploads/ (a note attachment cited in a spec file is also
copied into the spec's attachments/ folder; see "Notes
and attachments");
looks.json;
subagents.json.
A session nobody has touched for 30 days is removed, uploads and all, the next time a session opens. Your preferences are never removed.
Folders you add to your workspace last for one console session. The page keeps only each folder's path, name and description, and never looks inside.
What Plan2Code decides and builds is written to specs/
and your code, in your project. This page and the terminal are two ways
of working on those files; neither owns them. Losing a session loses
nothing that matters, and you can switch between the page and the
terminal at any time.