You know how ChatGPT and Claude are great at talking? Cogitator makes AI that can do things.

An agent is an AI that has tools - it can search the web, read files, call APIs, write code, run queries. You give it a goal, it figures out which tools to use and in what order.

Cogitator is a TypeScript framework for building these agents. One agent or a hundred, local model or cloud API, simple script or production service - same code, same patterns.

import { Cogitator, Agent, tool } from '@cogitator-ai/core';
import { z } from 'zod';

const weather = tool({
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: z.object({ city: z.string() }),
  execute: async ({ city }) => `${city}: 22°C, sunny`,
});

const agent = new Agent({
  name: 'assistant',
  model: 'google/gemini-2.5-flash', // free tier, no credit card
  instructions: 'You help people with questions. Use tools when needed.',
  tools: [weather],
});

const cog = new Cogitator();
const result = await cog.run(agent, { input: 'What is the weather in Tokyo?' });
console.log(result.output);

That's it. The agent reads your question, decides to call get_weather, gets the result, and writes a human-friendly response.

Option A - scaffold a project:

npx create-cogitator-app my-agents
cd my-agents && pnpm dev

Choose from 6 templates: basic agent, agent with memory, multi-agent swarm, DAG workflow, REST API server, or Next.js chat app.

Option B - add to existing project:

pnpm add @cogitator-ai/core zod

Set GOOGLE_API_KEY in your .env (get one free here) and run any example:

npx tsx examples/core/01-basic-agent.ts

Works with any LLM: swap google/gemini-2.5-flash for openai/gpt-4o, anthropic/claude-sonnet-4-6, ollama/llama3.3, or 10+ other providers.

Build your own AI that runs 24/7 on Telegram, Discord, or Slack. No code required — just a YAML config.

cogitator wizard

The interactive wizard walks you through everything: LLM provider, model, channels, capabilities, memory, MCP servers. It generates a cogitator.yml:

name: Jarvis
personality: 'You are Jarvis, a sharp personal assistant.'
llm:
  provider: google
  model: gemini-2.5-flash
channels:
  telegram:
    ownerIds: ['YOUR_TG_ID']
capabilities:
  webSearch: true
  fileSystem:
    paths: [~/Documents, ~/Projects]
  scheduler: true
  browser: true
memory:
  adapter: sqlite
  path: ~/.cogitator/memory.db
  compaction:
    threshold: 50
stream:
  flushInterval: 600
  minChunkSize: 30

The wizard asks your name, picks channels, configures capabilities, and writes everything to cogitator.yml + .env. Then start it:

cogitator up                    # foreground with live dashboard
cogitator daemon start          # background with auto-restart
cogitator daemon install        # register as system service (systemd/launchd)

You can also use cogitator init to scaffold a full project with package.json, TypeScript config, and source files if you prefer the programmatic API over YAML.

Manage everything from chat — no web dashboard needed:

What you get out of the box:

• Multi-channel — same assistant on Telegram + Discord + Slack + WhatsApp simultaneously
• Streaming — real-time typing with chunked message editing
• Voice messages — automatic STT via Deepgram, Groq, OpenAI, or local Whisper
• Image understanding — photos sent to the bot are analyzed via vision
• Access control — owner/authorized/public levels, pairing codes for new users
• Scheduled tasks — "remind me in 2 hours" with cron/interval/one-shot support
• Memory — persistent conversations with auto-compaction and knowledge graphs
• Lifecycle hooks — 10 event points for logging, analytics, custom behavior
• Skills — extend with tool bundles (cogitator skill add)
• MCP servers — connect any Model Context Protocol tool server

See @cogitator-ai/channels README for the full programmatic API and @cogitator-ai/cli for all CLI commands.

Install only what you need. Everything is a separate npm package.

Server adapters - mount agents as REST APIs with one line:

express · fastify · hono · koa · next · ai-sdk · openai-compat

All with Swagger docs, SSE streaming, and WebSocket support. See integration examples.

Every major feature has a working example you can run right now.

npx tsx examples/core/01-basic-agent.ts

Default LLM is Google Gemini 2.5 Flash - free tier, no credit card. See examples/README.md for setup.

# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/cogitator.git
cd cogitator && pnpm install && pnpm dev

See CONTRIBUTING.md for guidelines.

All npm packages

Package	Description	Version
@cogitator-ai/core	Core runtime (Agent, Tool, Cogitator)
create-cogitator-app	Interactive project scaffolding (npx create-cogitator-app)
@cogitator-ai/cli	CLI tool (cogitator init/up/run/deploy)
@cogitator-ai/types	Shared TypeScript interfaces
@cogitator-ai/config	Configuration management
@cogitator-ai/memory	Memory adapters (Postgres, Redis, SQLite, MongoDB, Qdrant)
@cogitator-ai/models	Dynamic model registry with pricing
@cogitator-ai/workflows	DAG-based workflow engine
@cogitator-ai/swarms	Multi-agent swarm coordination
@cogitator-ai/mcp	MCP (Model Context Protocol) support
@cogitator-ai/a2a	A2A Protocol v0.3 - cross-agent interoperability
@cogitator-ai/sandbox	Docker/WASM sandboxed execution
@cogitator-ai/redis	Redis client (standalone + cluster)
@cogitator-ai/worker	Distributed job queue (BullMQ)
@cogitator-ai/openai-compat	OpenAI Assistants API compatibility
@cogitator-ai/wasm-tools	WASM-based sandboxed tools (14 built-in)
@cogitator-ai/self-modifying	Self-modifying agents with meta-reasoning
@cogitator-ai/neuro-symbolic	Neuro-symbolic reasoning with SAT/SMT
@cogitator-ai/rag	RAG pipeline with loaders, chunking, retrieval, reranking
@cogitator-ai/evals	Evaluation framework with metrics, A/B testing, assertions
@cogitator-ai/voice	Voice/Realtime agents (STT, TTS, VAD, realtime sessions)
@cogitator-ai/browser	Browser automation (Playwright, stealth, vision, 32 tools)
@cogitator-ai/dashboard	Real-time observability dashboard
@cogitator-ai/next	Next.js App Router integration
@cogitator-ai/ai-sdk	Vercel AI SDK adapter (bidirectional)
@cogitator-ai/express	Express.js REST API server
@cogitator-ai/fastify	Fastify REST API server
@cogitator-ai/hono	Hono multi-runtime server (Edge, Bun, Deno, Node.js)
@cogitator-ai/koa	Koa middleware-based server
@cogitator-ai/deploy	Deployment engine (Docker, Fly.io)

MIT - see LICENSE.