Cogitator
Getting Started

Project Structure

How Cogitator projects and the monorepo are organized.

Monorepo Architecture

Cogitator is a pnpm + Turborepo monorepo. It publishes 32 @cogitator-ai/* packages and the create-cogitator-app scaffolder; dashboard (this site) and e2e (end-to-end tests) are private:

packages/
├── types/            # @cogitator-ai/types — shared TypeScript interfaces
├── core/             # @cogitator-ai/core — Cogitator runtime, Agent, tool(), LLM backends, built-in tools
├── models/           # @cogitator-ai/models — model registry with pricing and capabilities
├── config/           # @cogitator-ai/config — cogitator.yml and environment loading
├── memory/           # @cogitator-ai/memory — memory adapters, embeddings, knowledge graphs
├── rag/              # @cogitator-ai/rag — RAG pipeline (loaders, chunkers, retrieval, reranking)
├── workflows/        # @cogitator-ai/workflows — DAG engine, sagas, map-reduce, scheduling
├── swarms/           # @cogitator-ai/swarms — 7 swarm strategies
├── a2a/              # @cogitator-ai/a2a — Agent-to-Agent Protocol v0.3
├── mcp/              # @cogitator-ai/mcp — Model Context Protocol client and server
├── browser/          # @cogitator-ai/browser — browser automation (Playwright, stealth, vision)
├── sandbox/          # @cogitator-ai/sandbox — Docker and WASM execution isolation
├── wasm-tools/       # @cogitator-ai/wasm-tools — pre-built WASM tools
├── voice/            # @cogitator-ai/voice — voice and realtime agents (STT, TTS, VAD)
├── evals/            # @cogitator-ai/evals — eval framework (metrics, A/B testing, assertions)
├── self-modifying/   # @cogitator-ai/self-modifying — runtime tool generation
├── neuro-symbolic/   # @cogitator-ai/neuro-symbolic — Prolog-style logic, SAT/SMT
├── redis/            # @cogitator-ai/redis — Redis client (standalone + cluster)
├── worker/           # @cogitator-ai/worker — BullMQ distributed job queue
├── server-shared/    # @cogitator-ai/server-shared — shared REST/SSE/WebSocket utilities, OpenAPI
├── express/          # @cogitator-ai/express — Express.js integration
├── fastify/          # @cogitator-ai/fastify — Fastify integration
├── hono/             # @cogitator-ai/hono — Hono integration
├── koa/              # @cogitator-ai/koa — Koa middleware
├── tetsu/            # @cogitator-ai/tetsu — Tetsu controller on Bun (SSE, WebSocket, OpenAPI)
├── next/             # @cogitator-ai/next — Next.js App Router
├── ai-sdk/           # @cogitator-ai/ai-sdk — Vercel AI SDK adapter
├── openai-compat/    # @cogitator-ai/openai-compat — OpenAI Assistants API compatibility
├── channels/         # @cogitator-ai/channels — Telegram, Discord, Slack, WhatsApp, WebChat
├── deploy/           # @cogitator-ai/deploy — Docker and Fly.io deployment
├── cli/              # @cogitator-ai/cli — the `cogitator` command
├── test-utils/       # @cogitator-ai/test-utils — testing utilities
├── create-cogitator-app/  # create-cogitator-app — project scaffolder
├── dashboard/        # private — landing page, docs and cookbook site
└── e2e/              # private — end-to-end test suite

Package Dependency Graph

@cogitator-ai/types            ← shared interfaces, no dependencies
       ↑
models · redis → memory        ← model registry, Redis client, memory adapters
       ↑
@cogitator-ai/core             ← Cogitator runtime (types + models + memory)
       ↑
┌──────┼───────────┬──────────────────┬───────────────────────────┐
│      │           │                  │                           │
workflows  browser, neuro-symbolic  channels  express, fastify, hono, koa, tetsu
  ↑                                           (+ server-shared), next, openai-compat
swarms
  ↑
worker
  • @cogitator-ai/core depends on types, models and memory (which uses redis).
  • swarms builds on workflows, and worker on swarms.
  • mcp, rag, sandbox, wasm-tools, voice, a2a, evals, ai-sdk and self-modifying declare at most types as a dependency (some take core or memory as a peer dependency).
  • config and deploy handle configuration and deployment; cli combines core, config, models, memory, channels and deploy.

Typical Project Layout

A project scaffolded with create-cogitator-app (basic template) looks like this:

my-agent/
├── src/
│   ├── index.ts          # entry point: Cogitator + Agent
│   └── tools.ts          # tool definitions
├── cogitator.yml
├── .env.example          # API keys to copy into your environment
├── .gitignore
├── docker-compose.yml    # Redis + Postgres (+ Ollama), when Docker was chosen
├── pnpm-workspace.yaml   # when pnpm is the package manager
├── package.json
├── README.md
└── tsconfig.json

Other templates add files such as src/agents/*.ts (swarm) or src/agents.ts (workflow, api-server); see Project Scaffolding.

Development Commands

Run these from the monorepo root:

pnpm install        # install all dependencies
pnpm build          # build all packages (turbo)
pnpm dev            # watch mode for all packages
pnpm test           # unit tests across all packages
pnpm typecheck      # type-check all packages
pnpm lint           # lint the whole repo

pnpm --filter @cogitator-ai/core test    # one package

Project Scaffolding

Create new Cogitator projects in seconds with create-cogitator-app.

Configuration

Configure Cogitator with YAML files, environment variables, and provider settings.

On this page

Monorepo ArchitecturePackage Dependency GraphTypical Project LayoutDevelopment Commands