Getting started
Sign in, connect Google, and open your first inbox
Prerequisites
You need a Google account with Gmail and Google Calendar. For hackathon/demo environments, your email must be added as a Test user on the Google OAuth app (Testing mode).
Step 1 — Open the app
Go to command-inbox.sayantanbal.in (or your self-hosted URL).
You land on the sign-in page if you are not authenticated.
Step 2 — Sign in with Google
- Click Sign in with Google
- Choose your Google account
- Grant the requested permissions for the app sign-in flow
This creates your user record and Better Auth session. You are not yet connected to Gmail/Calendar for inbox operations.
Step 3 — Connect Google (Gmail + Calendar)
After sign-in you are redirected to Connect Google (/onboarding/connect).
- Click Connect Gmail
- Complete Google OAuth for Gmail scopes
- If prompted, complete the chained OAuth for Google Calendar
Both integrations must show as connected before the inbox loads.
Step 4 — Wait for indexing
On first connect, Command Inbox runs a two-phase index:
- Immediate — classifies your latest ~50 INBOX threads so lanes are usable within about a minute
- Background — continues indexing your full INBOX into semantic search (progress banner on
/inbox)
Semantic search (/) improves as more threads are indexed. Advanced search (Mod+Shift+F) queries Gmail directly via Corsair anytime — no index required.
This usually takes under a minute for lanes; full inbox indexing may run longer depending on mailbox size and AI latency.
Step 5 — Explore the inbox
Once on /inbox:
| Area | What you see |
|---|---|
| Left | Lane tabs — Reply, Schedule, FYI, Done |
| Center | Thread list for the active lane |
| Right | Selected thread + week-strip calendar |
| Bottom-right | Agent chat panel (toggle in header) |
Use J and K to move between threads. Press ? for the full shortcut cheat sheet.
Step 6 — Try the hero workflow
- Open a thread in the Schedule lane (or any email mentioning meeting times)
- Press
M - Review extracted attendees and proposed times
- Click an available slot
- Confirm — calendar invite sends and a confirmation draft appears in the composer
Visual walkthrough
Screenshots and a hero GIF are hosted on the production app (add before final submission):
| Asset | Path |
|---|---|
Hero M workflow (GIF) | /demo/hero.gif |
| Inbox triage lanes | /demo/inbox-triage.png |
| Agent approval UI | /demo/agent-approval.png |
| Mobile navigation | /demo/mobile-drawer.png |
See public/demo/README.md in the repo for capture dimensions.
AI provider switcher
In the inbox header, you can switch between OpenAI and Gemini. This affects classification, drafts, search embeddings, and the agent.
Switching embedding provider starts a re-embed job (banner shows progress). Semantic search works best after re-embed completes.
Troubleshooting first run
| Issue | What to do |
|---|---|
| Redirect loop on sign-in | Check OAuth redirect URIs match your app URL |
| "Google not connected" | Finish both Gmail and Calendar on onboarding |
| Empty lanes after connect | Wait for backfill; refresh after ~30s |
| AI features unavailable | App needs at least one AI API key configured server-side |
For self-hosters, see Local development.