Convex + Subconscious: Full-Stack Real-Time AI Apps

Build production apps where AI agents modify data in real-time and every connected client sees changes instantly — no polling, no manual WebSocket management, no cache invalidation.

Mental Model

Subconscious runs AI agents. Give it instructions + tools, it reasons, calls your tools, returns results. The "function tool" pattern hooks your Convex HTTP endpoints into the agent — Subconscious POSTs to your endpoint, which writes to Convex DB, which instantly pushes updates to all clients via WebSocket.

Convex is a reactive database + serverless backend. Queries are read-only and reactive (auto-push via WebSocket). Mutations are transactional writes. HTTP actions expose public endpoints at https://<deployment>.convex.site. Actions call external APIs.

The Reactive Loop (Core Pattern)

1. React calls useAction(api.agent.triggerAgent) → starts Subconscious run
2. Subconscious agent reasons, calls POST /tools/create-item
3. Convex HTTP action calls ctx.runMutation(internal.items.create, ...)
4. Convex DB writes → invalidates all subscriptions to items.list
5. All clients subscribed via useQuery(api.items.list) re-render instantly

No polling. No manual WebSocket management. No cache invalidation.

Architecture Overview

React App (Vite or Next.js)
  ├── ConvexProvider or ConvexAuthNextjsProvider
  ├── useQuery (reactive data — auto-updates)
  ├── useAction (triggers Subconscious via Convex action)
  └── useMutation (direct writes)
          ↓
Convex Backend (real-time database + functions)
  ├── Queries (reactive, cached, read-only)
  ├── Mutations / internalMutations (transactional writes)
  ├── Actions (side effects — call Subconscious SDK)
  └── HTTP Actions (tool endpoints for Subconscious agent)
          ↓
Subconscious AI Agent (tim-gpt / tim-edge / tim-gpt-heavy)
  ├── Calls Convex HTTP endpoints as tools
  ├── Uses platform tools (web_search, news_search, etc.)
  ├── Connects to MCP servers for external integrations
  ├── Loads skills for specialized knowledge
  └── Returns structured answers or calls webhook

Quick Setup

Option A: Use the Official Template (Fastest)

npx create-subconscious-app my-app --example convex_realtime

This scaffolds a working Convex + Subconscious app with real-time updates, tool calling, and a React frontend.

Option B: Manual Setup

npm install subconscious convex
npx convex dev   # initializes project, writes CONVEX_DEPLOYMENT to .env.local

Set the Subconscious API key in your Convex deployment (not .env.local):

npx convex env set SUBCONSCIOUS_API_KEY your_api_key_here
npx convex env list  # verify

Frontend .env.local needs only VITE_CONVEX_URL or NEXT_PUBLIC_CONVEX_URL (auto-set by npx convex dev).

Install This Skill for AI Coding Assistants

npx skills add https://github.com/subconscious-systems/skills --skill convex-subconscious

2. Required Files

File	Purpose
`convex/schema.ts`	DB schema with tables and indexes
`convex/http.ts`	HTTP router (tool endpoints + webhooks)
`convex/items.ts`	Queries + internal mutations for data
`convex/agentRuns.ts`	Agent run tracking (queries + mutations)
`convex/agent.ts`	Convex action that calls Subconscious SDK
`src/main.tsx`	ConvexProvider wrapper
`src/App.tsx`	useQuery / useAction hooks

For Next.js with auth, also see references/auth-nextjs.md for the additional auth files.

3. Environment Variables

Convex deployment (set via npx convex env set):

SUBCONSCIOUS_API_KEY — For AI agent calls
CONVEX_SITE_URL — Built-in, auto-set (do NOT set manually)

For Next.js auth (additional):

JWT_PRIVATE_KEY, JWKS, SITE_URL — See references/auth-nextjs.md

.env.local (frontend):

VITE_CONVEX_URL or NEXT_PUBLIC_CONVEX_URL — Auto-set by npx convex dev

Key Patterns

Triggering Agents from Convex

See references/agent-from-convex.md for the complete pattern: Convex actions calling Subconscious SDK, async runs with webhook callbacks, agent run tracking, and structured output with Zod.

HTTP Tool Endpoints

See references/subconscious-integration.md for HTTP action patterns, CORS helpers, tool schema requirements (CRITICAL: additionalProperties: false), webhook endpoints, MCP tools, tool headers, and the defaults pattern.

Real-Time Data

See references/realtime-patterns.md for schema design, query/mutation patterns, reactive UI with useQuery/useAction, Vite and Next.js provider setup, and optimistic updates.

Auth Setup (Next.js Only)

See references/auth-nextjs.md for Convex Auth with Password provider, JWT key generation, middleware, and all required auth files.

Common Pitfalls

See references/common-pitfalls.md for every bug encountered with solutions.

Critical Rules

additionalProperties: false — ALL Subconscious tool parameter schemas MUST include this. Without it, the agent gets stuck in a "Tinkering" loop.
HTTP actions use ctx.runMutation — They cannot use ctx.db directly. Use internal.* for mutations you don't want exposed as public API.
Actions (not mutations) call external APIs. Mutations are pure DB operations. Calling Subconscious must be inside an action or internalAction.
process.env.CONVEX_SITE_URL is always available in Convex functions — use it to construct tool callback URLs.
HTTP tool body format — Subconscious sends tool parameters directly in the POST body (e.g. { name: "test" }). Read params from the top-level body in your HTTP action.
Auth on AI-called mutations — Mutations called by Subconscious via HTTP tool routes don't have user auth context. Enforce auth upstream (in the action that triggers the AI), keep the mutations themselves permissive. Use internalMutation to prevent direct client calls.
defaults field — Values in defaults MUST be defined in parameters.properties and should NOT be in the required array.
For Next.js auth: Middleware MUST be at src/middleware.ts (not project root) if using src/ directory. Need BOTH ConvexAuthNextjsServerProvider (layout.tsx) AND ConvexAuthNextjsProvider (client provider). Requires convex/auth.config.ts or isAuthenticated is always false.

Available Engines

Engine	API Name	Type	Best For
TIM	`tim`	Unified	Flagship unified agent for a wide range of tasks
TIM-Edge	`tim-edge`	Unified	Speed, efficiency, search-heavy tasks
TIMINI	`timini`	Compound (Gemini-3 Flash)	Long-context and tool use, strong reasoning
TIM-GPT	`tim-gpt`	Compound (GPT-4.1)	Most use cases, good balance of cost/performance
TIM-GPT-Heavy	`tim-gpt-heavy`	Compound (GPT-5.2)	Maximum capability, complex reasoning

Recommendation: Start with tim-gpt for most applications.

File Structure

my-app/
├── convex/
│   ├── schema.ts          # DB schema
│   ├── http.ts            # HTTP actions (tool endpoints + webhooks)
│   ├── items.ts           # queries + internal mutations for items
│   ├── agentRuns.ts       # queries + internal mutations for run tracking
│   └── agent.ts           # Convex action that calls Subconscious
├── src/
│   ├── main.tsx           # ConvexProvider wrapper
│   └── App.tsx            # useQuery / useAction hooks
├── .env.local             # VITE_CONVEX_URL (written by npx convex dev)
└── package.json

The SUBCONSCIOUS_API_KEY lives in Convex deployment env vars (set via CLI), not in .env.local. Frontend never sees it.

convex-subconscious