Grasshopper

Open-source mentoring platform for tech & design professionals.

Why Grasshopper

Existing mentoring platforms are either overwhelming (38K+ unvetted mentors), expensive ($150–360/month), or lack purpose beyond a single call. Grasshopper exists because mentoring should be free, intentional, and beautiful.

Free forever. Mentors volunteer their time. No paywalls, no premium tiers.
Purposeful. Sessions are tied to goals, not isolated events.
Minimal. Every feature earns its place. No bloat.

Core Features

1. Mentor Profiles + Discovery

Browse mentors by expertise, experience level, and availability. Profiles are minimal: who you are, what you know, when you're free.

2. Session Booking + Shared Notes

Book 1:1 sessions with a mentor. Each session has collaborative notes that persist — creating continuity across conversations.

3. Goal-based Progress Tracking (opt-in module)

Mentees define goals. Sessions link to goals. Progress is visible over time. This turns one-off calls into a journey.

Architecture

Grasshopper is modular by design:

• Core — Profiles + Booking (ships with every instance)
• Modules — Notes, Goals (opt-in, activated per mentoring pair)

Each module is self-contained. The platform works without modules enabled; modules enhance committed mentoring relationships.

Auth

Passwordless by design — sign in with GitHub, Google, or a passkey. No passwords, no resets, no credential stuffing. See ADR-0002.

Status

🦗 Beta — Feature-complete, hardening.

Tech Stack

Next.js 16 · TypeScript · Tailwind CSS v4 · Drizzle ORM · PostgreSQL · Better Auth · Phosphor Icons · shadcn/ui

Getting Started

One-click (Codespaces / Dev Container)

Open in Codespaces, or locally with VS Code + Docker via Reopen in Container. The dev container installs deps, starts PostgreSQL, applies the schema, and seeds mentors. Then run pnpm dev and visit http://localhost:3000 — hot reload included.

Manual

# Prerequisites: Node.js 22+, pnpm, Docker

pnpm install
cp .env.example .env.local    # Then fill in BETTER_AUTH_SECRET
docker compose up -d          # Starts PostgreSQL
pnpm db:push                  # Apply schema to DB
pnpm db:seed                  # Optional: populate sample mentors
pnpm dev                      # http://localhost:3000

See ENGINEERING.md for architecture guidance and DESIGN.md for visual direction.

Deployment

Vercel (recommended)

1. Push the repo to GitHub
2. Import the project on vercel.com/new
3. Set these environment variables:

Variable	Required	Notes
DATABASE_URL	Yes	PostgreSQL connection string (Neon, Supabase, Railway, etc.)
BETTER_AUTH_SECRET	Yes	openssl rand -base64 32
BETTER_AUTH_URL	Yes	Your production URL (e.g. https://www.grsshppr.org)
GITHUB_CLIENT_ID	No	GitHub OAuth app ID
GITHUB_CLIENT_SECRET	No	GitHub OAuth app secret
GOOGLE_CLIENT_ID	No	Google OAuth client ID
GOOGLE_CLIENT_SECRET	No	Google OAuth client secret
RESEND_API_KEY	No	Resend API key for transactional emails. Without it in production no email is sent (feedback prompts stay in-app only)
CRON_SECRET	Yes, for scheduled jobs	Shared secret Vercel sends to the cron endpoints (openssl rand -hex 32). Without it the jobs refuse every call and never run
CALENDAR_SYNC_ENABLED	No	true turns on Google Calendar sync (RFC-0012). Off unless this and the three below are all set
GOOGLE_CALENDAR_CLIENT_ID	With sync	OAuth client for the calendar connection (can be the same Google project as sign-in). Redirect URI: ${BETTER_AUTH_URL}/api/calendar/callback/google
GOOGLE_CALENDAR_CLIENT_SECRET	With sync	Its secret
CALENDAR_TOKEN_ENC_KEY	With sync	Encrypts stored Google tokens: 32 bytes, openssl rand -base64 32. A malformed key stops sync loudly. Keep it: losing it means everyone must reconnect
CALENDAR_TOKEN_ENC_KEY_PREVIOUS	No	The old key during a rotation (decrypt only); tokens move to the new key as they're used

4. Deploy — Vercel auto-detects Next.js

After first deploy, run pnpm db:migrate against your production database to apply committed migrations. Never use db:push against production — see ADR-0003. To apply migrations automatically on every merge, set the MIGRATION_DATABASE_URL secret for the DB Migrate GitHub Action (.github/workflows/db-migrate.yml).

Scheduled jobs (vercel.json, once a day on Vercel's Hobby plan):

Job	When (UTC)	What it does
/api/sessions/auto-complete	00:00	Marks confirmed sessions that ended over 24h ago as completed
/api/feedback/nudge	09:00	Sends each participant of a recently completed session one feedback prompt — in-app and by email — at most once (ADR-0017)
/api/calendar/drain	03:00	Backstop for Google Calendar sync: pushes any session changes the instant sync didn't finish (retries, outages). A no-op unless calendar sync is on

All require CRON_SECRET and are safe to run again by hand (GET or POST with Authorization: Bearer $CRON_SECRET).

Self-Hosting (Docker)

# Build and run with Docker Compose
BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
  docker compose -f docker-compose.prod.yml up -d --build

# Apply migrations to the database
docker compose -f docker-compose.prod.yml exec app \
  npx drizzle-kit migrate

The app runs on http://localhost:3000. See Dockerfile for the multi-stage build.

Docker has no scheduler: call the jobs above once a day from your host's cron, e.g. curl -fsS -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/calendar/drain.

Contributing

• Get the code — clone or fork the repo; see Getting Started above for local setup.
• Report a bug — open an issue using the bug template. Bugs are auto-escalated for triage and ownership by @natos.
• Request a feature — open a feature issue or start a Discussion.
• Contribute — read CONTRIBUTING.md for setup, conventions, PR guidelines, and the current feedback workflow.
• Response target — we aim to acknowledge new issues within two weeks, with urgent regressions handled faster when the impact is clear.

AI agents: read AGENTS.md for how to operate (RFCs, ADRs, traceability) and ENGINEERING.md before writing any code.

Working in the Open

Grasshopper is a fully open product — not just open source. Code, specs, design, decisions, and roadmap are all public.

• Roadmap — product/roadmap (now / next / later)
• Propose a change — RFCs for anything major
• Why things are the way they are — decisions (ADRs)
• Who decides — governance
• How humans + agents operate — AGENTS.md

Contributions are welcome across every layer — product, design, and engineering.

Contributors

Built in collaboration with Claude — an AI pair-programming partner that helped architect, code, and refine Grasshopper from first commit to beta.

License

MIT