TheChat

Facilitate collaboration between machines and humans.

Development

This project has very limited documentation intentionally.

Documentation rot is a real thing.

Source code + CLAUDE.md is documentation.

PostgreSQL

Create .env:

DATABASE_URL=postgresql://thechat:thechat@localhost:15543/thechat

Reset the Docker Compose PostgreSQL service using that DATABASE_URL and push the schema:

./scripts/restart-db.sh

This removes only the Docker Compose PostgreSQL service and its data volume, leaves other Compose services such as Redis running, starts a new PostgreSQL 17 instance, and runs pnpm db:push.

Building the desktop app from source

Prerequisites

• Node.js >= 22
• pnpm >= 9
• Rust (stable)
• Platform-specific system libraries (see below)

Linux (Debian/Ubuntu)

sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

macOS

xcode-select --install

Windows

• Microsoft C++ Build Tools with the "Desktop development with C++" workload
• WebView2 (pre-installed on Windows 10 1803+ and Windows 11)

Build

git clone https://github.com/crosslink-ch/thechat.git
cd thechat
pnpm install
pnpm tauri:build:dev --no-bundle

Executable is written to packages/desktop/src-tauri/target/release/

Dev mode

For the local backend stack:

pnpm dev

This starts Docker Compose services, runs database migrations, then starts the API and bot worker. Logs are written to .tmp/dev.

Useful options:

pnpm dev -- --skip-compose
pnpm dev -- --skip-migrate
pnpm dev -- --no-worker

For the desktop app:

pnpm tauri:dev

Starts the Vite dev server and the Tauri app with hot reload. This command applies the development Tauri flavor, named TheChat Dev with identifier com.bruno.thechat.dev. Framework-managed app data, the Windows WebView2 profile, logs, caches, and generated files therefore stay separate from the installed production app, which retains com.bruno.thechat.

pnpm tauri:dev is the canonical command. The package-level Tauri wrapper also injects the development flavor for direct pnpm tauri dev commands, preventing an accidental development launch with the production identity. For a release-mode local build that keeps the development identity, use pnpm tauri:build:dev. pnpm tauri:build retains the production identity for release validation. The fixed OAuth callback ports remain shared, so do not start OAuth login in both apps at the same time.

Rust profiling

The Rust backend uses tracing for instrumentation, with optional backends behind cargo feature flags. Release builds have zero overhead.

Log levels

Controlled by the THECHAT_TRACING env var using tracing EnvFilter syntax — comma-separated target=level pairs where the target is typically the crate name:

THECHAT_TRACING=thechat=trace pnpm tauri:dev                       # our code at trace, others at default
THECHAT_TRACING=thechat=trace,reqwest=debug,warn pnpm tauri:dev     # per-crate control
THECHAT_TRACING=trace pnpm tauri:dev                                # everything at trace (very noisy)

If unset, defaults to thechat=debug,info in dev builds, info in release.

tokio-console (async task introspection)

pnpm tauri:dev --features tokio-console
# In another terminal:
tokio-console                                # connects to localhost:6669

Requires tokio-console CLI: cargo install tokio-console

Local Grafana LGTM

Start the local observability stack:

docker compose up -d otel-lgtm promtail

Open Grafana at http://localhost:13300. The default local credentials are admin / admin.

TheChat intentionally uses different local observability ports from the AzulAI dev stack, so both projects can run at the same time:

• Grafana: 13300 -> container 3000
• OTLP gRPC: 14317 -> container 4317
• OTLP HTTP: 14318 -> container 4318

Override them if needed:

GRAFANA_PORT=23300 OTEL_GRPC_PORT=24317 OTEL_HTTP_PORT=24318 docker compose up -d otel-lgtm promtail

The TheChat Dev Grafana folder is provisioned from deployment/local/grafana/dashboards. It includes dashboards for local logs and OpenTelemetry span metrics/traces.

Promtail reads local log files from .tmp by default (pnpm dev:services mounts .tmp/dev instead and writes API and worker logs there; pnpm dev:hermes writes API, Hermes gateway, and desktop logs to .tmp). Files are matched recursively, so either mount works. To use another directory:

THECHAT_DEV_LOGS_DIR=/path/to/logs docker compose up -d promtail

Dev builds of the desktop app (pnpm tauri:dev) also mirror their logs — including webview logs from the frontend — as JSON to $THECHAT_DEV_LOGS_DIR/desktop.log (default .tmp/dev/desktop.log), so they appear in the TheChat Dev Logs dashboard under job=thechat-desktop without extra setup. Rust-side tracing events are not included; use THECHAT_TRACING (stderr) or the otel feature for those.

For Rust/Tauri traces, point the OTLP exporter at the local LGTM HTTP endpoint and run the app with the otel feature:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:14318 pnpm tauri:dev --features otel

In Grafana Explore, select Tempo, choose TraceQL, and run { resource.service.namespace = "thechat" }.