Packages
SmartChats is a monorepo. The app in apps/smartchats is a thin shell:
the voice pipeline, the agent loop, the backend contract and the data layer
live in packages/*. You can build a different shell on these packages, or
use one package on its own (tivi for browser voice, cortex for a
function-calling agent loop).
The MCP server (smartchats-mcp) and the CLI (smartchats-cli) both sit on
smartchats-database for their queries and operations.
By role
Voice (browser):
tivi: React voice hook and settings. Silero VAD, Web Speech recognition, TTS queuevie: turn-taking engine (when a spoken turn is over), self-tuning per device, with a replay harness
Agent runtime:
cortex: agent loop, runners, prompt modules, sandbox interface, model registry, presets, voice catalogllm-service: LLM handlers for OpenAI, Anthropic, Gemini, xAI and Together, NDJSON streaming with TTS, turn verdict, embeddingssmartchats-tools: web search (Serper) and URL text extraction used by the tool routes
Backend:
smartchats-backend: the typed backend contract,AuthProvider, HTTP stream helperssmartchats-backend-local:LocalBackend, the contract againstsmartchats-local-serversmartchats-local-server: self-hosted Express server for the backend, on local SurrealDB with your own keys. See Local serversmartchats-cloud-client: runs query specs against smartchats.ai with a cached Firebase sign-in
Data and sessions:
smartchats-database: SurrealQL query builders, schema, the client, the operations layersmartchats-sessions: session export, per-session analyzers, cross-session triage
Surfaces:
smartchats-cli: thesmartchatscommand. See CLI referencesmartchats-mcp: MCP server for user data (logs, metrics, knowledge graph, todos). See MCP servergraph-viz: React knowledge graph view (sigma.js and graphology)
Agents and relay:
smartchats-hub: per-machine daemon that holds the relay connection and a durable inbox per agent. See Hubsmartchats-mcp-bridge: MCP server that lets a coding agent message the SmartChats usersmartchats-relay: WebSocket relay between bridges and browser clients. See Relaysmartchats-relay-protocol: the relay wire protocol, envelope and validatorssmartchats-relay-connect: outbound bridge connection helper (auth, reconnect, reauth)
Shared:
smartchats-common: logger, helpers, sounds, insights client andcreateInsightStoresimi: declarative in-app test workflows
Internal tooling
These are for working on SmartChats itself. They are not meant to be used as libraries.
| Package | What it is |
|---|---|
benchpress | Scripted end-to-end benchmark of the agent against real models (private) |
llmbench | LLM streaming latency and cost benchmark across providers (private) |
voicebench | Streaming TTS latency and cost benchmark (private) |
smartchats-test | Layered test runner: lint, build, unit, integration, e2e (private) |
smartchats-tunnel | Fly.io SSH bastion for reaching a dev server from another machine (private) |
smartchats-relay-cf | Cloudflare Workers and Durable Objects port of the relay (private) |
smartchats-docs-canary | A design document only, not implemented and no package.json |
sail-dsp | Rust and WASM audio DSP for the app’s /sail audio lab. Not marked private, but an early proof of concept used only there |
When to use a package directly
- Voice input in another React app:
tivi. - A browser function-calling agent without the SmartChats UI:
cortex. - Server-side LLM calls with the same routing and streaming:
llm-service. - Reading SmartChats session data from a script:
smartchats-sessions. - Talking to a SmartChats database from your own code:
smartchats-databasewith aClientfrom your backend.
If you only run SmartChats as a user, you don’t need the packages. The app composes them.