@eunjae/planner

Local markdown planning sessions with PR-like revisions, line comments, resolved threads, and configurable agent follow-ups.

Commands

planner setup
planner setup --agents pi
planner setup --agents codex
planner setup --background
planner agents list
planner actions list
planner new "Session title"
planner new "Session title" --agent-target <target-id> --agent-var key=value
planner new "Session title" --agent-target codex --agent-var "codexSessionId=$CODEX_THREAD_ID,cwd=$PWD"
planner new "Session title" --agent-target pi-extension --agent-var "piSessionId=<pi-session-id>"
planner attach-agent <session-id> <target-id> --var key=value
planner attach-agent <session-id> codex --var "codexSessionId=$CODEX_THREAD_ID,cwd=$PWD"
planner attach-agent <session-id> pi-extension --var "piSessionId=<pi-session-id>"
planner install-skill --agents pi
planner write <session-id> --file /tmp/plan.md
planner latest <session-id>
planner latest <session-id> --withComments
planner comments list <session-id>
planner comments add <session-id> --line 12 --content "Clarify this"
planner comments reply <session-id> <thread-id> --content "Updated in the next rev"
planner comments resolve <session-id> <thread-id>
planner setup --hostname my-mac.tailnet-name.ts.net --scheme https --bind-host 0.0.0.0
planner server start
planner server status
planner server stop
planner install-skill --all

Data is stored under ~/.config/planner. Agent delivery is configured by ~/.config/planner/planner.config.ts; planner setup installs skills, creates a matching config when none exists, and asks whether to start the background server. Sessions store generic agent metadata (targetId + variables), and the web UI uses the configured actions/targets to queue follow-up requests. The web UI is a TanStack Start + Tailwind app styled with coss/ui components. It is served at <configured-scheme>://<configured-hostname>:<port>/s/<session-id> and includes raw markdown, latest-revision changes, and comment threads. For Tailnet/LAN HTTPS setup, enable Tailscale Serve and pass planner setup --hostname ... --bind-host 0.0.0.0; .ts.net hostnames default to https.

planner install-skill writes an agent-specific skill file for each selected agent. Pi installs Pi linkage instructions, Codex installs Codex linkage instructions, and other agents receive generic attach-agent guidance.

When running from Codex, pass the current CODEX_THREAD_ID as the Codex target's codexSessionId variable. Without that session variable, the web UI cannot route Ask-agent actions back to the current Codex thread. planner setup --agents codex records the detected absolute codex binary path when available and adds the Planner home directory as a Codex writable directory, so Ask-agent actions still work when the Planner server is launched by launchctl with a minimal PATH.

Agent config

Create a global TypeScript config during setup:

planner setup
# or non-interactively
planner setup --agents pi --background
planner setup --agents codex --skip-server

The config can import helpers from @eunjae/planner/config:

import { definePlannerConfig, piExtensionTarget } from "@eunjae/planner/config";

const pi = piExtensionTarget({
  id: "pi-extension",
  label: "Pi",
  sessionId: (ctx) => ctx.variables.piSessionId,
});

export default definePlannerConfig({
  targets: [pi],
  actions: [
    {
      id: "reply",
      label: "Ask agent to reply",
      buildMessage: ({ sessionId, url }) =>
        `Planner request: Please review ${url} and reply to unresolved comments. Use planner session ${sessionId}. Do not resolve threads.`,
    },
    {
      id: "update",
      label: "Ask agent to update plan",
      requiresResolvedThreads: true,
      buildMessage: ({ sessionId, url }) =>
        `Planner request: Please update planner session ${sessionId} based on resolved comments at ${url}. Do not resolve threads.`,
    },
  ],
});

Install

npm install -g @eunjae/planner

The published CLI runs on Node.js 20+ and uses the package bin entry (planner -> dist/cli.js). After installing, run planner setup for an interactive setup. It recommends the launchctl background server, but you can skip it and run planner server run in the foreground only when needed.

Build

bun install
bun run build

The build first compiles web/ with TanStack Start/Nitro, then emits the Node CLI into dist/. Run planner setup to install integrations and launch the background service, or planner server start to only install/start the launchctl service.

End-to-end tests

npx playwright install chromium # first time only
bun run test:e2e

The E2E suite uses a temporary PLANNER_HOME, starts the built Planner server on a random port, and sends Ask-agent requests to a test config that writes JSONL locally.