ExecOS

ExecOS is an autonomous executive assistant built on Next.js and Clerk auth. It connects Gmail and Google Calendar, analyzes unread email using AI, drafts replies, extracts tasks, and manages a user-facing dashboard for agent activity.

Features

• Clerk-based authentication and user onboarding
• Google OAuth integration for Gmail and Google Calendar
• Autonomous agent that:
  • fetches unread Gmail messages
  • analyzes emails with AI
  • creates Gmail drafts for replies
  • extracts action items as tasks
  • optionally creates Google Calendar events
• User dashboard with agent status, onboarding progress, and recent activity
• Monitoring page with email processing statistics and detail cards
• Drizzle ORM + Neon database schema for users, integrations, tasks, and agent runs
• Encrypted OAuth token storage

Tech stack

• Next.js 16
• React 19
• Clerk for auth
• Drizzle ORM with Neon serverless PostgreSQL
• Google APIs (googleapis) for Gmail and Calendar
• Tailwind CSS / shadcn UI
• Zod for validation patterns
• AES-GCM encryption for sensitive tokens

Project structure

• app/ - Next.js App Router pages and API routes
  • (auth)/ - sign-in / sign-up UI
  • (main)/dashboard, monitoring, settings - protected app pages
  • api/auth/google - Google OAuth initiation route
  • api/auth/google/callback - OAuth callback and token persistence
  • api/agents/run - manual or cron-triggered agent execution
• components/ - shared UI and helper components
• lib/ - core application logic
  • agent.ts - agent run orchestration
  • google.ts - Google OAuth helper
  • google-client.ts - Gmail / Calendar authenticated clients and token refresh
  • db/ - Drizzle database adapter, schema, and queries
  • agents/ - Gmail and calendar integration helpers
  • encryption.ts - token encryption / decryption

Environment setup

Create a .env.local file at the project root with the following values:

DATABASE_URL=postgresql://user:password@host:port/dbname
ENCRYPTION_KEY=your-super-secret-32-byte-key
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
NEXT_PUBLIC_APP_URL=http://localhost:3000
CRON_SECRET=your-cron-secret
CLERK_PUBLISHABLE_KEY=your-clerk-publishable-key
CLERK_SECRET_KEY=your-clerk-secret-key
CLERK_FRONTEND_API=your-clerk-frontend-api

Note: Clerk-specific env variables are required by @clerk/nextjs but are not explicitly referenced in the code snippets. Configure them according to your Clerk application settings.

Google OAuth configuration

1. Create a Google Cloud project.
2. Enable Gmail API and Google Calendar API.
3. Create OAuth 2.0 credentials.
4. Set the authorized redirect URI to:
   • http://localhost:3000/api/auth/google/callback
5. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env.local.

Local development

Install dependencies:

npm install

Run the development server:

npm run dev

Open http://localhost:3000 in your browser.

Database

This app uses Neon/PostgreSQL with Drizzle ORM.

• The database connection is read from DATABASE_URL
• Tables are defined in lib/db/schema.ts
• Sensitive token data is encrypted before storing in integrations

Key pages

• / - Landing page and marketing hero
• /dashboard - Protected dashboard showing agent health and onboarding
• /settings - Integration setup for Gmail and Google Calendar
• /monitoring - Agent processing metrics and email detail view

Agent workflow

1. User connects Gmail and/or Google Calendar via /settings
2. api/agents/run triggers lib/agent.ts
3. The agent:
   • loads Gmail and Calendar clients
   • fetches unread Gmail messages
   • summarizes each email with AI
   • creates reply drafts when needed
   • extracts tasks into the database
   • schedules calendar events if available
   • marks emails as read
4. The agent stores run history in agent_runs

Running the agent

• Manual: click Run Agent Now from the dashboard
• Cron/automatic: configure a scheduler to POST to /api/agents/run

If CRON_SECRET is set, the route will execute the cron-style batch runner for all enabled users.

Scripts

• npm run dev — start development server
• npm run build — compile the app for production
• npm run start — run the production server
• npm run lint — lint the project

Notes

• The app uses encrypted OAuth token storage with ENCRYPTION_KEY.
• The Google callback route stores encrypted tokens via upsertIntegration.
• settings page supports connecting Gmail and Calendar providers.
• monitoring page visualizes processed emails, drafts, and tasks.

Future improvements

• add subscriptions and paid plan enforcement
• improve agent error handling and retry behavior
• add task management UI with complete/incomplete state
• support additional providers beyond Google

License

This repository has no explicit license file. Add one if you plan to publish or share the project.