Agentchat is a self-hosted agent chat harness. It keeps users, conversations, runtime bindings, and local development state under operator control instead of assuming a hosted product backend.
- Product and architecture map: docs/agentchat/README.md
- Harness engineering model: docs/agentchat/harness-engineering.md
- Agent instructions: AGENTS.md
- Local wrapper details: docs/local-modes.md
- Operator setup: docs/agentchat/operator-guide.md
- Testing and confidence plan: docs/agentchat/testing-plan.md
Agentchat is organized around the system that is already in progress:
- Agent-centric UX where conversations are bound to the selected agent.
- Convex-owned auth, conversations, runs, and runtime bindings.
apps/serveras the runtime layer that owns live agent sessions.- Codex as the active runtime.
- Agent-owned inline runtime config for new Codex agents, with legacy provider config retained only as a compatibility bridge.
- Pi, OpenCode, and Claude Code as planned runtime implementations.
The runtime is an implementation detail of an agent. Avoid rebuilding hosted product assumptions, billing, analytics, attachments, or browser-local product data modes into the active path.
Web/server URLs are routed through portless; worktrees are managed with worktrunk. Both are installed via mise.
bun install
bun scripts/local/setup-tree.ts # one-time per checkout
bun devVisit https://agentchat-web.agentchat.localhost.
For disposable branch work:
wt switch -c <branch> # post-start hook runs setup-tree.ts
bun dev
# ...
wt removeThe setup script owns these generated files:
apps/web/.env.localapps/server/.env.localapps/server/agentchat.config.json
Re-run bun scripts/local/setup-tree.ts to regenerate them; the script is
idempotent and preserves per-tree secrets across runs.
Use the lightest confidence layer that matches the change:
- Orientation: read AGENTS.md, this README, and docs/agentchat/README.md.
- Checkout readiness:
bun install,bun scripts/local/setup-tree.ts. - Runtime readiness:
bun run doctor:server, thenbun devwhen a live stack is needed. - Surface health:
bun run health:web,bun run health:server,bun run health:mobile,bun run health:shared, orbun run health:convex. - Repo policy:
bun run env:check,bun run docs:check,bun run lint:repo, andbun run verify:ci. - Live confidence: use the manual runtime and browser checks in docs/agentchat/testing-plan.md.
The full model is documented in docs/agentchat/harness-engineering.md.
| Surface | Purpose |
|---|---|
apps/web |
Next.js web client |
apps/server |
Agent runtime server and live transport |
apps/mobile |
Expo mobile client |
packages/convex |
Convex schema, auth, conversations, runs, and runtime bindings |
packages/shared |
Shared contracts and utilities |
scripts/local |
Per-tree setup hook + supporting tests |
This inventory keeps environment usage discoverable and satisfies the repo environment-docs check. Prefer docs/local-modes.md and docs/agentchat/operator-guide.md for setup flow details.
Web runtime: PORT, HOST, NEXT_PUBLIC_CONVEX_URL,
NEXT_PUBLIC_AGENTCHAT_SERVER_URL, NEXT_ALLOWED_DEV_ORIGINS.
Mobile runtime: EXPO_PUBLIC_CONVEX_URL,
EXPO_PUBLIC_AGENTCHAT_SERVER_URL, EXPO_PUBLIC_GOOGLE_CLIENT_ID.
Convex CLI and backend: CONVEX_DEPLOYMENT, CONVEX_URL, SITE_URL,
AGENTCHAT_AUTH_MODE, AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET,
BACKEND_TOKEN_SECRET, RUNTIME_INGRESS_SECRET, JWKS, JWT_PRIVATE_KEY,
CONVEX_SITE_URL.
Agentchat backend server: XDG_STATE_HOME, AGENTCHAT_CONVEX_SITE_URL.
Optional Convex limits: AGENTCHAT_MAX_CHAT_TITLE_CHARS,
AGENTCHAT_MAX_MESSAGE_CONTENT_CHARS, AGENTCHAT_MAX_MESSAGE_CONTEXT_CHARS,
AGENTCHAT_MAX_MESSAGE_REASONING_CHARS, AGENTCHAT_MAX_LOCAL_ID_CHARS,
AGENTCHAT_MAX_CHATS_PER_USER, AGENTCHAT_MAX_MESSAGES_PER_USER,
AGENTCHAT_MAX_LIST_CHATS, AGENTCHAT_MAX_LIST_MESSAGES,
AGENTCHAT_MAX_PAGE_CHATS, AGENTCHAT_MAX_PAGE_MESSAGES.
Convex environment variable names must stay under 40 characters.
MIT