Contributing

Licensing of contributions. SmartChats is operated on an open core model: this repository is open, and SmartChats Cloud is a closed product built on it. The repository is licensed under Apache-2.0, and by contributing you agree that your contribution is licensed under it too (section 5) and that Sattvic Systems LLC may use it in SmartChats Cloud and its other products. The full terms are in CONTRIBUTING.md.

Questions? Join the Discord.

The developer guide is CONTRIBUTING.md on GitHub. It covers setup, the architecture, the verification workflow, the conventions, the PR workflow and a section for AI coding agents.

In short:

Clone, install, run bin/preflight. It lints and builds the whole monorepo through turbo. If it passes, your environment works.
Adding a query the agent can run takes three files and about 20 lines. See Architecture.
Run bin/preflight before opening a PR. For UI changes, run bin/devserve (or smartchats dev) for hot reload and check the change in a browser.

Running from source

The user install (curl | bash from Quick Start) ships compiled binaries. For development, use the source:

git clone https://github.com/sheunaluko/smartchats.git
cd smartchats
npm install

Two ways to run the stack while you work:

# Hot-reload Next.js dev server + Express + SurrealDB container
bin/devserve
 
# Or through the CLI, which calls bin/devserve:
cd packages/smartchats-cli
npm link    # points the `smartchats` command at your source
smartchats dev

bin/devserve is the normal dev loop: hot reload and TypeScript watch, with no container rebuild per change. smartchats start is the end-user path, and is useful for checking production behavior.

⚠️

Don’t run npm run dev at the repo root. Turbo would start every package’s dev script, including ones you don’t need. The MCP server’s stdio script is named dev:stdio for this reason, so it no longer starts a sign-in flow, but bin/devserve or smartchats dev still start only the processes you need.

Useful bin/ scripts

Script	What it does
`bin/preflight`	Lint and workspace build (which type-checks). Run before every PR.
`bin/devserve`	Hot-reload dev stack: Next.js dev, the Express server and a SurrealDB container
`bin/aio`	Build and run the all-in-one Docker image from `Dockerfile.aio`
`bin/test-bun-deploy`	Smoke-test the no-Docker path: native SurrealDB plus the server under Bun
`bin/test-e2e`	Start the `bin/test-bun-deploy` stack, run the Simi e2e suite against it, then stop it
`bin/seaweedfs`	Run a local SeaweedFS S3 bucket for media storage. `bin/seaweedfs env` prints the `SMARTCHATS_S3_*` exports
`bin/release`	Prepare a release tag: bump the CLI version, commit, and create an annotated tag. Does not push
`bin/checkpoint "<msg>"`	`git add -A && git commit -m "checkpoint: <msg>"`
`bin/save_session`	Export session bundles from a local install for triage

The layered test runner is packages/smartchats-test (levels L0 lint, L1 build, L2 unit, L3 integration, L4 e2e). See Architecture: Verification.

Repo layout (high level)

smartchats/
├── apps/
│   ├── smartchats/                # Next.js app (chat UI, voice, KG), static SPA
│   └── site/                      # This docs site
├── packages/
│   ├── cortex/                    # Agent loop
│   ├── llm-service/               # Model + TTS providers, NDJSON streaming, turn verdict
│   ├── tivi/                      # Voice I/O hooks (VAD, speech recognition, TTS queue)
│   ├── vie/                       # Voice engine (turn-taking)
│   ├── smartchats-backend/        # Backend contract (types only)
│   ├── smartchats-backend-local/  # Local-target backend adapter
│   ├── smartchats-cloud-client/   # Client for the hosted cloud
│   ├── smartchats-cli/            # `smartchats` command (setup, start, etc.)
│   ├── smartchats-database/       # SurrealDB queries, operations, DataAPI factories
│   ├── smartchats-local-server/   # Express server: serves the SPA + /local-api/*
│   ├── smartchats-mcp/            # MCP server
│   ├── smartchats-mcp-bridge/     # MCP bridge from a coding agent to the relay
│   ├── smartchats-hub/            # Per-machine agent hub
│   ├── smartchats-test/           # Layered test runner
│   └── ...
├── bin/
│   ├── preflight                  # Lint + build
│   ├── devserve                   # Hot-reload dev stack
│   ├── aio                        # Docker all-in-one image
│   ├── test-e2e                   # e2e suite against a fresh stack
│   ├── checkpoint                 # `git add -A && git commit -m "checkpoint: …"`
│   └── ...
└── CONTRIBUTING.md                # The developer guide

Architecture invariants

These matter. Discuss before changing them:

Single direct importer of surrealdb. Only packages/smartchats-database/src/client.ts imports the npm package in runtime code. Everything else uses its Client interface.
One credential store. ~/.smartchats-mcp/credentials.json is shared by the CLI, MCP server, bridge and hub. Don’t add another auth file.
The DataAPI contract is the read/write boundary. Don’t add another dispatcher layer.
Per-statement errors must surface. Never return a silent [] on status: ERR.

See Architecture: Open and closed for the package-level split.

For AI coding agents

Humans and AI coding agents build SmartChats together. The same rules and review apply to both. What helps agent contributions land:

Read the existing code first. Most patterns you need already exist. Search, then write. Nearly every “I need to add X” has one home.
Make small changes. A feature usually touches one builder, one tool wrapper and one CLI command. A sprawling diff is a sign you are working against the structure.
Run bin/preflight before you call it done. Don’t rely on CI for your own change. For UI work, run bin/devserve or smartchats dev and check the change in a browser.
Confirm destructive actions with the user first: deleting data, force-pushing, changing live cloud state, killing shared processes.
When tests fail, find the cause. Read the log, reproduce it and fix the root cause. Don’t write it off as a flaky environment.
Note architecture ideas instead of refactoring as you go. Raise them in an issue or a discussion. See Architecture for the current design.
Match the surrounding code and docs in tone, style and comment density.

Re-read this section at the start of each session. It is the quickest way to load the project conventions.