Skip to content
nerln docs

Plancia

Claude Code and Codex already write down everything they do, in files on your disk, in different folders and different formats. Neither one reads the other. Plancia reads both and gives you one board of open tasks, a spoken recap of the day, and one place to send work back to either agent. It is a macOS tool for one person and one machine.

What it reads

Section titled “What it reads”
source where
Claude Code sessions ~/.claude/projects/**/*.jsonl
Claude memory notes ~/.claude/projects/*/memory/*.md
skills, plugins, routines ~/.claude/skills, plugins, scheduled-tasks
Claude Code task lists ~/.claude/tasks/<session>/*.json
Codex sessions and goals ~/.codex/sessions, goals_1.sqlite
GitHub gh repo list, recent commits
local git your code roots
session hooks SessionStart, SessionEnd

Everything lands in SQLite at ~/.plancia/. The sources are read and left alone.

What it does not do

Section titled “What it does not do”
  • It does not phone home. No telemetry, no account, no server of ours. The only thing that leaves the machine is work you explicitly hand to an agent, through the claude or codex command already installed, under your own subscription.
  • It does not modify the sources it reads.
  • It does not write to your code by default. Dispatching work runs in proposta mode: the agent reads and reports without touching a file. Writing requires --modo esegui, and that is a choice you make on every run.
  • It does not guess what you should do next. Recap proposals come only from signals in the data: a failed run, a Codex goal out of quota, files uncommitted since yesterday, an approved post that never went out, a stale next step. A quiet day gives you a short recap instead of an invented suggestion.
  • It does not run outside macOS. Requirements are macOS 13 or later, Python 3.9+ and Claude Code. Xcode command line tools are needed only to build the app, and gh only to read your repos.
  • It does not do the work. It reads, shows and dispatches. The agents do the rest.

Install

Section titled “Install”
Terminal window
git clone https://github.com/nerln/plancia.git ~/dev/plancia
cd ~/dev/plancia
./bin/plancia install      # command, MCP server, hooks, skills, autostart
./bin/plancia init         # builds your project map from repos, folders, memory
./mac/build.sh --install   # builds Plancia.app into /Applications

plancia uninstall puts everything back. Your data stays in ~/.plancia/.

Use

Section titled “Use”

Three ways in: the native app, with a menu bar item and URL actions (plancia://recap, plancia://jarvis, plancia://ask?q=…); twenty plancia_* MCP tools and a SessionStart hook inside Claude Code and Codex; the terminal.

Terminal window
plancia recap --speak                       # today, out loud
plancia recap --lang en                     # in English
plancia ask "what did I ship this week?"
plancia lavagna                             # the unified board
plancia manda "rerun the ablation" --agente codex --progetto atlas
plancia lanci                               # how the runs went
plancia daily on 08:45                      # every morning, as a notification

⌥Space opens Jarvis, a panel that listens continuously and decides from the silence that you have finished speaking. A text field covers a missing microphone or a misheard sentence.

How it works

Section titled “How it works”

The flow is sources ▸ sync ▸ SQLite ▸ briefing.md · recap · REST · voice, on two rhythms: a hot pass every two minutes reads the hook queue and the new tail of the transcripts, a cold pass every thirty minutes reads memory, skills, repos and git, then rebuilds the search index and the recap. plancia flusso prints every source, which pass reads it and how fresh it is.

Spoken answers take three routes: recognised commands and data questions run locally, anything else goes to a Claude Code process kept warm between questions so only the first one pays the startup. The recap is precomputed at the end of every cold pass.

Two parsing decisions are documented because they are easy to get wrong. Transcripts are read by byte offset rather than by line, since they run to hundreds of megabytes; lines over 256 KB are probed and never parsed. Record types are matched in full ("type":"assistant", "type":"user") because message.content contains other type fields that appear first.

Events are appended to ~/.plancia/eventi.jsonl, one JSON line per event, schema plancia.evento/1. A consumer keeps the id of the last event it saw and asks for what came after with plancia eventi --dopo <id> or GET /api/eventi. The file is append only and rotates at 5 MB.

The local server listens on loopback only, and HTTP writes require the token in ~/.plancia/token. Reads are open.

What is checked

Section titled “What is checked”

python3 tools/prova.py runs eighty two checks in about ten seconds, against a throwaway archive that never touches yours. Contributors turn it on as a pre-push hook:

Terminal window
git config core.hooksPath .githooks

The same suite runs in CI, in the prova.yml workflow. Separately, bin/plancia-hook --prova prints what the session hook would hand to Claude without queueing anything, so testing the hook cannot leave a session in the archive that never happened.

Licence

Section titled “Licence”

GPL-3.0-or-later. Versions up to 0.2.0 were MIT and stay MIT. Building from source is free. The signed and notarised build of the same program is pay what you want from €5.

nerln/plancia on GitHub