Skip to main content
Zuko is an open-source agentic CRM that combines a modern CRM data model (contacts, companies, deals) with an AI chat experience. Every conversation can be grounded in a specific CRM entity so the AI always has the right customer, deal, or company in context.

​
Tech stack

LayerTechnology
FrontendNext.js 16 + React 19 (App Router)
BackendNestJS 11
DatabasePostgreSQL via Prisma ORM
AuthBetter Auth (GitHub OAuth + optional email/password)
AI agentsLangGraph (graph agents in TypeScript)
Meeting botPuppeteer + Deepgram (Google Meet recording)
MonorepoNx + Bun 1.3.10 workspaces

​
Repository structure

zuko/
├── apps/
│   ├── backend/          # NestJS API (port 3001)
│   ├── web/              # Next.js frontend (port 3000)
│   ├── ai-agents/        # LangGraph agents service (port 8080)
│   ├── meeting-bot/      # Google Meet recording bot (port 8000)
│   ├── web-e2e/          # Playwright E2E tests for web
│   ├── backend-e2e/      # Backend E2E tests
│   └── ai-agents-e2e/    # AI agents E2E tests
├── libs/
│   ├── models/           # Prisma schema, DB client, seeds
│   ├── core/             # Shared utilities
│   ├── ui-kit/           # Shared React components
│   ├── sales/            # CRM domain: contacts, deals, companies
│   └── agents/           # AI agents library
└── docs/                 # This documentation

​
Prerequisites

Before setting up Zuko, make sure you have the following installed:
Zuko requires Node.js 22 (matches the CI environment). Earlier versions will not work.Check your version:
node --version
# Should output v22.x.x
Install via nvm:
nvm install 22
nvm use 22
Bun is used as the package manager and runtime across the monorepo.Check your version:
bun --version
# Should output 1.3.10 or higher
Install Bun:
curl -fsSL https://bun.sh/install | bash
Zuko uses PostgreSQL for all data storage. Any recent version works.macOS (Homebrew):
brew install postgresql@16
brew services start postgresql@16
Check it’s running:
psql --version
pg_isready
You will need:Optional:
  • LangSmith API key — for agent tracing at smith.langchain.com
  • Deepgram API key — only needed for the meeting bot

​
Core concepts

  • Contacts, companies, deals — the three core CRM entities, modeled in the database and exposed via the backend API.
  • Agentic chat — an AI chat interface where conversations can be attached to any CRM entity, keeping AI responses grounded in real customer data.
  • AI agents service — a separate LangGraph service (apps/ai-agents) that runs the agent logic and calls the backend via authenticated /api/agents/* endpoints.
  • Meeting bot — joins Google Meet calls, records audio, transcribes via Deepgram, and stores recordings in S3.
  • Beads issue tracking — issues live in .beads/issues.jsonl and are managed with the bd CLI directly in the repo.