Why This Exists

AICoS - AI Chief of Staff is an operating intelligence workspace for CEOs, founders, operators, and functional leaders. It turns department-level CSV uploads into live dashboards, current Supabase JSONB snapshots, Slack-derived action items, historical trend imports, board memos, and OpenAI-generated recommendations.

The product is designed around a simple idea: every important department should report the metrics a serious CEO would actually inspect, and the Executive dashboard should synthesize those signals into company-level operating judgment.

Product Cards

Core Capabilities

CEO Metrics Philosophy

This is not a generic BI dashboard. It focuses on the metrics CEOs, CFOs, operators, and investors actually care about:

The Executive dashboard intentionally avoids naive technical metrics like row count or column count as core charts. Those are relegated to the data-store table. Executive charts focus on operating outcomes.

Architecture

ai-chief-of-staff/
  frontend/
    app/
      page.js                              # Home command center
      departments/[slug]/page.js           # Department + executive dashboards
      slack/page.js                        # Live Slack workspace UI
      todo/page.js                         # Master To-Do command center
      integrations/page.js                 # Slack integration hub
      assistant/page.js                    # CEO chat over Supabase vector memory
      pipeline/page.js                     # HubSpot CEO deal pipeline
      tickets/page.js                      # Linear CEO ticket overview
      api/
        analytics/[department]/route.js    # Guarded OpenAI recommendations
        ceo-chat/route.js                  # Retrieval planner + CEO answer agent
        embeddings/rebuild/route.js        # Backfill vector memory
        notion/okrs/route.js               # Notion OKR sync and store
        hubspot/deals/route.js             # HubSpot deal pipeline sync and store
        linear/tickets/route.js            # Linear ticket sync and store
        current-data/route.js              # Supabase JSONB current store
        historical-data/route.js           # Historical trend import ledger
        board-memos/route.js               # Board memo persistence
        slack/...                          # Slack OAuth, events, channels
        todo/route.js                      # Master To-Do sync and mutation
    lib/
      current-data-store.js                # Supabase read/write + org rollup
      openai/department-embeddings.js      # OpenAI embeddings + pgvector retrieval
      openai/guardrails.js                 # Enterprise AI guardrails
      slack/server.js                      # Slack OAuth/API helpers
      supabase/server.js                   # Server-side Supabase client

  supabase/
    schema.sql                             # Table creation SQL
    README.md                              # Supabase setup notes

  slack/
    slack-app-manifest.example.json        # Slack app manifest template

  backend/
    main.py                                # FastAPI CSV parsing scaffold

Data Flow

flowchart LR
  A[Department CSV Upload] --> B[Next.js API]
  B --> C[Supabase department_snapshots]
  B --> D[Supabase department_snapshot_history]
  B --> M[Supabase department_embeddings]
  C --> E[Executive Rollup]
  D --> F[Historical Trend Ledger]
  M --> N[CEO Chat Retrieval]
  E --> G[CEO Dashboard]
  G --> H[Guarded OpenAI Synthesis]
  N --> H
  H --> I[PDF Report / Board Memo]
  J[Slack Events API] --> K[Task Harvester]
  K --> L[Master To-Do]

1. A department user downloads a CSV template.
2. The user uploads operating data in that department dashboard.
3. The frontend parses the CSV into records.
4. /api/current-data upserts the current department snapshot.
5. The same upload is appended to the historical import ledger.
6. Executive rollups calculate org-level scorecards.
7. Uploads refresh Supabase vector embeddings for CEO chat retrieval.
8. OpenAI recommendations are generated only on explicit button clicks or chat sends.
9. PDF reports and board memos export from the live dashboard state.
10. Slack events and channel sync harvest commitments into the Master To-Do.

Supabase Data Model

Primary tables:

Run supabase/schema.sql in the Supabase SQL Editor before starting the app. The schema enables pgvector and exposes match_department_embeddings for cosine-similarity search.

Enterprise AI Guardrails

All OpenAI API calls use frontend/lib/openai/guardrails.js.

If a direct request resembles a jailbreak or credential-exfiltration attempt, the API blocks it before it reaches OpenAI.

Slack Integration

This is a real Slack integration, not a simulator.

Create a Slack app using slack/slack-app-manifest.example.json, replacing YOUR_APP_DOMAIN.com with your deployed app domain.

Required Slack URLs:

Redirect URL: https://your-app-domain.com/api/integrations/slack/callback
Events URL:   https://your-app-domain.com/api/slack/events

Required bot scopes:

app_mentions:read
channels:history
channels:join
channels:read
chat:write
chat:write.public
groups:history
groups:read
im:history
im:read
im:write
mpim:history
mpim:read
team:read
users:read

Required bot events:

app_mention
message.channels
message.groups
message.im
message.mpim

After install, open /integrations and connect Slack. Then use /slack for the live workspace view, /todo to sync harvested commitments, and Slack DMs/app mentions to talk to Aegis from inside Slack.

Notion Product OKRs

This is a real Notion integration for Product OKR tracking.

1. Create a Notion internal integration.
2. Copy the integration secret.
3. Share your Product OKR database with that integration.
4. Copy the database ID from the Notion database URL.
5. Add the values in Vercel env vars or connect manually from /integrations.
6. Open /departments/product and click Sync Notion OKRs.

Recommended database properties:

Objective
Key Result
Owner
Status
Progress
Quarter
Due Date
Department
Priority
Confidence

The parser is flexible and also recognizes common variants like Name, KR, DRI, State, % Complete, Cycle, and Target Date.

HubSpot Deal Pipeline

This is a real HubSpot CRM integration for CEO-level deal pipeline tracking.

1. Create a HubSpot Private App.
2. Add CRM read scopes for deals, pipelines, and owners.
3. Copy the Private App access token.
4. Add it in Vercel env vars or connect manually from /integrations.
5. Open /pipeline and click Sync HubSpot Deals.

The pipeline dashboard tracks open pipeline, weighted forecast, next 90-day forecast, stale deals, open deal count, average deal size, pipeline by stage, pipeline by HubSpot pipeline, and top open deals.

Linear Ticket Overview

This is a real Linear integration using Linear's official npm SDK.

1. Create a Linear personal API key from Linear account security settings.
2. Add it in Vercel env vars or connect manually from /integrations.
3. Open /tickets and click Sync Linear Tickets.

The ticket overview tracks open tickets, urgent issues, overdue work, stale execution, completed issues in the last 30 days, average open age, team load, priority mix, and CEO risk queue.

Reports And Board Memos

For the best report, upload department CSVs first and click Fetch Suggestions before exporting.

Environment Variables

Create frontend/.env.local or configure the same variables in Vercel:

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_or_secret_key
NEXT_PUBLIC_APP_URL=https://your-app-domain.com
SLACK_CLIENT_ID=your_slack_client_id
SLACK_CLIENT_SECRET=your_slack_client_secret
SLACK_SIGNING_SECRET=your_slack_signing_secret
NOTION_API_KEY=your_notion_internal_integration_secret
NOTION_OKR_DATABASE_ID=your_product_okr_database_id
HUBSPOT_ACCESS_TOKEN=your_hubspot_private_app_access_token
LINEAR_API_KEY=your_linear_personal_api_key

Do not commit real .env files. They are ignored by .gitignore.

Quick Start

cd frontend
npm install
npm run dev

Open:

Production check:

cd frontend
npm run lint
npm run build

Backend Scaffold

The backend is a FastAPI scaffold for CSV ingestion and validation. The current frontend primarily uses Next.js API routes for Supabase-backed JSONB storage, but the backend is available for future API-backed ingestion.

cd backend
python -m venv venv
source venv/bin/activate
pip install fastapi uvicorn python-multipart
python main.py

Health check:

GET http://127.0.0.1:8000/health

Department Metrics

Executive Dashboard

The Executive dashboard rolls up Supabase department JSON into four CEO scorecards:

The Executive page also includes a metrics glossary so operators can understand what each metric means and how it should be interpreted.

Recommended CEO Workflow

1. Start at the home command center.
2. Visit each department dashboard.
3. Download the department CSV template.
4. Fill it with monthly operating data.
5. Upload the CSV.
6. Confirm charts and KPI cards update.
7. Return to Executive.
8. Review the combined scorecards.
9. Click Fetch Org Suggestions.
10. Open /assistant to ask CEO-level questions grounded in Supabase vector memory.
11. Open /pipeline to sync and inspect the HubSpot deal pipeline.
12. Open /tickets to sync and inspect Linear execution health.
13. Export a PDF report or board memo.
14. Use /todo and /slack to track commitments and follow-ups.

Routes

/                               Home command center
/departments/executive           Executive dashboard
/departments/finance             Finance dashboard
/departments/sales               Sales dashboard
/integrations                    Tool integrations hub
/slack                           Live Slack workspace
/todo                            Master To-Do
/assistant                       CEO chat over Supabase vector memory
/pipeline                        HubSpot CEO deal pipeline
/tickets                         Linear CEO ticket overview
/api/current-data                 Supabase JSONB store
/api/historical-data              Supabase historical import ledger
/api/board-memos                  Supabase board memo storage
/api/analytics/[department]       Guarded OpenAI analysis endpoint
/api/ceo-chat                    Retrieval planner and CEO answer agent
/api/embeddings/rebuild          Supabase vector memory backfill
/api/notion/okrs                 Notion Product OKR sync endpoint
/api/hubspot/deals               HubSpot deal pipeline sync endpoint
/api/linear/tickets              Linear ticket overview sync endpoint
/api/integrations/slack/authorize Slack OAuth start
/api/integrations/slack/callback  Slack OAuth callback
/api/slack/events                 Slack Events API endpoint
/api/slack/channels               Slack conversations.list endpoint

Roadmap

• User authentication and role-based access control
• Department schema validation
• Automated anomaly detection before OpenAI synthesis
• Slack/email action routing to department owners
• Permissioned multi-company workspaces
• Audit log viewer for Slack events, OpenAI calls, and board memo generation

Status

This is a completely open-source, local-first MVP of an AI operating system for company leadership. It is an independent personal project designed to be credible in front of founders, operators, investors, and technical reviewers, while remaining small enough to iterate quickly.

License

MIT License. See LICENSE.