The stack behind Smoo AI, open sourced
Not a pile of side projects — the actual layers we run. The smooth-operator agent core, the embeddable chat widget, the th CLI, and the config, logging, observability, and schema libraries our platform is built on. Rust at the core, native clients in TypeScript, Python, Go, and .NET.
The agent stack
One engine, from the core to the widget
Smoo AI is agents. This is the open-source spine that makes them run — a polyglot core, the service that wraps it, the widget that embeds it, and the CLI that ships it.
Key Features:
- Agents, workflows, and a tool system with pre/post hooks
- Durable checkpointing + resumable turns
- Confirm-before-write human-in-the-loop, modeled in the core
- Per-turn cost + token accounting
- One graph, five languages — Rust reference, native bindings
Quick Example:
use smooai_smooth_operator_core::{Agent, Model};
// Define an agent: a model, a system prompt, and typed tools.
let agent = Agent::builder()
.model(Model::new("claude-sonnet-5"))
.system("You are a helpful assistant.")
.tool(weather_tool)
.build();
// Run a turn and stream it, token by token.
let mut turn = agent.run("What's the weather in Denver?").await?;
while let Some(event) = turn.next().await {
if let Event::Token(t) = event {
print!("{t}");
}
}Key Features:
- Schema-driven WebSocket protocol — one language-neutral contract
- Real streaming clients in 5 languages, not thin REST wrappers
- Knowledge grounding with citations (pgvector or S3 Vectors)
- Checkpointing, memory, and resumable turns
- Deploy to Kubernetes, AWS serverless, or run locally
Quick Example:
import { SmoothAgentClient } from '@smooai/smooth-operator';
const client = new SmoothAgentClient({ url: 'wss://your-host/ws' });
await client.connect();
const { sessionId } = await client.createConversationSession({ agentId });
// Stream the agent's reply, token by token.
for await (const event of client.sendMessage({ sessionId, message: 'Hi!', stream: true })) {
if (event.type === 'stream_token') process.stdout.write(event.token ?? '');
}Installation:
pnpm add @smooai/smooth-operatorThe embeddable end of the stack: a framework-light <smooth-agent-chat> web component that speaks the smooth-operator protocol. One script tag, streaming replies, grounded sources, popover or full-page — and it inherits your brand color from a single accent. We dogfood it across Smoo AI.
Same component · three brands · live
The real component, streaming right on this page — each one the same code themed from a single color.
<!-- one script tag, then the element -->
<script src="https://unpkg.com/@smooai/chat-widget/dist/chat-widget.global.js"></script>
<smooth-agent-chat
endpoint="wss://your-host/ws"
agent-id="…"
agent-name="Support">
</smooth-agent-chat>import { mountChatWidget } from '@smooai/chat-widget';
mountChatWidget({
endpoint: 'wss://your-host/ws',
agentId: '…',
agentName: 'Support',
theme: { primary: '#8b5cf6' }, // one color themes everything
});Key Features:
- One binary for the whole platform — config, secrets, keys, agents, knowledge
- th config replaces the deprecated smooai-config CLI
- Jira sync, pearls work tracking, and git worktree management built in
- Big Smooth — an always-on personal AI assistant, booted with th up
- One ~10 MB binary — no Docker, no Node.js, no runtime deps
Quick Example:
# Install with Homebrew (macOS / Linux)
brew install SmooAI/tools/th
# …or the one-line installer (single binary, no deps)
curl -fsSL https://raw.githubusercontent.com/SmooAI/smooth/main/install.sh | sh
# Manage config, secrets, and feature flags (replaces smooai-config)
th config set DATABASE_URL "postgres://..." --environment production
th config list
# Start Big Smooth — your always-on personal AI assistant
th auth login
th up
th codeProduct building blocks
The libraries our platform runs on
Config, logs, error tracking, tests, schemas, deploys. Every service we ship leans on these — so we open sourced them, with the same multi-language reach.
Key Features:
- Three-tier configuration: public, secret, feature flags
- Schema-agnostic validation (Zod, Valibot, ArkType, Effect)
- Type-safe keys with automatic casing conversion
- JSON Schema serialization for cross-language use
- Runtime client with local caching for config servers
Quick Example:
import { defineConfig } from '@smooai/config';
import { z } from 'zod';
export default defineConfig({
public: {
API_URL: z.string().url(),
APP_NAME: z.string().default('My App'),
},
secret: {
DATABASE_URL: z.string(),
JWT_SECRET: z.string().min(32),
},
featureFlags: {
NEW_DASHBOARD: z.boolean().default(false),
},
});Installation:
pnpm add @smooai/configKey Features:
- Automatic context gathering for AWS services
- Correlation ID tracking across microservices
- Browser and device intelligence
- Detailed error logging with stack traces
- Log rotation, pretty printing, and a desktop log viewer
Quick Example:
import { AwsServerLogger } from '@smooai/logger';
const logger = new AwsServerLogger({ name: 'UserAPI' });
export const handler = async (event, context) => {
logger.addLambdaContext(event, context);
logger.info('Processing request', { userId: event.pathParameters.id });
// Outputs CloudWatch-formatted JSON with full context
};Installation:
pnpm add @smooai/loggerKey Features:
- Error capture for browser, Node, React, and Next.js
- Automatic context + breadcrumbs on every event
- Open-core companion to the hosted o11y dashboards
- Rust core with typed JavaScript SDKs
Quick Example:
import { init, captureException } from '@smooai/observability';
init({ dsn: process.env.SMOOAI_O11Y_DSN, environment: 'production' });
try {
await checkout(cart);
} catch (err) {
captureException(err, { tags: { area: 'checkout' } });
throw err;
}Installation:
pnpm add @smooai/observabilityKey Features:
- CLI-first — report CTRF results straight from CI
- Programmatic SDK for custom test orchestration
- Manage runs, cases, environments, and deployments
- First-class GitHub Actions integration
Quick Example:
# Authenticate
npx @smooai/testing login \
--client-id <M2M_CLIENT_ID> \
--client-secret <M2M_CLIENT_SECRET> \
--org-id <ORG_ID>
# Report CTRF test results from CI
npx @smooai/testing runs report ctrf-report.json \
--environment production \
--name "PR #42 Tests"Installation:
pnpm add @smooai/testingKey Features:
- PgTableSpec as the single source of truth for DDL
- Diff-based migrations + CI drift detection
- serde / sqlx row codegen from the spec
- Tenant-scoped sqlx layer built in
Quick Example:
use smooai_postgres_kit::{PgTableSpec, Column, ColumnType};
// One spec is the source of truth — DDL, migrations, and row types derive from it.
let contacts = PgTableSpec::new("contacts")
.column(Column::new("id", ColumnType::Uuid).primary_key())
.column(Column::new("org_id", ColumnType::Uuid).not_null())
.column(Column::new("email", ColumnType::Text))
.tenant_scoped("org_id");
// Diff against the live database and emit a forward migration.
let migration = contacts.diff(&introspected)?;
println!("{}", migration.to_sql());Key Features:
- Allowlisted types — safe for user-defined schemas
- DDL generation + forward-only migrations
- Drift detection for multi-tenant tables
- Serde-native, Rust throughout
Quick Example:
use smooai_clickhouse_kit::{TableSpec, Column, ChType};
// Allowlisted types only — safe to build from untrusted, per-tenant schemas.
let events = TableSpec::new("events")
.column(Column::new("ts", ChType::DateTime64(3)))
.column(Column::new("org_id", ChType::String))
.column(Column::new("name", ChType::LowCardinality(Box::new(ChType::String))))
.order_by(["org_id", "ts"]);
// Forward-only migration + drift check against the live table.
let ddl = events.create_ddl();Key Features:
- Reusable SST v4 constructs (WebSocket + Rust Lambda + DynamoDB + S3 Vectors)
- Helm / ArgoCD chart for Kubernetes deploys
- Consumed by smooth-operator, dogfooded by Smoo AI
Installation:
pnpm add @smooai/deployKey Features:
- Shared design tokens + CSS
- The Smoo monogram as a component
- One brand across five language ecosystems
Handy on their own
Utility libraries
Standalone tools that don't need the rest of the stack — grab one and go. Battle-tested in production, MIT licensed.
Key Features:
- Automatic retries with exponential backoff and jitter
- Intelligent timeout management
- Circuit breaking for unstable services
- Schema validation and type-safe responses
- Built-in telemetry and @smooai/logger integration
Quick Example:
import { FetchBuilder } from '@smooai/fetch';
import { z } from 'zod';
const api = new FetchBuilder('https://api.example.com')
.withRetry({ maxRetries: 3, backoff: 'exponential' })
.withCircuitBreaker({ threshold: 5, resetTimeout: 30000 })
.withTimeout(5000)
.build();
const users = await api.get('/users', {
schema: z.array(z.object({ id: z.string(), name: z.string() })),
});Installation:
pnpm add @smooai/fetchKey Features:
- Stream-first design for memory efficiency
- Multiple file sources (local, URLs, S3, FormData)
- Lazy file content loading
- Intelligent file type detection (100+ types)
- Rich metadata extraction and checksum support
Quick Example:
import { SmooFile } from '@smooai/file';
// Stream from URL to S3 without loading into memory
const file = await SmooFile.fromUrl('https://example.com/large-file.zip');
console.log(file.mimeType); // 'application/zip'
await file.uploadToS3('my-bucket', 'uploads/file.zip');
// Generate a signed URL for temporary access
const signedUrl = await file.getSignedUrl(3600);Installation:
pnpm add @smooai/fileKey Features:
- Lambda error handling helpers
- Production-ready Hono app factory
- Smart retries + environment detection
- Schema validation with human-readable errors
Installation:
pnpm add @smooai/utilsKey Features:
- Base, Node, React, Next.js, and library presets
- Strict type checking out of the box
- Tuned for monorepos
And a few more
More from our GitHub
Want to contribute?
We welcome contributions from the community. Browse the repositories, open an issue, send a pull request, or suggest something new.
Visit our GitHub organizationNeed custom development?
Our open source packages solve common problems — and when you need more, we build custom solutions that plug straight into this ecosystem. Let's talk about your project.
Let's Build Something Amazing
Tell us about your development needs and we'll create custom solutions that integrate seamlessly with our open source ecosystem.
By submitting this form, you agree to our Privacy Policy and Terms of Service.