Get Started

Pre-built image: frannsoftdev/planpush

Create a GitHub OAuth App

Go to your GitHub org's Settings → Developer settings → OAuth Apps → New OAuth App and create one:

• Homepage URL: http://localhost:3000 (or your production domain)
• Authorization callback URL: http://localhost:3000/auth/callback

Copy the Client ID and generate a Client Secret.

Configure environment

Create a .env file with the required values:

Enterprise SSO with Okta (optional)

For org-wide single sign-on, use Okta (OpenID Connect) instead of GitHub. In the Okta admin console, create an OIDC — Web Application with:

• Sign-in redirect URI: {BASE_URL}/auth/callback
• Initiate login URI: {BASE_URL}/auth/initiate_login_uri (enables the Okta dashboard tile)
• Sign-out redirect URI: {BASE_URL}
• Add a groups claim to the ID token so PlanPush can map Okta groups to roles

Then set these in your .env (in place of the GitHub vars):

Sign in once as a bootstrap admin, then map your Okta groups to roles (admin / project manager / developer / QA) from the dashboard. For group → role mapping, SCIM auto-provisioning/deprovisioning, and single logout, see the SSO docs.

Option A: Docker Hub image (quickest)

Pull the pre-built image and run it directly — no need to clone the repo:

> docker run -d --name planpush \
    -p 3000:3000 \
    -v planpush-data:/app/data \
    --env-file .env \
    --restart unless-stopped \
    frannsoftdev/planpush:latest

Data (SQLite DB) is persisted in a Docker volume (planpush-data). Migrations run automatically on startup.

Option B: Clone + Docker Compose

Clone the repo if you want the .env.example template, docker-compose.yml, or want to build from source:

> git clone https://github.com/Frannsoft/planpush.dev.git
> cd planpush.dev
> cp .env.example .env  # edit with your values
> docker compose up -d

Production deployment

For production, put a reverse proxy (nginx, Caddy, Traefik) in front for HTTPS. Make sure to:

• Set BASE_URL to your public domain (e.g. https://planpush.example.com)
• Update the GitHub OAuth App callback URL to match
• Back up the planpush-data Docker volume for your SQLite database

Add the marketplace source

In Claude Code, add the PlanPush marketplace:

> /plugin marketplace add Frannsoft/planpush.dev

Install the plugin

Then install the planpush plugin from the marketplace:

> /plugin install planpush@planpush

Verify

Type /planpush in Claude Code — you should see the command autocomplete. If not, restart Claude Code.

Have a planning conversation

Talk through your architecture, data models, API design, or UI flows with Claude like you normally would. The richer the conversation, the better the design doc.

Run /planpush

> /planpush

First-run authentication

On your first run, /planpush will start a device flow to authenticate with your server — similar to how GitHub CLI and Vercel CLI work. You'll see a URL and a one-time code:

Open this URL and enter the code below:
  URL:  https://your-server.example/activate
  Code: ABCD-1234

✓ Authenticated as you (your-org)

Open the URL, sign in with your provider (GitHub or Okta SSO), and enter the code. Your credentials are stored locally — subsequent runs skip straight to generating the doc.

You can also pass editorial direction:

> /planpush focus on the data model

Share the link

You'll get a URL back instantly. Share it with your team — they can view the design doc, leave comments on specific sections, and get Slack notifications as the plan evolves.

✓ Plan pushed successfully.

  URL: https://your-server.example/p/a3f8c1

  Share this link with your team.