nyyon-planner

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)

npm install

{
  "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

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

Part of a family

Built like nyyon-figures: a local, offline MCP server where the calling assistant does the thinking and the tool does the persistence and the drawing. MIT.