{"id":50246524,"url":"https://github.com/pariksheet/plannen","last_synced_at":"2026-06-10T12:00:37.870Z","repository":{"id":357450439,"uuid":"1169562629","full_name":"pariksheet/plannen","owner":"pariksheet","description":"Local-first AI planner that learns your preferences and turns events into memories. Your data stays on your machine.","archived":false,"fork":false,"pushed_at":"2026-06-03T08:54:48.000Z","size":4021,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T10:24:19.537Z","etag":null,"topics":["agpl-3","ai-planner","byok","claude","claude-code","event-planner","local-first","mcp","mcp-server","react","supabase","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pariksheet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T21:47:44.000Z","updated_at":"2026-06-03T08:54:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pariksheet/plannen","commit_stats":null,"previous_names":["pariksheet/plannen"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/pariksheet/plannen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pariksheet%2Fplannen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pariksheet%2Fplannen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pariksheet%2Fplannen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pariksheet%2Fplannen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pariksheet","download_url":"https://codeload.github.com/pariksheet/plannen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pariksheet%2Fplannen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34151276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agpl-3","ai-planner","byok","claude","claude-code","event-planner","local-first","mcp","mcp-server","react","supabase","typescript"],"created_at":"2026-05-26T23:15:18.443Z","updated_at":"2026-06-10T12:00:37.847Z","avatar_url":"https://github.com/pariksheet.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"public/logo.svg\" alt=\"Plannen\" width=\"320\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eLocal-first AI planner that learns your preferences and turns events into memories.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-AGPL--3.0-blue.svg\" alt=\"License: AGPL-3.0\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/pariksheet/plannen/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/pariksheet/plannen/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/screenshot-app.png\" alt=\"Plannen calendar view\" width=\"720\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003e… or skip the web app and just talk to Claude.\u003c/sub\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/screenshot-claude.png\" alt=\"Asking Claude Code to find a sailing course for kids\" width=\"720\"\u003e\n\u003c/p\u003e\n\nPlannen 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.\n\n---\n\n## Why it works\n\nTwo pieces do the heavy lifting:\n\n**An MCP server.** Plannen ships an [MCP server](mcp/) 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.\n\n**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\"*.\n\n---\n\n## Deployment modes\n\nPick one at `init` time; switch later by re-running `init`.\n\n| Mode | What it is | When to use |\n|------|------------|-------------|\n| `local_pg` | Embedded Postgres + Plannen's own Hono backend. Node-only, no Docker. | Default. Fastest path; everything on your machine. |\n| `local_sb` | Local Supabase stack (Postgres + Auth + Storage + Edge Functions) via Docker. | You want the full Supabase surface locally. |\n| `cloud_sb` | Supabase Cloud project (DB + Storage + Edge Functions + remote MCP). | You want browser access from anywhere, or to deploy to Vercel. |\n\n## Prerequisites\n\n| Need | For | Install |\n|------|-----|---------|\n| [Node.js](https://nodejs.org/) ≥ 20 LTS | All modes | `brew install node` |\n| [Claude Code](https://claude.com/claude-code) or [Claude Desktop](https://claude.ai/download) | The AI interface | claude.com/claude-code |\n| A container runtime (Docker, [Colima](https://github.com/abiosoft/colima), [OrbStack](https://orbstack.dev)) | `local_sb` only | per-tool docs |\n| [Supabase CLI](https://supabase.com/docs/guides/cli) ≥ 2.0 | `local_sb`, `cloud_sb` | `brew install supabase/tap/supabase` |\n| A [Supabase Cloud](https://supabase.com/dashboard) project + `supabase login` | `cloud_sb` only | dashboard → new project |\n\n---\n\n## Quick start\n\n```bash\ngit clone \u003crepo-url\u003e plannen\ncd plannen\nnpm install\nnpx plannen init --mode=local_pg --email you@example.com\nnpx plannen up\n```\n\nOpen \u003chttp://localhost:4321\u003e. 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).\n\n`init` is idempotent. Re-run any time. If something gets broken, `/plannen-doctor` (inside Claude Code) will diagnose and suggest a fix.\n\nCI flags: `npx plannen init --help`.\n\n## Daily workflow\n\n```bash\nnpx plannen up             # db + backend + web dev\nnpx plannen up --no-dev    # headless: db + backend only (MCP/Claude use case)\nnpx plannen status         # what's running for the active profile\nnpx plannen down           # graceful shutdown\n```\n\nAll sub-steps are idempotent, so re-running on a live stack is a no-op.\n\nFor auto-start at login (macOS LaunchAgent) and per-mode troubleshooting, see [`docs/OPERATIONS.md`](docs/OPERATIONS.md).\n\n### Profiles\n\nA profile is a named bundle of mode + env settings. `plannen init` creates one called `default` and points `\u003crepo\u003e/.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.\n\n```bash\nnpx plannen profile list                              # show all profiles, mark active\nnpx plannen profile create staging --mode=cloud_sb    # second cloud profile\nnpx plannen profile use staging                       # swap the .env symlink\nnpx plannen up --profile=default                      # one-off, doesn't change active\nnpx plannen profile delete staging --yes              # irreversible\n```\n\nProfile state lives under `~/.plannen/profiles/\u003cname\u003e/`. The active pointer is `~/.plannen/active`, or override per-shell with `PLANNEN_PROFILE=\u003cname\u003e`.\n\n---\n\n## Deploying to Vercel (`cloud_sb`)\n\n```bash\nnpm i -g vercel \u0026\u0026 vercel login\nnpx plannen deploy\n```\n\n(`vercel link` is run automatically by `plannen deploy` if `.vercel/` doesn't exist.)\n\nPost-deploy checklist (custom SMTP, custom domain, Google OAuth callback) lives in [`docs/VERCEL.md`](docs/VERCEL.md).\n\n---\n\n## AI provider (web-app features only)\n\nOpen **/settings** and pick one:\n\n- **Claude Code CLI (`local_pg` only).** If `claude` is in your PATH, the backend auto-detects it and routes AI calls through your subscription. No API key required.\n- **Anthropic API key (BYOK).** Paste a key from [console.anthropic.com](https://console.anthropic.com). Stored locally, never leaves your machine. Works on all modes.\n\nSkip this if you only drive Plannen via Claude Code or Claude Desktop — MCP slash commands work without anything in `/settings`.\n\n---\n\n## Slash commands (in Claude Code)\n\nAfter the plugin is installed:\n\n| Command | What it does |\n|---|---|\n| `/plannen-doctor` | Diagnose env, DB, MCP, plugin, AI key, Google keys. |\n| `/plannen-setup` | Re-config `.env` (email, Supabase URL/keys, Google OAuth). |\n| `/plannen-write-story \u003cevent\u003e` | Compose a story from event memories and photos. |\n| `/plannen-organise-photos \u003cevent\u003e` | Drive the Google Photos picker for an event. |\n| `/plannen-discover \u003cquery\u003e` | Find events from saved sources + web search. |\n| `/plannen-check-watches` | Force-process the watch queue now. |\n| `/plannen-backup` | Run `scripts/export-seed.sh`. |\n\nThe plugin also bundles always-on workflow skills (event-creation intent gate, profile extraction, source analysis, etc.) — see [`plugin/skills/`](plugin/skills/).\n\nFor plugin scope (user vs project) and Claude Desktop registration, see [`docs/PLUGIN.md`](docs/PLUGIN.md).\n\n### Connect Plannen to claude.ai (web, Desktop, mobile, Chrome)\n\nTier 2 installs can register the Plannen MCP as a claude.ai custom connector:\n\n1. `npx plannen cloud oauth enable --profile prod` (provision runs this automatically for new installs)\n2. claude.ai → Settings → Connectors → Add custom connector → paste the printed URL\n3. Click Connect — log in with your Plannen account and approve\n\nThe connector then works across claude.ai web, Claude Desktop, mobile, and\nClaude in Chrome. The Claude Code plugin is unaffected — it keeps its\n`plnnn_` token from `plugin.json`.\n\n## MCP server modes\n\n- **stdio (default)** — `mcp/src/` Node process. Used by `local_pg` and `local_sb`.\n- **HTTP (default on `cloud_sb`)** — `supabase/functions/mcp/` Deno Edge Function, personal-access-token auth.\n\nSwitch 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.\n\n## MCP Personal Access Tokens\n\nEach 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.\n\n### Admin / dev (you have DB access)\n\n```bash\nnpx plannen token create --label \"MacBook\"\n```\n\nMints 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.\n\n### Inviting another user (they don't have DB access)\n\n1. Share your deployment's `SUPABASE_URL` + anon key.\n2. They run `npx plannen profile create --mode cloud_sb` and sign in via magic link at the deployment's web URL.\n3. /settings → \"Personal access tokens\" → Generate, save the plaintext.\n4. `npx plannen token activate \u003cPAT\u003e` — wires their plugin.\n\n### Verbs\n\n| Verb | What it does |\n|---|---|\n| `plannen token create --label \u003cname\u003e` | Mint a new PAT, wire it into active profile + plugin.json |\n| `plannen token list` | Show your tokens (no plaintext) |\n| `plannen token revoke \u003cid\u003e` | Revoke a token |\n| `plannen token activate \u003cPAT\u003e` | Wire a PAT from /settings into active profile + plugin.json |\n| `plannen token rotate` | Revoke current PAT, mint a fresh one |\n\n---\n\n## Backups\n\n```bash\nbash scripts/export-seed.sh\n```\n\nWrites `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`.\n\n**Never run `supabase db reset` on `local_sb`** — it wipes the database. Use `supabase migration up` instead.\n\n---\n\n## Optional integrations\n\nGoogle Calendar / Photos / Drive setup (Cloud Console + OAuth callback per mode) is in [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md).\n\n---\n\n## Project layout\n\n```\nplannen/\n├── src/                  # React app (Vite + TypeScript)\n├── mcp/                  # MCP server (pg.Pool + withUserContext)\n├── backend/              # Hono backend (used by local_pg)\n├── plugin/               # Claude Code plugin (skills + commands)\n├── cli/                  # `plannen` CLI (init, up, down, status, profile)\n├── supabase/\n│   ├── migrations/       # Main schema (source of truth)\n│   ├── functions/        # Edge functions\n│   └── seed*.{sql,tar.gz}  # Personal data backups (gitignored)\n├── scripts/              # Lower-level helpers the CLI delegates to\n└── docs/                 # Design docs and architecture notes\n```\n\n---\n\n## Tips\n\nThese aren't Plannen-specific — general practice for anyone using Claude or running a local-first app with personal data.\n\n**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](https://claude.ai/settings/privacy) and turn **\"Help improve Claude\"** off.\n\n**Cap your Anthropic spend.** [console.anthropic.com](https://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.\n\n**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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpariksheet%2Fplannen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpariksheet%2Fplannen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpariksheet%2Fplannen/lists"}