Plannen — Planejador IA Local-First
pariksheet/plannen
Planejador IA que aprende suas preferências e vive no seu computador
Ver no GitHubMCP server que expõe um planejador inteligente com armazenamento local e aprendizado de preferências. Integra-se ao Claude Desktop e Claude Code para acessar eventos, perfil pessoal e histórico de forma persistente, sem enviar dados para a nuvem.
Instalação
npx convez-ai pariksheet/plannen1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Planejar eventos e atividades personalizadas com histórico de preferências familiares
- Integrar agenda inteligente ao Claude Desktop com contexto persistente
- Transformar eventos em memórias e narrativas com aprendizado contínuo
Veredito

MCP server bem arquitetado que leva a sério privacidade e aprendizado contextual. A abordagem local-first é rara e valiosa; o design de perfil que extrai fatos naturalmente é inovador. Recomendado para quem valoriza controle de dados e planejamento personalizado.
README
A tradução para o português deste README ainda está na fila.
Plannen is a local-first AI planner. It knows your preferences and past events, helps you schedule what's next, and turns memorable moments into stories. Use it through the web app, or just talk to it from Claude Code or Claude Desktop — both surfaces drive the same database via an MCP server.
Why it works
Two pieces do the heavy lifting:
An MCP server. Plannen ships an MCP server that exposes its data layer — events, profile facts, family members, locations, sources, stories — as tools Claude Code and Claude Desktop can call directly. You don't talk to a bespoke chatbot; you talk to Claude in whatever client you already use, and Claude reaches into Plannen via MCP. The web app uses the same service functions, so the two surfaces stay in lockstep.
A profile that learns. Every time you mention something durable about yourself or your family in natural conversation — "my son just turned 6", "we prefer apartments over hotels", "no highway charging when the kids are in the car" — Plannen passively extracts the fact and saves it. The next time Claude plans something, it knows. Suggestions become personal: "his school finishes Wednesday at 12:00, want a sports option that runs 13:00–15:00?" rather than generic "here are some sports classes in Belgium".
Deployment modes
Pick one at init time; switch later by re-running init.
| Mode | What it is | When to use |
|---|---|---|
local_pg | Embedded Postgres + Plannen's own Hono backend. Node-only, no Docker. | Default. Fastest path; everything on your machine. |
local_sb | Local Supabase stack (Postgres + Auth + Storage + Edge Functions) via Docker. | You want the full Supabase surface locally. |
cloud_sb | Supabase Cloud project (DB + Storage + Edge Functions + remote MCP). | You want browser access from anywhere, or to deploy to Vercel. |
Prerequisites
| Need | For | Install |
|---|---|---|
| Node.js ≥ 20 LTS | All modes | brew install node |
| Claude Code or Claude Desktop | The AI interface | claude.com/claude-code |
| A container runtime (Docker, Colima, OrbStack) | local_sb only | per-tool docs |
| Supabase CLI ≥ 2.0 | local_sb, cloud_sb | brew install supabase/tap/supabase |
A Supabase Cloud project + supabase login | cloud_sb only | dashboard → new project |
Quick start
git clone <repo-url> plannen
cd plannen
npm install
npx plannen init --mode=local_pg --email you@example.com
npx plannen up
Open http://localhost:4321. For the other modes, swap --mode=local_sb or --mode=cloud_sb (the cloud variant is interactive — it picks your project and asks for the DB password).
init is idempotent. Re-run any time. If something gets broken, /plannen-doctor (inside Claude Code) will diagnose and suggest a fix.
CI flags: npx plannen init --help.
Daily workflow
npx plannen up # db + backend + web dev
npx plannen up --no-dev # headless: db + backend only (MCP/Claude use case)
npx plannen status # what's running for the active profile
npx plannen down # graceful shutdown
All sub-steps are idempotent, so re-running on a live stack is a no-op.
For auto-start at login (macOS LaunchAgent) and per-mode troubleshooting, see docs/OPERATIONS.md.
Profiles
A profile is a named bundle of mode + env settings. plannen init creates one called default and points <repo>/.env at it via symlink. You only need extra profiles when you want to run a second environment (e.g. a staging cloud setup) alongside your daily one.
npx plannen profile list # show all profiles, mark active
npx plannen profile create staging --mode=cloud_sb # second cloud profile
npx plannen profile use staging # swap the .env symlink
npx plannen up --profile=default # one-off, doesn't change active
npx plannen profile delete staging --yes # irreversible
Profile state lives under ~/.plannen/profiles/<name>/. The active pointer is ~/.plannen/active, or override per-shell with PLANNEN_PROFILE=<name>.
Deploying to Vercel (cloud_sb)
npm i -g vercel && vercel login
npx plannen deploy
(vercel link is run automatically by plannen deploy if .vercel/ doesn't exist.)
Post-deploy checklist (custom SMTP, custom domain, Google OAuth callback) lives in docs/VERCEL.md.
AI provider (web-app features only)
Open /settings and pick one:
- Claude Code CLI (
local_pgonly). Ifclaudeis in your PATH, the backend auto-detects it and routes AI calls through your subscription. No API key required. - Anthropic API key (BYOK). Paste a key from console.anthropic.com. Stored locally, never leaves your machine. Works on all modes.
Skip this if you only drive Plannen via Claude Code or Claude Desktop — MCP slash commands work without anything in /settings.
Slash commands (in Claude Code)
After the plugin is installed:
| Command | What it does |
|---|---|
/plannen-doctor | Diagnose env, DB, MCP, plugin, AI key, Google keys. |
/plannen-setup | Re-config .env (email, Supabase URL/keys, Google OAuth). |
/plannen-write-story <event> | Compose a story from event memories and photos. |
/plannen-organise-photos <event> | Drive the Google Photos picker for an event. |
/plannen-discover <query> | Find events from saved sources + web search. |
/plannen-check-watches | Force-process the watch queue now. |
/plannen-backup | Run scripts/export-seed.sh. |
The plugin also bundles always-on workflow skills (event-creation intent gate, profile extraction, source analysis, etc.) — see plugin/skills/.
For plugin scope (user vs project) and Claude Desktop registration, see docs/PLUGIN.md.
Connect Plannen to claude.ai (web, Desktop, mobile, Chrome)
Tier 2 installs can register the Plannen MCP as a claude.ai custom connector:
npx plannen cloud oauth enable --profile prod(provision runs this automatically for new installs)- claude.ai → Settings → Connectors → Add custom connector → paste the printed URL
- Click Connect — log in with your Plannen account and approve
The connector then works across claude.ai web, Claude Desktop, mobile, and
Claude in Chrome. The Claude Code plugin is unaffected — it keeps its
plnnn_ token from plugin.json.
MCP server modes
- stdio (default) —
mcp/src/Node process. Used bylocal_pgandlocal_sb. - HTTP (default on
cloud_sb) —supabase/functions/mcp/Deno Edge Function, personal-access-token auth.
Switch with bash scripts/mcp-mode.sh stdio|http. The HTTP MCP does not include transcribe_memory (needs local Whisper). Use stdio if you need audio transcription.
MCP Personal Access Tokens
Each user has their own PAT — like a GitHub PAT, but for Plannen. PATs scope every MCP call to the issuing user; RLS handles the rest.
Admin / dev (you have DB access)
npx plannen token create --label "MacBook"
Mints a plnnn_… token, writes it to your active profile's env, and rewires plugin/.claude-plugin/plugin.json. Reload the plannen plugin in Claude Code.
Inviting another user (they don't have DB access)
- Share your deployment's
SUPABASE_URL+ anon key. - They run
npx plannen profile create --mode cloud_sband sign in via magic link at the deployment's web URL. - /settings → "Personal access tokens" → Generate, save the plaintext.
npx plannen token activate <PAT>— wires their plugin.
Verbs
| Verb | What it does |
|---|---|
plannen token create --label <name> | Mint a new PAT, wire it into active profile + plugin.json |
plannen token list | Show your tokens (no plaintext) |
plannen token revoke <id> | Revoke a token |
plannen token activate <PAT> | Wire a PAT from /settings into active profile + plugin.json |
plannen token rotate | Revoke current PAT, mint a fresh one |
Backups
bash scripts/export-seed.sh
Writes supabase/seed.sql + supabase/seed-photos.tar.gz (both gitignored). To restore: drop both into supabase/, run npx plannen init again, then bash scripts/restore-photos.sh.
Never run supabase db reset on local_sb — it wipes the database. Use supabase migration up instead.
Optional integrations
Google Calendar / Photos / Drive setup (Cloud Console + OAuth callback per mode) is in docs/INTEGRATIONS.md.
Project layout
plannen/
├── src/ # React app (Vite + TypeScript)
├── mcp/ # MCP server (pg.Pool + withUserContext)
├── backend/ # Hono backend (used by local_pg)
├── plugin/ # Claude Code plugin (skills + commands)
├── cli/ # `plannen` CLI (init, up, down, status, profile)
├── supabase/
│ ├── migrations/ # Main schema (source of truth)
│ ├── functions/ # Edge functions
│ └── seed*.{sql,tar.gz} # Personal data backups (gitignored)
├── scripts/ # Lower-level helpers the CLI delegates to
└── docs/ # Design docs and architecture notes
Tips
These aren't Plannen-specific — general practice for anyone using Claude or running a local-first app with personal data.
Don't share your Claude sessions for model training. API keys are excluded by Anthropic's commercial policy. If you sign Claude Code into a claude.ai subscription instead, open claude.ai/settings/privacy and turn "Help improve Claude" off.
Cap your Anthropic spend. console.anthropic.com → Workspaces → create one → set a monthly spend limit → generate a key scoped to that workspace. If a key leaks, blast radius is bounded.
Back up your data. bash scripts/export-seed.sh writes the two seed files; copy them somewhere safe. Encrypt if you upload to a cloud provider.