planner / site

# Planner

> Planner is a free, open-source web app that runs on localhost and shows the HTML and Markdown plans coding agents write, side by side in split panes, live as they are written. It reads one or more docs folders (for example one per project), and has a `planner` command line that agents use to configure it and to show the user a plan.

What agents most often need:

- Install: `npm install -g @limyuquan/planner` (Node.js 20.19+), then `planner` starts it on http://localhost:4173.
- Show the user a doc in the Planner tab they already have open: `planner open '<link>'`. Links are `?ws=<task>/<phase-folder>&plan=<file>` (or `?ws=<folder>:<task>/...` for any docs folder but the first), or `?doc=<path or absolute path>`.
- Configure it: `planner config add <folder> [--name <name>]`, `planner config remove <name>`, `planner config show`, `planner config path`, and `planner config check`, which validates the config and prints what each folder holds (exits non-zero while anything is wrong).
- The config is `~/.config/planner/config.json`. Only changed keys are needed; any docs folder can override the layout keys (`statusFolders`, `plansFolder`, `phasePattern`, `fileTypes`, `groups`, `collections`) for itself. `planner config schema` prints the JSON schema.
- A running Planner picks up config and file changes by itself; never restart it to apply them.

## Docs

Each page is also Markdown at its URL with `.md`; the HTML docs are at https://limyuquan.github.io/planner/docs/.

- [Everything in one file](https://limyuquan.github.io/planner/llms-full.txt): every page below, the full text of each agent skill, and the config JSON schema
- [Introduction](https://limyuquan.github.io/planner/docs/introduction.md): what Planner is and does
- [Installation](https://limyuquan.github.io/planner/docs/installation.md): install, start, update, run from source
- [Quick tour](https://limyuquan.github.io/planner/docs/quick-tour.md): five minutes on the demo folder
- [Reading plans](https://limyuquan.github.io/planner/docs/reading-plans.md): sidebar, workspaces, panes, tabs, live updates, search, settling
- [Keyboard shortcuts](https://limyuquan.github.io/planner/docs/keyboard-shortcuts.md): defaults, and the hotkeys config
- [Links](https://limyuquan.github.io/planner/docs/links.md): link format, `planner open`, links inside plans, theme hand-off
- [Docs folders](https://limyuquan.github.io/planner/docs/docs-folders.md): how a folder is read: tasks, phases, doc types, groups, collections, several folders
- [Configuration](https://limyuquan.github.io/planner/docs/configuration.md): the config file and every key
- [Working with agents](https://limyuquan.github.io/planner/docs/agents.md): setting Planner up with an agent, showing plans, docs for agents
- [Agent skills](https://limyuquan.github.io/planner/docs/skills.md): planner-setup, link-plan and visualise
- [Command line](https://limyuquan.github.io/planner/docs/command-line.md): `planner`, `planner open`, `planner config …`
- [API overview](https://limyuquan.github.io/planner/docs/http-api.md): the local HTTP API: base URL, names, errors, and every data shape
- [API: Tree and docs](https://limyuquan.github.io/planner/docs/api-tree-and-docs.md): `GET /api/tree`, `GET /api/doc`, `GET /docs/<folder>/<path>`
- [API: Search](https://limyuquan.github.io/planner/docs/api-search.md): `GET /api/search`
- [API: Open and events](https://limyuquan.github.io/planner/docs/api-open-and-events.md): `GET /api/open`, `GET /api/events`
- [API: Tasks](https://limyuquan.github.io/planner/docs/api-tasks.md): `POST /api/move`
- [API: Config](https://limyuquan.github.io/planner/docs/api-config.md): `GET`/`PUT /api/config`, `POST /api/config/preview`
- [Troubleshooting](https://limyuquan.github.io/planner/docs/troubleshooting.md): common problems
- [Config JSON schema](https://raw.githubusercontent.com/limyuquan/planner/main/schema/config.schema.json): every config key with a description

## Agent skills

- [planner-setup](https://raw.githubusercontent.com/limyuquan/planner/main/skills/planner-setup/SKILL.md): set Planner up for the user: find their docs folders, match the layout rules to how each is organised, and check the result with `planner config check`
- [link-plan](https://raw.githubusercontent.com/limyuquan/planner/main/skills/link-plan/SKILL.md): show the user a plan in Planner with `planner open` instead of pasting a file path
- [visualise](https://raw.githubusercontent.com/limyuquan/planner/main/skills/visualise/SKILL.md): have a subagent write a plan, recap, codebase map, explainer, ELI5 picture page or review as one self-contained HTML page in a consistent style
- [visualise render guide](https://raw.githubusercontent.com/limyuquan/planner/main/skills/visualise/render/GUIDE.md): the full brief the writing subagent follows
- [visualise components](https://raw.githubusercontent.com/limyuquan/planner/main/skills/visualise/render/base.html): every component of the page style once, with the scripts to copy

## Optional

- [Code map](https://raw.githubusercontent.com/limyuquan/planner/main/CONTRIBUTING.md): how the source is laid out, for changing Planner itself
- [Website](https://limyuquan.github.io/planner/): with a live demo of the app
- [Repository](https://github.com/limyuquan/planner)