English ｜ 简体中文
Quick Start ｜ Architecture ｜ Documentation ｜ Design Stance ｜ Extensions ｜ Community ｜ Contributing ｜ Issue Tracker
Cortico is an agent harness designed around an event stream, built for autonomous, continuously running agents with mixed real-time input. It suits persona bots, AI streamers, roleplay, companionship, and many other downstream tasks. A Cortico bot is far more than a chat bot: with an extensible agent system designed around the event stream, Cortico helps you build persistent AI agents capable of handling complex inputs. It supports flexible external extensions, allowing a single bot to simultaneously observe and act across multiple environments—including chat platforms, live games, and even physical environments. Cortico's goal: bring your AI to the world!
- 🆓 Free and open source!
- 🤖 A native agent harness: everything is designed around the agent.
- 🔌 Modular LLM provider components: built on the Responses protocol inside, supporting various upstream LLM APIs as well as locally deployed models outside.
- 🧠 Unconstrained internal context management, giving much freedom for the design of agent behaviour patterns and Memory systems.
- 🧩 An extension system (Cortico World), isolated from the inside, with event delivery and tool calls as its input and output: excellent compatibility and nearly unlimited extensibility.
- 🖥️ A WebUI that is straightforward to operate.
- 🪄 An Extension Creator system built for AI development (Cortina): a non-developer can use an AI agent to build the extension they want, or move an existing implementation onto Cortico!
Use cortico-world-vtuber to start creating your own AI VTuber right away: it drives a Live2D model through VTube Studio, speaks through streaming TTS, times subtitles with a forced aligner and pushes the overlay into OBS, all as one Cortico World.
It is released under its own source license (AGPL-3.0 + CLA), so it lives in a separate repository instead of the Cortico main tree.
Use 
to build the Cortico extension or adaptation you want, fast!
How to use: first, clone the repository from https://github.com/Pal-AI-Lab/Cortina to your machine.
- Open that workspace with any coding agent.
- Say hello! Cortina assists and guides you through the Cortico extension development / adaptation you want, all through conversation.
- No coding experience or knowledge needed.
- Once the extension is finished, publish it to npm to share it with everyone~
Cortina is designed on the TINA (There Is No App) Spec proposed by Pal AI Lab. There is no app here: language is the code, the agent is the runtime.
Requires Node 22+.
corepack pnpm install
pnpm startOn your first launch with an empty deployment directory, Cortico automatically initializes a default deployment named mybot (using the reference bot cormini with terminal chat enabled) and spins up the web console at:
http://127.0.0.1:7788/
The terminal page opens with three onboarding steps: configure a model endpoint, inspect active Worlds, and adjust the system prompt. Once an endpoint is configured, click Say hello to let the bot initiate conversation. All endpoints, credentials, and runtime parameters can be adjusted directly from the console; saved changes apply to the next request, and a managed runtime's launch parameters apply on its next start.
Each deployment is an isolated configuration directory inside deployments/ (see deployment.md). To add another one:
pnpm start --newPick a bot package, a directory name and a display name; the new deployment starts right away, with endpoints and everything else configured from the console. To start a specific deployment by name:
pnpm start secondThe launcher scripts (pnpm start, ./start.sh, and start.bat on Windows) automatically install missing dependencies, build web console assets when they are missing or older than the source, list every deployment for selection on an interactive terminal (including an entry for creating a new one), and restart processes on request from the console.
Cortico strictly separates concerns across four distinct layers:
| Layer | Responsibility | Directory |
|---|---|---|
| Core | Manages session lifecycles, event streams, and model invocations. Semantics-free. | src/core/ |
| Persona | Defines the semantics of a bot category: context synthesis, cognitive loop, and Memory protocols. | bots/<name>/persona/ |
| Memory | The authoritative persistence store for internal state; layout and lifecycle are chosen by the Persona. | <deployment>/memory/ |
| World | The isolated boundary to an external environment: event ingestion, tool declarations, and environment prompts. | src/worlds/<id>/ |
| Bot | Assembly definition: couples one Persona with a designated set of Worlds. | bots/<name>/index.ts |
| Document | Topic |
|---|---|
| deployment.md | Deployment layouts, deployment roots, and launcher behaviors |
| configuration.md | Four-layer config cascading, configuration groups, and hot reload |
| providers.md | Provider modules, model catalogs, endpoint configurations, and pricing |
| runtimes.md | Local runtimes and model files for llamacpp |
| console.md | Console architecture, live monitoring, and custom module pages |
| sessions.md | Session lifecycle, token capacity management, and context handoff |
| runs.md | Runtime directories, structured logs, and pnpm logq CLI |
| personas.md | Persona lifecycle hooks, Memory architecture, and bot assembly |
| worlds.md | The World contract: events, tools, and environment prompts |
| extensions.md | Extension package specifications, manifests, and dynamic loading |
| environment-variables.md | CORTICO_* environment configuration and the .env hierarchy |
| windows.md | Windows environment compatibility and setup |
| development.md | Development workflows, dual tsconfig setup, and test architecture |
| World | ID | Integration & Capabilities |
|---|---|---|
| Terminal | terminal |
Interactive two-way conversation within the web console |
qq |
Multi-group and direct message channels with optional vision model transcription | |
| Bilibili Live | bilibili |
Real-time danmaku, superchats, gifts, guards, and viewer traffic monitoring with local OBS overlay |
| Minecraft | minecraft |
Mineflayer client for vanilla servers: game state observations and high-level autonomous action dispatch |
| Web Search | websearch |
Real-time web search integration powered by Brave Search API |
| Provider | Supported Services |
|---|---|
openai-responses-compat |
Any model API supporting the Responses protocol specification |
llamacpp |
Local llama-server runtime with automated binary download and process management |
Additional upstream protocols and providers can be integrated seamlessly via extensions.
Join our groups to follow the project and talk with other developers!
- QQ Group: 681195563
- Discord Server: https://discord.gg/DR37WB5zJf
We welcome issues and pull requests!
- Please read CONTRIBUTING.md for architectural guidelines and code separation rules.
- Refer to AGENTS.md for our engineering conventions and code review checklist.
- AI-assisted contributions are welcome, provided the author thoroughly understands and can explain all submitted logic.
Run automated verifications before submitting:
pnpm test
pnpm run typecheckFor changes touching frontend browser code, also run:
pnpm typecheck:web
pnpm build:webBuilding something cool with Cortico? Submit a pull request to share it here!
- @可缇Corti — An AI VTuber from the future
- ...and more!