Context is everything. Share it.
Stop sharing walls of text. Run /planpush and get a visual breakdown — diagrams, tables, flows — your team can actually read, comment on, and stay in sync. Self-hosted and open source.
| Field | Type | Notes |
|---|---|---|
id | uuid | Primary key |
user_id | uuid | FK → users |
token_hash | varchar(64) | SHA-256 of refresh token |
expires_at | timestamptz | 30-day sliding window (UTC) |
device_id | varchar(128) | New — multi-device tracking |
ip_address | inet | New — last known IP |
user_agent | text | New — device fingerprint |
| Field | Type | Notes |
|---|---|---|
id | uuid | Primary key |
client_id | varchar(64) | Public identifier |
client_secret_hash | varchar(64) | bcrypt hash |
redirect_uris | jsonb | Allowed callback URLs |
scopes | text[] | Permitted scope list |
rate_limit | int | Custom req/min (default 60) |
| Field | Type | Notes |
|---|---|---|
id | bigserial | Auto-increment PK |
event_type | varchar(32) | login | logout | token_refresh | revoke |
actor_id | uuid | FK → users (nullable for system) |
ip_address | inet | Request origin |
metadata | jsonb | Event-specific payload |
created_at | timestamptz | Immutable, partitioned by month |
/auth/callback
GitHub OAuth callback
/api/auth/device
Start device flow (CLI)
/api/auth/token
Exchange refresh for access token
/api/auth/me
Current user + active sessions
/api/auth/sessions
Revoke all sessions (new)
/api/auth/sessions/:id
Revoke single device (new)
validateJwt()
Replaces session cookie check (breaking)
rateLimit()
Per-client rate limiting via oauth_clients.rate_limit (new)
/api/webhooks/auth
Receives auth events for downstream propagation (new)
/admin/audit-log
Query audit events (filterable) (new)
/admin/oauth-clients
Register new OAuth client (new)
/admin/users/:id/sessions
Force-logout a user (admin-only) (new)
Pre-built image on Docker Hub (frannsoftdev/planpush), or clone the repo and build locally. Set up auth (a GitHub OAuth App or your Okta OIDC app), configure your .env, and docker compose up. Install the Claude Code plugin.
/planpushHave a planning conversation with Claude, then run the command. It reads your conversation and generates a visual design doc — diagrams, tables, flows — not just a text dump.
Share the URL from your server. Your team sees the live doc, leaves anchored comments, and gets Slack notifications.
Deploy the server, install the plugin, sign in with GitHub or Okta SSO, and push your first design doc.
Setup Guide →Architecture diagrams, data flow charts, API surface tables, UI mockups, decision matrices — all generated as a visual HTML doc. Your team skims structure, not paragraphs. Especially useful for large changes where a wall of text would get ignored.
Run /planpush focus on the data model to shape what gets emphasized. Guide the doc like you'd guide a teammate writing it for you.
Comments attach to specific elements. They survive regeneration and stay relevant as the plan evolves.
New comments, plan updates, and resolved items post to your Slack channel automatically.
Run /planpush again mid-conversation. Only changed sections update — the URL stays the same.
Self-hosted on your own infrastructure. SQLite by default, optional PostgreSQL for remote databases. Deploy with Docker or run directly with Node.js.
Sign in with GitHub (org-membership gated) or your enterprise IdP. Plans stay private to their owner until published, and only authorized users can view them.
Single sign-on via Okta (OpenID Connect). Role-based access — admin, project manager, developer, QA — mapped from your Okta groups and re-synced on every login. SCIM provisioning, single logout, and instant session revocation for clean offboarding.
Sessions, activity feed, comments, and API tokens in one place. Search, filter, and sort — all client-side, no round-trips. Views are role-scoped — admins and project managers see everything; developers and QA see what they own.
Every push is snapshotted. Browse older versions at /p/my-plan?v=2 — each version records who pushed it and when, so you always know where the design has been.
Host it yourself, install the plugin, and your team gets a visual design doc they'll actually read.
❯ git clone https://github.com/Frannsoft/planpush.dev.git
❯ cp .env.example .env # configure auth (GitHub OAuth or Okta SSO)
❯ docker compose up -d
Authentication Flow