React

cortextOS is an operating system-like framework for managing fleets of AI coding agents (Claude, Codex, Hermes) with a file-based message bus, background daemon, CLI, Telegram bot integration, and a Next.js dashboard. It orchestrates agent lifecycles, schedules cron tasks, handles approvals, and provides multi-modal knowledge base capabilities via RAG scripts.

Tech Stack

ReactNext.jsVitest

Key Features

File-Based Message Bus
Agent Daemon with IPC
CLI Agent Management
PTY-Based Agent Processes
Telegram Bot Integration
Event Hooks System
Next.js Dashboard
Multi-Modal RAG Knowledge Base
Community Agent Templates

Coding Conventions

Standards and patterns used in this codebase

Build & Compilation

Use tsup for building TypeScript packages with multiple entry points, targeting Node.js ESM output with declaration files and source maps enabled

tsup.config.ts defines entry points for each module (bus, daemon, cli, pty, telegram, hooks, types, utils) compiled to ESM format

tsup.config.ts

Testing

Use Vitest for unit/integration tests with path aliases matching tsconfig, and Playwright for E2E tests. Tests are organized by type (unit, integration, e2e) and sprint-based feature tests live at the tests root

vitest.config.ts sets up path aliases and test discovery patterns; playwright.config.ts defines browser test settings; tests/unit/, tests/integration/, tests/e2e/ directories

vitest.config.tsplaywright.config.ts

Process Management

Use PM2 for daemon process management with ecosystem.config.js defining process configuration for the cortextOS daemon

ecosystem.config.js configures PM2 process settings for the daemon lifecycle

ecosystem.config.js

File I/O & Concurrency

Use atomic writes and file locking utilities for all file-based data operations to prevent corruption in the message bus and config files

Shared utilities in src/utils provide atomic write and file locking primitives used by the bus layer for tasks, events, crons, approvals, heartbeats, and knowledge

scripts/migrate-runtime-field.ts

Architecture

Follow a file-based message bus pattern for inter-agent communication rather than using a database or network-based message queue. The bus handles tasks, events, crons, approvals, heartbeats, and knowledge as files

src/bus implements file-based messaging; daemon reads/writes bus files for agent lifecycle, cron scheduling, and health checks

Dashboard & Frontend

Use Next.js App Router with shadcn-style reusable UI primitives, Tailwind CSS via PostCSS, and enforce authentication via middleware using session cookies or JWT Bearer tokens with CORS and security headers

dashboard/src/middleware.ts enforces auth and security; dashboard/src/components/ui/ contains reusable primitives (button, card, dialog, tabs); postcss.config.mjs configures Tailwind

dashboard/src/middleware.tsdashboard/postcss.config.mjsdashboard/eslint.config.mjsdashboard/next.config.ts

API Design

Next.js API routes serve as the dashboard backend, with cache headers configured to prevent caching on API responses. Routes are organized by domain (agents, workflows, comms, tasks, approvals, analytics)

dashboard/next.config.ts sets cache headers for API routes; dashboard/src/app/api/ contains domain-organized route handlers

dashboard/next.config.ts

Type Safety

Maintain a shared types module (src/types) for core system type definitions, ensuring type consistency across bus, daemon, CLI, PTY, telegram, and hooks layers

src/types contains shared TypeScript type definitions imported by all other modules

Hooks & Extensibility

Use an event hooks system for cross-cutting concerns like Telegram alerts, fact extraction, crash handling, and context status updates, keeping them decoupled from core logic

src/hooks implements event-driven hooks that respond to system events without coupling to the daemon or bus internals

Installation & Cross-Platform

Use ESM scripts (.mjs) for tooling and installation, with cross-platform support checking dependencies before setup

install.mjs is a cross-platform installer that checks dependencies, clones the repo, and sets up the environment

install.mjs

Migration Scripts

Write one-shot migration scripts in TypeScript under scripts/ for schema or config changes, operating directly on file-based agent configs across the workspace

scripts/migrate-runtime-field.ts backfills the `runtime` field into agent config.json files

scripts/migrate-runtime-field.ts

Linting

Use ESLint with Next.js core web vitals and TypeScript rule extensions for the dashboard; config files use .mjs extension for ESM compatibility

dashboard/eslint.config.mjs extends Next.js core web vitals and TypeScript rules

dashboard/eslint.config.mjs