Cortex — Autonomous Project Owner

中文文档 | Docs

Cortex is an autonomous agent system for long-running projects. You give it a mission with a success criterion, and it plans the work, dispatches a pipeline of agents to execute it, keeps a structured log of progress in your repo, and reviews itself before each commit — across days or weeks of unattended work.

Cortex is designed around four failure modes of long agent runs. Context rot — durable project state lives as plain files in your repo, not chat history that accumulates and decays. Execution drift — every task carries a verifiable success criterion, checked at completion. Context window limits — work is partitioned across agent pipelines, each with bounded scope and fresh context. Single-perspective bias — adversarial review is a built-in pipeline stage, not a polite suggestion.

Features

• Mission-driven task system — hand off a goal; Cortex decomposes it into tracked tasks with priorities, dependencies, and verifiable done-conditions, works through them autonomously, and stops to ask only when blocked. You stop maintaining the todo list. See docs/tasks.md.

• Multi-agent thread pipelines — long jobs run as a relay of focused agents instead of one overloaded session. Each step starts with a clean context and a narrow scope, so the model never loses the plot mid-task. Handoffs carry only what the next stage needs. See docs/threads.md.

• Structured project log — every project keeps mission, roadmap, status, experiments, knowledge, patterns, and decisions as plain files in your repo. A fresh agent (or a fresh you, weeks later) can pick up where the last one left off — no chat history to scroll, no vector store to query. See docs/memory.md.

• Cron and interval scheduling — schedule Cortex to scan a domain every morning, ship a weekly digest, or sweep an inbox every few minutes. Schedules persist across restarts and hot-reload without downtime. See docs/scheduling.md.

• Self-evolving skills — when Cortex catches itself doing the same thing a third time, it drafts a new skill, you approve, and future runs use it automatically. The longer Cortex runs, the more your patterns become first-class behavior. See docs/skills-and-plugins.md.

• One agent across your machines — your compute, documents, code, and tools rarely live on one box. Connect any Mac, Windows, or Linux machine as a remote host via cortex-client, and Cortex can read, write, and execute across all of them from a single control plane. See docs/cross-machine.md.

• Backend agnostic — runs on Claude Code or PI today, with adapter abstraction for additional coding agents. Use the LLM subscription you already pay for — no extra API key, no second bill.

• Slack and CLI native — talk to Cortex from Slack on your phone (interactive prompts, threads, file uploads) or from a terminal on your laptop. Same agent, same project, same memory.

Quickstart

Requirements: Node 20+ and an installed coding agent backend (Claude Code or PI).

# Install
npm install -g @cortex-agent/server

# Initialize (guided setup)
cortex init

# Start
cortex start

Once running, message Cortex from Slack — it reads your project context, plans the work, and dispatches agents automatically.

For a detailed step-by-step guide covering setup wizard prompts, what files are created, and how to send your first message, see docs/quickstart.md.

How a project looks

Each project lives under .cortex/context/projects/<name>/ with a predictable layout:

projects/my-project/
├── mission.md           # Goal and success criteria
├── roadmap.md           # Milestones and timeline
├── STATUS.md            # Current state (overwrite)
├── ISSUES.md            # Open friction points (append)
├── TASKS.yaml           # Machine-readable task queue
├── decisions/           # DR-NNNN.md design decisions (append)
├── experiments/         # EXP-NNN.md atomic experiment records
├── knowledge/           # K-NNN.md atomic knowledge entries
├── patterns/            # PAT-NNN.md cross-experiment patterns
└── tasks-archive.md     # Completed tasks (auto-archived)

This is the project log. It survives sessions, restarts, and model upgrades. A fresh agent can resume work from here without the previous conversation.

Safety boundaries

Cortex classifies operations by blast radius. The harness enforces this at the tool-call layer.

| Class | Examples | |-------------------|------------------------------------------------------------| | Autonomous | read files, run small scripts, edit context files, web search, in-budget compute | | Requires approval | modify CLAUDE.md rules, add new skills, change agent-server behavior, over-budget compute, delete data | | Forbidden | system-level package install, system config changes, rm -rf |

The approval queue lives at .cortex/context/PENDING_APPROVALS.md. Configure additional rules in .claude/settings.json.

Configuration

All configuration lives under $CORTEX_HOME/config/. Only CORTEX_PLATFORM and your platform credentials (Slack tokens) are required. Run cortex init for guided setup. The full environment variable reference, file layout, and precedence rules are in docs/configuration.md.

Docs

| Doc | What it covers | |---|---| | Quickstart | Install, init, and first Slack message in 5 minutes | | Slack Setup | App creation, token collection, Socket Mode, scopes | | Configuration | Full .env reference, profiles.json, file layout, hot-reload | | CLI Reference | cortex, cortex-task, cortex-run — every subcommand and flag | | Backends | Claude Code vs PI vs Codex, feature matrix, fallback, cost reporting | | Architecture | Server layers, WS protocol, event bus | | Threads | Multi-agent pipelines, templates, transitions, hooks | | Tasks | TASKS.yaml format, lifecycle, dispatch, cortex-run watchdog | | Memory | EXP/K/PAT atomized knowledge, project log governance | | Skills & Plugins | Skill authoring, plugin layout, third-party plugins | | Scheduling | Interval/daily/weekly/once schedules, preCheck, fallback | | Safety & Approvals | Blast-radius classes, approval workflow, audit trail | | Hooks | Hook lifecycle, hook-bridge, custom hooks in settings.json | | MCP | Cortex-core and cortex-ext MCP servers, third-party MCP | | Cross-machine | cortex-client deployment, remote tools, network topology |

Developing on Cortex

# Clone and install dependencies
git clone https://github.com/<your-org>/cortex
cd cortex/agent-server && npm install

# Build
npm run build

# Run tests
npm test

# Start in dev mode (hot-reload via .restart watcher)
npm run build && npm start

Architecture

Cortex has three main packages:

| Package | npm | Role | |---------|-----|------| | @cortex-agent/server | agent-server/ | Control plane — Slack bot, task dispatch, scheduling, thread orchestration | | @cortex-agent/client | client/ | Remote worker — runs on remote machines, executes commands via WebSocket | | Plugins | plugins/ | Role-scoped skills loaded by thread agents at runtime |

The server is organized in six layers (src/): core utilities → persistence → event bus → domain logic → orchestration → entry points. Test coverage is mandatory for all code changes. See docs/architecture.md for the full architecture.

License

MIT