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)
- Push the repo to GitHub
- Import the project on vercel.com/new
- 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 |
CALENDAR_SYNC_ALLOWED_USERS |
No | Comma-separated emails allowed to connect, for testing before Google verifies your OAuth app. Unset = everyone |
- 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.
