# nyyon-planner

![Nyyon Planner — Focus Sessions, weekly objectives, honest carry-over](assets/cover.png)

A **local MCP server** for day planning. Your AI assistant runs the planning *conversation*; this tool gives it memory and a method: saved day plans, weekly objectives, an honest carry-over ritual, and a rendered day card you can pin anywhere. No network, no model, nothing leaves the machine — every plan is a plain JSON file you can grep, diff, and sync however you like.

Extracted from the Daily Planner inside the Nyyon Command Center, where it plans real days.

## The method (what the assistant follows)

1. **Ground first** — one `plan_day` call returns today's plan, the week's objectives, and what's still open from recent days.
2. **The carry-over ritual** — unfinished items from past days surface *first*, and each gets a decision: done, carry over, or drop. Nothing silently disappears.
3. **Four questions, one at a time** — what do you want done today? any constraints? how many Focus Sessions fit? aligned with the week?
4. **Focus Sessions are the backbone** — ~2-hour deep-work blocks, each with **one concrete deliverable** (what will exist when it's done). Everything else is supporting blocks and to-dos.
5. **Strategic or wing-it** — a day either serves the week's 2-4 objectives or it deliberately doesn't. Both are legitimate; the plan says which.

The full brief ships in the server (`plan_day` returns it), so any MCP-capable assistant picks up the method with zero setup.

## The live panel (the part that closes the loop)

`open_panel` starts a tiny loopback-only web page — the day in the same aesthetic, but **every control is real**: tap a block or a to-do and it writes to the plan store; type a note ("replan the afternoon, I'm drained") and it's recorded. Each interaction becomes a **signal**, and the next `plan_day` call delivers all of them to the assistant exactly once as `panel_activity` — so the conversation always opens already knowing what you did with your hands. No fake buttons, no push magic: an honest pull on the next turn.

Loopback only, token-guarded URL, dies with the MCP process; the state is in the files either way.

## Follow-up and analytics

Because every day is one JSON file with done-flags, review is just a read. `review_period` computes any range (defaults to the last 7 days):

- **completion rates** — focus sessions, blocks, to-dos, and the starred few, planned vs done
- **the slippage list** — items that appeared on multiple days before resolving, and the ones **still stuck** (the honest follow-up feed)
- **strategic vs wing-it** ratio, and every touched week's objectives with their hit rate
- a `review_brief` telling the assistant how to narrate the retro: lead with what shipped, read rates as patterns not grades, close by drafting next week's objectives

"Do my week in review" or "how did this month actually go" becomes one tool call plus an honest conversation.

## The day card

`render_plan` draws any day as a clean 1080×1350 PNG — Focus Sessions accented, done items struck, the week's objectives at the foot:

<img src="docs/sample-card.png" width="540" alt="A rendered day card: schedule blocks with accented Focus Sessions, to-dos with starred priorities, weekly objectives at the foot">

## Tools

| tool | what it does |
|------|--------------|
| `plan_day` | **Start here.** The planning brief + today's plan + the week + the carry-over feed, in one call. |
| `save_plan` | Write the day: schedule blocks (`focus:true` for Focus Sessions, each with a deliverable) + to-dos (`star:true` for the critical few) + mode. |
| `update_plan` | Edit during the day — pass only the keys that change. |
| `read_plan` | One day's plan, with its still-open items computed. |
| `list_recent_plans` | Recent past days with their open items — the carry-over feed. |
| `search_plans` | Full-text search across every saved day. |
| `read_week` / `set_week` | The strategic layer: this week's 2-4 objectives. |
| `review_period` | Week/month analytics: completion rates, the slippage list, objectives hit rate + a retro narration brief. |
| `render_plan` | The day as a shareable PNG day card. |
| `open_panel` | The LIVE local page: real checkboxes + a note box; interactions surface as `panel_activity` on the next `plan_day`. |
| `get_settings` | Data dir, work week, theme — all env-overridable. |

## Install (Claude / MCP)

```bash
npm install
```

```json
{
  "mcpServers": {
    "nyyon-planner": { "command": "node", "args": ["/ABSOLUTE/PATH/nyyon-planner/src/index.js"] }
  }
}
```

Or with the CLI: `claude mcp add nyyon-planner -- node /ABSOLUTE/PATH/nyyon-planner/src/index.js`

## Settings

Everything is env-overridable (`NYYON_PLANNER_*`):

- `NYYON_PLANNER_DIR` — where plans live (default `~/.nyyon-planner`; plain JSON, one file per day)
- `NYYON_PLANNER_WORK_DAYS` — comma list, 0=Sun..6=Sat (default `1,2,3,4,5`; an Israeli work week is `0,1,2,3,4`)
- `NYYON_PLANNER_WEEK_START` — the week's anchor day (default: first work day). Weekend days roll forward to the coming week.
- `NYYON_PLANNER_TZ` — the "today" boundary timezone (default: system)
- `NYYON_PLANNER_PAPER / INK / MUTE / LINE / ACCENT / ACCENT_WASH` — day-card colors (hex)
- `NYYON_PLANNER_FONT_SANS / FONT_MONO / FONT_FILES` — day-card fonts (IBM Plex bundled)
- `NYYON_PLANNER_BRAND` — the footer mark on the card
- `NYYON_PLANNER_OUT` — where rendered cards are written (default `<data dir>/cards`)

## Test

```bash
npm test   # store roundtrip, week anchoring, card render — in a temp dir
```

## Part of a family

Built like [nyyon-figures](https://github.com/LevNyyon/nyyon-figures): a local, offline MCP server where the calling assistant does the thinking and the tool does the persistence and the drawing. MIT.