Ir al contenido
nerln docs

Plancia

Esta página aún no está disponible en tu idioma.

Claude Code and Codex already write down everything they do, in files on your disk, in different folders and different formats, and neither one reads the other. Plancia reads both and shows the open tasks from each on one board. It also produces a spoken recap of the day, and sends work back to either agent.

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=…); seven plancia_* MCP tools in Claude Code and Codex, and a SessionStart hook in Claude Code; the terminal.

The MCP surface is kept small on purpose. Tool schemas are paid for in every request of a session, so the six tools that get used stay exposed and the rest sit behind one plancia tool called with azione. That costs 1195 tokens per Claude Code session and 1020 per Codex session, down from 2870 and 2196.

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 138 checks in about twenty 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.github.io/plancia
nerln/plancia on GitHub