Every decision taken while turning the original design notes into the implementation spec and the implementation, with rationale. Numbered so code comments and the plan can cite them (A1, A2, ...). Decisions the user made explicitly (2026-09-28 Q&A) are marked [user].
- U1 [user] Stack: TypeScript on Node 24 for both server and CLI. Fastify + node-postgres.
- U2 [user]
skill/holds both a Claude Code plugin (hooks +/mokkan) and a Codex skill, both wrapping onemokkanCLI. - U3 [user] Acknowledgment is explicit: the user runs
/mokkan ack <id>(orack all) for every viewed reminder. Hooks never auto-acknowledge. - U4 [user] Deployment target is local dev only: HTTP on 127.0.0.1, Postgres in Docker. HTTPS is left to a reverse proxy later.
- U5 [user] Postgres row-level security is used if it is fast enough (perf gate in spec §3).
- U6 [user] Emails are mocked (no SMTP).
- U7 [user] No UI testing inside Codex; the user tests that by hand.
- U8 [user, 2026-09-29] Status line: show the most recently added reminder plus "+N more"; show reminder text by default; a due reminder unseen for more than 15 minutes is "overdue" (red); Codex is covered via a tmux
status-rightmode because Codex has no command-backed status line. - U9 [user, 2026-09-29] Prepaid credits. EUR 5 buys 500 credits (1 credit = 1 cent); packs are Stripe prices found by
lookup_key, credits from the price'smetadata.credits, default packcredits_500. Push = 1 credit; every 3rd edit = 1 credit; a scheduled email = 1 credit. pop, dequeue, ack, deliver, list, pending, heartbeat, /me and billing reads are free. - U10 [user, 2026-09-29]
PATCH /reminders/:ideditstextand/ordue_at(nullclears it); one successful PATCH is one edit; no reordering. - U11 [user, 2026-09-29] The email credit is debited when the scheduler actually sends (claim and debit in one transaction) and refunded if the send fails. Pushing with any
due_atneeds a balance of at least push cost + email cost × (outstanding + 1), where outstanding = reminders with a due time that have not been emailed and are not acknowledged (scheduled, due, or shown in a session but not yet acknowledged;mokkan ackreleases the reserve; the edited one excluded), but debits only the push; setting a due time via PATCH needs the same reserve (plus that edit's own debit); the 402requiredreports that number; the email debit may take the balance below zero, so a promised email is never dropped. Escalation emails are charged the same way; a reminder is emailed at most once. - U12 [user, 2026-09-29] At zero credits paid actions answer 402
insufficient_credits; reading and completing stay free. When a debit takes the balance from above 0 to 0 or below, one "out of credits" email is sent (re-armed by a grant or purchase). - U13 [user, 2026-09-29] 50 starter credits on sign-up (
STARTER_CREDITS, 0 disables) as agrantledger row. Credits never expire; refunds are manual in the Stripe Dashboard and the webhook removes the refunded share. - U14 [user, 2026-09-29] VAT via config flag
STRIPE_AUTOMATIC_TAX(default false). Mailer is generic SMTP via nodemailer (MAILER=smtp, set up for Zoho);MAILER=mockstays for tests and dev. - U16 [user, 2026-09-29] Release-gate fixes. The status line runs plain
nodewhencommand -v noderesolves to the same real file as the running binary, else its absolute path (README says so). From Claude Code (--exit-zero, i.e. /mokkan or /mokkan:mokkan) plainstatuslinesets up Claude Code only (removal still takes out mokkan's own tmux block). Auto setup skips tmux when the config has its ownstatus-rightor a TPMrunline and prints the#(…)to combine; explicit--tmuxthen needs--force. Configure-vs-render depends on stdin being a terminal only. - U17 [user, 2026-09-29] The public repository will be
github.com/vicmpen/mokkan, published later from a fresh squashed history;vicmpen/mokkan-skillstays private. The marketplace name staysmokkan. The support address is the Zoho sending address on mokkan.dev (the one on Stripe receipts). - U15 [user, 2026-09-29]
mokkan statuslineconfigures the status line (Claude Code'ssettings.json, plus a marked tmux block for Codex and terminals) andmokkan statusline --renderrenders it. Codex's own config is not touched: its footer cannot run a command. Supersedes A33. - U19 [user, 2026-10-05] Notifications (
mokkan notify) are read-only: a poll callsGET /reminders/pendingand nothing else, with no heartbeat and nodeliver. An unacknowledged scheduled reminder still escalates to email, so a notification nobody saw loses nothing. - U20 [user, 2026-10-05]
mokkan notify setupdetects the platform and whether a desktop session exists, then offers the best setup it finds: a launchd agent on macOS, a systemd user timer on Linux with a desktop and systemd, XDG autostart on Linux with a desktop but no systemd, and only the prompt hook on a headless machine or WSL. It asks before each step. - U21 [user, 2026-10-05] The prompt hook supports zsh, bash (including macOS's bash 3.2) and fish. Shells, desktop backends and agents are registries of small modules with a shared contract test, so other systems can come as contributions (
CONTRIBUTING.md, a PR template, an issue form asking formokkan notify doctor). - U22 [user, 2026-10-05] The terminal escape over SSH (OSC 9/777/99) is opt-in: the
oscsetting is off by default, and when on, the shell sends it only when$SSH_CONNECTIONis set. - U23 [user, 2026-10-05] Only scheduled reminders notify:
due_atset and passed, not acknowledged, frompending.dueandpending.awaiting_ack. Plain pushes never do, and a reminder already shown in a session or emailed still counts until it is acked. Every open shell prints the set once per change, remembered in a shell variable rather than a shared file.
- A1 Popped/dequeued items move to a
donehistory (soft delete) rather than being deleted. The user's answer chose explicit ack but did not object to the history default; history costs one column and makes accidental pops recoverable. If wrong: switchpop/dequeuetoDELETE, one-line change in the service. - A2 Ports: Postgres on
127.0.0.1:5439(5432–5434 are taken by other projects' containers on this machine), API on127.0.0.1:8787. Both overridable by env. - A3 Lifecycle extends the design's three states (due → delivered → acknowledged) with
scheduled(futuredue_at, not yet on the list) anddone(popped). A future reminder is not "due", and the design's "done history" open question needs a terminal state. The three design states keep their exact meaning. - A4 A pushed item (no
due_at) starts in statedue: it is on the list now. It is shown by the next hook run and markeddelivered; it then waits for explicit ack (U3). It still stays on the stack after ack until popped/dequeued; ack only means "I saw it". - A5 RLS applies to
remindersandtokens(the account-scoped data).accounts,otps,rate_limits,outboxare not under RLS because login/OTP/rate-limit lookups happen before an account context exists. Token lookup by hash goes through aSECURITY DEFINERfunction so the app role never reads the tokens table directly. If the perf gate (200 pops, mean < 20 ms) fails, RLS is dropped in favor of explicitWHERE account_idand this line is updated. - A6 Two DB roles: the Docker superuser
mokkanruns migrations; the API connects asmokkan_app(LOGIN, no BYPASSRLS, not table owner) so RLS is actually enforced. Two connection strings in.env. - A7 Email escalation applies only to scheduled reminders (
due_atset). Pushed list items are never emailed: emailing every un-acked list item after 3 minutes would be spam, and the design's routing section talks about "when a reminder fires". - A8 The scheduler lives in the server process (design §3 says "the server holds due_at ... and a scheduler checks for due items"). The client-side "background watcher" therefore does not decide email routing;
mokkan watchis a foreground poller that sends heartbeats, prints due reminders to the terminal, and marks them delivered. Packaging as a daemon (systemd/launchd) is documented, not automated, because it cannot be tested here. - A9 Design's "optionally both" routing is expressed as
ACK_GRACE_SECONDS=0(email immediately after in-session delivery) rather than a separate mode flag. Fewer code paths. - A10 Optimistic concurrency uses a per-account
list_versioncounter and an optionalexpected_versionon pop/dequeue/ack (409staleon mismatch). Push is idempotent via an optionalclient_idinstead of a version, because a push never conflicts with another push. Atomicity of pop/dequeue is guaranteed by the single-statementUPDATE ... WHERE id = (SELECT ... FOR UPDATE SKIP LOCKED)form regardless of versions. - A11 Tokens are opaque random strings stored hashed, not JWTs: revocation and rotation are then trivial and there is no signing key to manage. Access token 24 h, refresh 90 days, rotation on refresh with family revocation on reuse (design asked for expiry + refresh; exact numbers are mine).
- A12 Password hashing uses argon2id via
@node-rs/argon2(prebuilt binary, no native toolchain needed). Minimum password length 10. - A13 OTP is 6 digits, 10 minutes, 5 attempts, 3 sends per email per 15 minutes; login 10 attempts per email per 15 minutes; 20 auth calls per IP per 15 minutes. Design said "five to ten minutes" and "rate-limited"; numbers are mine.
- A14
register/startreturns 409 when the email already has an account instead of a silent 202. This is a personal tool; the friendlier error beats enumeration resistance. - A15 The Stop hook surfaces reminders by returning
{"decision":"block","reason":...}so Claude relays them in its next reply, plus asystemMessagefor the user. Plain stdout from a Stop hook is not shown to the model. It blocks only when there are newly due reminders andstop_hook_activeis false, so it cannot loop. If this proves annoying, switch tosystemMessageonly. - A16 The
/mokkanslash command uses Claude Code's!bash expansion (allowed-tools: Bash(mokkan:*)) so the CLI runs deterministically before the model sees anything, and the model is told to relay output verbatim.register/loginneed hidden input; run from a terminal, the slash command only starts the OTP flow. - A17 Codex has no stable hook mechanism in the installed version (0.106), so the Codex skill instructs the agent to call
mokkan heartbeatandmokkan pendingat task start/end. Installed by symlink to~/.codex/skills/mokkan. Untested beyond lint (U7). - A18 The CLI credentials live at
$XDG_CONFIG_HOME/mokkan/credentials.json(default~/.config/mokkan), dir 0700 file 0600, and the CLI refuses to run if the file is group/world readable. Rotation policy: refresh rotates the refresh token;mokkan logoutrevokes the family. - A19 Tests run against the real Docker Postgres (no in-memory fake), and the scheduler is driven with an explicit
nowso tests never sleep. The end-to-end script is bash and asserts on the outbox. - A20 The repo was initialized as a git repository (
main) because the workflow commits per task. No remote is configured. - A21 Mock emails are written to an
outboxtable and toserver/outbox.jsonl, exposed viaGET /dev/outboxonly whenMAILER=mock. This is how the OTP is read during registration in dev. - A22 Heartbeat "recent" means within 300 s. Stop hooks fire on every reply so a live session refreshes far more often than that.
- A23 Duration syntax for
mokkan in:Ns,Nm,Nh,Ndand combinations like1h30m. No natural-language dates. - A24 The
listoutput orders top-of-stack first (highest position).pop= top,dequeue= bottom, matching the design's LIFO/FIFO description. - A25
tokens.last_used_at(listed in the spec's data model) is omitted from the schema: nothing reads it, and updating it on every request would add a write per call./melives inauth/routes.tsrather thandelivery/routes.ts; cosmetic. RLS is both ENABLED and FORCED onremindersandtokens; the Docker owner role is a superuser and bypasses RLS regardless, which is why the scheduler uses the admin pool (A6). - A26 Refresh rotation revokes the whole token family, including the still-valid access token. Two CLI processes refreshing the same family at the same instant (e.g. a Stop hook and a
/mokkancommand inside the 1-hour pre-expiry window) trip reuse detection and force a re-login. Chosen because reuse detection is worth more than that rare inconvenience; the pre-emptive refresh window keeps it rare. Processes on one machine no longer trip it (A28); it remains only for two different machines using the same tokens (e.g. a copiedcredentials.json). Separate logins start separate families and never interfere. - A27 The scheduler records
email_sent_atunconditionally after sending, even if a hook delivered the reminder in-session between the scheduler's SELECT and UPDATE, so a reminder can never be emailed twice. - A28 Every mokkan process on a machine (the hooks of each Claude Code session,
mokkan watch, commands) shares onecredentials.json, and the server stays strict about refresh-token reuse (A26). So before any refresh (pre-emptive or after a 401) the CLI re-reads the file and, if another process already rotated the refresh token, adopts the stored tokens and retries instead of refreshing. The re-read, refresh and save run under an exclusive lock filecredentials.json.lock(created withopen(..., 'wx'), polled every 50 ms for up to 5 s, removed by its owner infinally; a lock older than 30 s is treated as left over from a crash and removed). When a refresh token is rejected anyway (expired, revoked, logged out elsewhere), the CLI removes the dead credentials file and saysSession expired on this machine; run: mokkan login; hooks log that once, then log "Not logged in" at most hourly (marker filehook.log.notified). - A29
mokkan statuslinefetchesGET /reminders?scope=all(no new server endpoint). "Last added" = newestcreated_atamong reminders not yet popped/dequeued, acknowledged and scheduled ones included (they are still on the list, A4); ties go to the top of the stack. "+N more" counts the rest of that set. Urgency survives as colour, classified against the local clock at render time: red if any reminder is unseen (due, orscheduledpast its time) for more than the grace period, yellow if any is unseen, dim if onlydeliveredones await ack. Adeliveredreminder is never "overdue": a session already showed it. - A30 The status cache lives next to the credentials (
$XDG_CONFIG_HOME/mokkan/status.json, 0600), not in$XDG_CACHE_HOME, because it holds reminder text and so tests stay inside one temp dir. The TTL is measured from the last refresh attempt, so a down server is retried once per TTL, not on every render. - A31 Invalidation deletes the cache after push/pop/dequeue/deliver/ack/login/register/logout (
onListChangedinMokkanClient). A background refresh that started before such a change can rewrite slightly old data; that is bounded by the TTL (30 s) and accepted rather than adding version checks. - A32 The status line does not send heartbeats or mark anything delivered: showing a count is not delivering, and a timer-driven heartbeat would keep an idle machine "active" and suppress email escalation.
- A33 (superseded by U15 and A37)
install.shprinted the Claude CodestatusLineand tmux snippets and never wrotesettings.jsonor.tmux.conf. It still writes neither; it now tells the user to runmokkan statusline, which writes them on request. - A34 The CLI's default server is now
https://api.mokkan.dev(washttp://127.0.0.1:8787, A2/U4), because credits and Stripe Checkout need a public HTTPS server.MOKKAN_SERVER_URLand theserver_urlsaved incredentials.jsonstill win, so local development setsMOKKAN_SERVER_URL=http://127.0.0.1:8787. An existing login keeps the server it was made against. - A35
mokkan edit <n|id>takes the list number frommokkan list(active list, top first;--alluses themokkan list --allnumbering) when the argument is 1 to 3 digits: that is always a list number, and a number out of range is an error, never an id prefix. Anything else is an id prefix (as forack), resolved against all non-done reminders. The new text is positional (mokkan edit 2 call mom), with--textas an alias (not both). It sends the listversionasexpected_versionand retries once on a stale version, likeack. At most one of--in,--at,--clear-duemay be given, plus text; at least one change is required. Combining changes in one call matters because every call is one edit and every 3rd edit costs a credit. - A36 Exit code 3 means insufficient credits (402). The skill docs tell agents to relay
mokkan buyto the user and not to retry or buy themselves; buying needs a human and a browser. - A37
mokkan statusline(setup) rules. Only one status line can exist and it may be the user's own, so: (1) a Claude CodestatusLineis "mokkan's" only when its command is nothing but[node] <path ending in mokkan, mokkan.mjs, or a cli.js/cli.mjs under a path containing "mokkan"> statusline [render flags](no pipes,;,$(), quoting tricks); anything else is foreign and is never replaced without--force, and a foreign command that callsmokkan statuslinegets a hint to add--render. (2) mokkan's own entry is rewritten to<process.execPath> <cli> statusline --render, keeping its other keys (padding, a customrefreshInterval; default 30); equal JSON means "already configured" and nothing is written. (3) Writes are atomic (temp file + rename, through a symlink to its target, same mode) after a<file>.mokkan-bak-<UTC yyyymmddThhmmssZ>backup (-1,-2… on collision); invalid JSON or a non-object is refused. (4) tmux changes only the marked block (appended after a blank line, replaced in place, removed with that blank line); an incomplete block is refused; the user's ownstatus-rightlines stay and are pointed out. (5) Without a target flag Claude Code is set up only if its config dir exists and tmux only iftmuxis on PATH (PATH is searched, tmux is never run); "reload tmux" is printed as a hint whenever the block changed, without checking whether a server runs. (6) A CLI whose realpath lies under~/.claude/plugins/cacheor$CLAUDE_CONFIG_DIR/plugins/cacheis copied (0755, atomically, only when the bytes differ) to${XDG_DATA_HOME:-~/.local/share}/mokkan/mokkan.mjs, which the status line runs;mokkan hook session-startrefreshes that copy when it exists and never creates it. (7) Compatibility: any render flag (--render,--format,--no-text,--width,--ttl,--grace,--refresh) means render, so old tmux snippets keep working; the plain command with no arguments, no TTY and no--exit-zero, while settings.json's statusLine is mokkan's, is Claude Code running an old config: it migrates that one setting to--render(once; afterwards it is a read of settings.json) and renders, never touching tmux. Consequence: an agent without a TTY (Codex) must pass a target flag (mokkan statusline --tmux) to configure; the skill docs say so. - A38 The Claude Code plugin ships the CLI as one committed esbuild bundle,
claude-plugin/scripts/mokkan.mjs(ESM, node20, onlynode:imports). Plugins are copied from git into the plugin cache without running a build, and the status line's stable copy (A37) works only for a single file. It is not placed inbin/, because claude.ai and Cowork reject plugins that have a top-levelbin/.npm run check:bundleandtest/bundle.test.tsrebuild it in memory and fail when the committed file differs. The npm package keeps shipping the tsc output indist/. - A39 The plugin's
/mokkancommand became the skillclaude-plugin/skills/mokkan/SKILL.md, invoked as/mokkan:mokkan, so there is one entry and no name clash. The docs state that Claude Code substitutes${CLAUDE_PLUGIN_ROOT}in a plugin skill's body, including in!lines, and in itsallowed-toolsBash rules. The skill therefore runsnode ${CLAUDE_PLUGIN_ROOT}/scripts/mokkan.mjs --argline "$ARGUMENTS" --exit-zeroand pre-approves exactly that prefix. The path is unquoted, as in the docs' example, so that the permission rule matches the command text. An install path that contains spaces would break it. There is no PATH fallback in the!line, because a compound shell line would not match a simple rule. The PATH-based user command moved toclaude-command/mokkan.md, whichinstall.shlinks as/mokkan. A test keeps its body identical to the skill's except for the run line. - A40 The hook scripts try the plugin bundle first, then a dev checkout's
dist/cli.js, thenmokkanon PATH. Running the bundle by its path keepsprocess.argv[1]inside the plugin cache, so the SessionStart hook can refresh the stable copy. A dev checkout that has the plugin loaded with--plugin-dirnow runs the committed bundle rather thandist/. - A41
engines.nodeis>=20.3.0, the real minimum:AbortSignal.anyneeds 20.3. The previous>=24came from the dev machine. The bundle targets node20. Nothing has been tested on Node 20 itself. CI runs Node 22. - A42 [user, 2026-10-05] Design notes, plans, research and this decision log are committed to the private development repository but never published:
tools/export-public.shleaves outdocs/(all of it, whatever the subfolder),ASSUMPTIONS.md,.impeccable/,.superpowers/and.claude/, and the npmfileswhitelist (dist/**/*.js,codex/,claude-command/,CHANGELOG.md, plus README, LICENSE and package.json) keeps them out of the package. Public material for contributors goes inCONTRIBUTING.md. Until 2026-10-05 onlydocs/internal/was left out, so the 0.3.1 export published the TUI spec and plan (docs/superpowers/); the next export removes them from the public tree, and they remain only in its history. - A43 Plain
mokkan statuslinewith stdin not a terminal and without--exit-zeronever runs the setup (it is most likely a status bar refresh): an old mokkan statusLine is migrated to--renderand rendered; otherwise it prints one line and exits 0. A failed migration (read-only settings.json) is recorded in~/.config/mokkan/statusline-migrate-failedand not retried for 24 h. - A44 File edits write a temp file first, then take the backup, then rename; a failed rename deletes its backup, and the file is re-read just before the rename so a concurrent write by Claude Code is not overwritten (the command then asks to run again).
- A45
mokkan statuslinerefuses to point a status line at a CLI inside npm's_npxcache (--removestill works from there). Once a tmux config has mokkan's block, later runs update it without--force(the user opted in).--removedeletes the stable plugin copy when neither settings.json nor the tmux config mentions it any more. - A46 The plugin skill quotes
"${CLAUDE_PLUGIN_ROOT}/scripts/mokkan.mjs"in both the!line andallowed-tools(both must match; verified live by the reviewer with spaced and plain paths). The guardrails (never pass --force, logout or buy unless the user typed them) are indescription:, which the model reads before the command runs. The plugin skill writes/mokkan:mokkan …, the user-level command/mokkan …. - U18 [user, 2026-09-29] npm rejected the unscoped name
mokkanas too similar tomorgan. The package is published as@vicmpen/mokkan-cli(public,publishConfig.access), still installing themokkancommand; the Claude Code plugin and marketplace keep the namemokkan. - A47 [user, 2026-09-30] The terminal UI is a separate subcommand,
mokkan ui; baremokkankeeps printing the list. It is hand-rolled on Node built-ins (raw mode, ANSI escapes, a pure render function) rather than Ink, because the plugin bundle must stay a small single file: the status line executes it every 30 seconds. - A48 [user, 2026-09-30] Reminders in state
duethat the TUI shows are marked delivered, and every refresh (on start, every 10 s, after each action) sends a heartbeat with sourceui, exactly like the hooks andmokkan watch. Pop, dequeue, ack of the selected reminder and edit send the list version on screen; a 409 stale refreshes and asks to try again. Afterdeliverthe list is fetched again and its version adopted, so a pop right after delivery is not stale. - A49 [user, 2026-09-30]
eedits text andtedits the time as two separate PATCH calls (two edits).bopens Stripe Checkout with the same URL check asmokkan buy. Without credentialsmokkan uiopens on a login screen and a lost session returns to it;registerstays a CLI command (once per account, a one-time-code wizard). - A50 Overdue in the TUI is the status line's rule (due and unseen for more than
DEFAULT_GRACE_MINUTES). Bracketed paste is enabled: pasted text arrives as one paste key that only input fields accept, so it can never run commands. Display width is best effort (wide CJK ranges, emoji blocks, U+FE0F). Ctrl-C quits from every mode; Esc quits only from the login screen. - A51 [user, 2026-10-02] 0.3.0 removes the status line (render, setup, cache, stable CLI copy; U8, U15, U16, A29, A30, A32, A37, A43, A45 and the status-line half of A40 no longer apply).
mokkan statuslineremains for one release as a stub: without--removeit prints nothing when stdout is not a terminal (an old status bar keeps running it harmlessly) and one hint when it is;--removeundoes a 0.2.0 setup. The TUI keeps the shared formatting helpers insrc/text.ts. - A52 [user, 2026-10-02] The Claude Code pane is part of the plugin, as a function-hooks module (
claude-plugin/hooks/pane.tsx, named undermodulesin the samehooks.jsonas the shell hooks; its$.statecontract isclaude-plugin/types/index.d.ts). It runs the plugin's own bundle ($.plugin.root/scripts/mokkan.mjs), then a dev checkout'sdist/cli.js, thenmokkanon PATH.npm run test:pluginvalidates and tests it with theclaudeCLI; vitest does not load it. Done and ack stay two acts in the pane too:afinishes (or reopens),kacknowledges. - A53 The notify
stamprecords the time of the last poll attempt, written before the network call (the A30 rule), so a server that is down is retried once perintervaland never makes every prompt startnode. The agent and every shell share the stamp andpoll.lock, so a machine makes at most onependingcall per interval. - A54 A reminder id is marked notified in
notified.jsononly when the desktop notifier exits 0. A failure counts as an attempt and the id is given up after 3, so a notification daemon that is not up yet (the timer's first run at boot) does not lose the popup. Ids that are no longer notifiable are pruned. - A55 More than 3 new reminders in one poll become one summary notification ("4 reminders due"), whose result counts for each of them.
- A56
shell.txtand the notifications show the due time as a local clock time (HH:MMtoday,ddd HH:MMwithin 6 days, else the date), never a relative time: "5m ago" would change every poll and make every shell print again each minute. - A57
logout, session expiry anddelete-accountremove the reminder text innotify/(removeNotifyState) but keep the generatedinit.<shell>scripts, so the prompt hook resumes after the next login.notify removedeletes them too and keepsconfig.json. - A58 The
nodebaked into the agent and the snippet is the firstnodeon PATH when it resolves to the running binary, elseprocess.execPath: a PATH entry such as/opt/homebrew/bin/nodesurvives upgrades, a versioned Cellar path does not (the rule U16 had for the status line). The CLI path is the realpath of the runningcli.js. Onlynotify setup(andon/off, run from a shell) choose these paths; a poll that regeneratesinit.<shell>keeps the paths already in it, because the agent runs with launchd's or systemd's PATH, where the stable node is not found. - A59
notify setuprefuses to run from a CLI whose path contains/plugins/cache/,/.claude/plugins/or/_npx/, because those change with every update (the rule A45 had); it asks fornpm i -g @vicmpen/mokkan-cliorinstall.sh.shell initonly warns there. - A60 The gdbus backend writes every argument as a typed GVariant literal (strings double-quoted with
\,"and control characters escaped), becausegdbus callparses its arguments as GVariant text and would change plain text such as'x',123ortrue. Verified against a fake notification service underdbus-run-session. - A61 The systemd agent runs
daemon-reload,enableand thenrestarton the timer rather thanenable --now, because a running timer keeps its oldOnUnitActiveSecuntil restarted; this way a newintervalapplies when setup runs again. Identical files with the timer enabled and active are left alone. - A62 The launchd plist sets
PATH=/opt/homebrew/bin:/usr/local/bin:/opt/local/bin:/usr/bin:/bin:/usr/sbin:/sbin: launchd's default PATH lacks Homebrew, so the agent's polls would use osascript although setup tested terminal-notifier. It is fixed rather than copied from the setup shell, sostatusrenders the same plist from any shell. systemd needs nothing: Linux notifiers are distro packages in/usr/bin. - A63
shell.txtholds at most 20 reminders plus- … and N more: mokkan list --all, andosc.txtat most 3 (else oneN reminders dueline), because the prompt hook reads the file on every prompt. A poll whosependinganswer arrives after a logout writes no reminder text. - A64 Claude runs mokkan through a tool the mod registers at
session.start($.tool.register,mcp__mokkan__mokkan,isDeferred: true), answered by its owntool.callhook, instead of the skill's!line (A39, A46 for the plugin;/mokkan-clikeeps its!line). The input is{ command, args[] }and reaches the CLI as--exit-zero <command> <args…>, with--exit-zerofirst so that a--in the arguments cannot turn it into text. The hook refuses everything outsidelist push in edit ack done undone pending pop dequeue status balance notify(andnotifyother thanstatus test doctor on off), so the guard rails no longer depend on the model reading the description. The hook answers beforenext, so no permission prompt is shown, as with the old pre-approved!line. - A65
prompt.autocompleteoffers/mokkanverbs and, foredit,ack,doneandundone, rows from theviewatom (open rows; Archived forundone), matched by id prefix or text substring, at most 8, written as the full id. It answers only the word right after the verb, sinceedit <id>takes one id and the rest is text. - A66 The Bash guard (
tool.callonBash) matchesmokkan, a path ending in/mokkan, ormokkan-cli[@version], then any flags, thenacceptordelete-account, and denies with the tool's own refusal. It is a backstop to the skills' instructions, not a sandbox: a command line built some other way (a variable,node scripts/mokkan.mjs, an alias) is not caught. Text that merely contains the words (mokkan push "accept the offer") goes through. - A67 The pane uses
Text'sweight(semiboldwhere it drewbold;regularon unselected rows) and so needs Claude Code 2.1.299, the first release after 2.1.296 and the first whoseui.renderacceptsweight: 2.1.296 refuses the tree (Text prop "weight" is not allowed) and draws no pane. Checked by running the plugin's tests on 2.1.296 and 2.1.299.