Cortex

Give your AI agents a chief of staff, coordinating them through plain markdown files.

Stars
★ 13
Last updated
7mo ago
License
MIT

At a glance

Works with
Universal · cross-platformClaude CodeCodex · OpenAI API · Claude API (Partial support)
You'll need
Claude Code CLIGitShell / CLINetwork accessLocal filesystem
Typical use
You run both a billing service and a dashboard project and want one chief-of-staff agent dispatching to billing-dev and dashboard-dev while sending daily briefings over Telegram.
Main limitation
The turnkey plugin path is tied to Claude Code; other runtimes require writing your own adapter against docs/protocol.md and the adapter examples.
Website
agentweave.github.io/cortex ↗ set on GitHub
Maintenance
No commits for 6+ monthslast commit 2026-04-07

What does this agent do, and when should you use it?

Cortex is an open protocol for coordinating AI agents through plain markdown files with YAML frontmatter, stored in a shared team directory. It ships as a Claude Code plugin with four skills — /setup, /register, /join, /leave — but the protocol is runtime-agnostic: Codex, Cursor, Gemini CLI, OpenCode and anything that can read and write files can participate. The execution model is one chief-of-staff agent plus project-specific worker agents; the chief writes tasks to agents/<slug>/tasks.md, workers poll their task file on a heartbeat, claim ready tasks and report status back. Agents never talk to each other directly, so they do not need to run simultaneously; a worker can pick up a task hours after it was written.

/setup creates the team directory structure, writes ~/.cortex/config.yaml and registers the chief of staff; /register <name> creates <team_dir>/agents/<slug>/ with an agent note and an empty tasks.md; /join <name> reads the agent note, generates .cortex.md in the current project with the full protocol, updates CLAUDE.local.md so the agent auto-syncs on session start, and starts the heartbeat (polling every 15 minutes by default). Task files follow a ready → in-progress → done lifecycle with Started/Completed timestamps and a ### Summary block, using the Shuttle Protocol format. The chief of staff sends briefings at the configured daily_briefing and daily_review times, detects stale agents via <!-- cortex:last-tick --> liveness timestamps, and prunes done tasks older than seven days and trims session logs during the daily review, with git preserving history.

  1. You run both a billing service and a dashboard project and want one chief-of-staff agent dispatching to billing-dev and dashboard-dev while sending daily briefings over Telegram.
  2. Your team already keeps an Obsidian vault and wants to use that directory as the team directory so agent notes and tasks live as markdown.
  3. A mixed team where the chief of staff runs on Claude Code while workers run on Codex or Gemini CLI, using the adapters under docs/adapters/.
  4. Worker agents cannot be online when the chief writes tasks and must pick up work later from the file queue on a heartbeat.
  5. You want an auditable assigned/started/completed timeline in the task files plus git history for previously pruned tasks.
  6. You want terminal-only operation without Telegram, using /join and the heartbeat to run unattended daily dispatch.

Key setup facts

Pulled from the install and usage notes below. The project README has the current values.

Config files
.claude-plugin/marketplace.json ~/.cortex/config.yaml

How do you install or deploy this agent?

Install from a local clone:

claude plugins marketplace add /path/to/cortex --scope user
claude plugins install cortex@agentweave

Install from GitHub:

claude plugins marketplace add https://github.com/agentweave/cortex --scope user
claude plugins install cortex@agentweave

The marketplace name agentweave comes from .claude-plugin/marketplace.json, which is required for the plugin system to discover and install the plugin. Then run /setup in Claude Code; it asks for the team directory path (default ~/cortex-team), an optional Telegram chat ID, the heartbeat interval and daily schedule times.

How do you use this agent?

Join a project as an agent:

/join Chief of Staff

This generates .cortex.md, updates CLAUDE.local.md, and starts the heartbeat (polls for work every 15 minutes); the heartbeat restarts each session when /join runs. Register and onboard a worker:

/register Billing Dev

Then in the worker's project directory:

/join Billing Dev

Use /leave Billing Dev to remove .cortex.md, clean CLAUDE.local.md and mark the agent inactive. The configuration file ~/.cortex/config.yaml looks like:

team_dir: ~/cortex-team
heartbeat_minutes: 15
daily_briefing: "09:00"
daily_review: "18:00"
telegram_chat_id: "your-chat-id"
chief_of_staff_project: "~/Projects/chief-of-staff"

What are this agent's strengths and limitations?

Pros
  • The coordination layer is plain markdown, so Claude Code, Codex, Cursor, Gemini CLI and OpenCode can mix in one team thanks to documented adapters under docs/adapters/.
  • There is no direct agent-to-agent messaging, so workers can pick up tasks hours later and do not need to run at the same time as the chief of staff.
  • Task files have an explicit ready → in-progress → done lifecycle with Started/Completed timestamps, and git history preserves content pruned during the daily review.
  • Liveness tracking via <!-- cortex:last-tick --> lets the chief of staff spot agents that appear down while still holding active tasks, and the daily review prunes done tasks older than 7 days.
  • MIT licensed, with a clear team directory layout (agents/, projects/, templates/) that can live in an Obsidian vault, a git repo or any directory.
Limitations
  • The turnkey plugin path is tied to Claude Code; other runtimes require writing your own adapter against docs/protocol.md and the adapter examples.
  • There is no standalone daemon: the heartbeat only runs when a session starts via /join, so nothing polls if the session is not open.
  • Telegram is only a notification channel and requires the separate Claude Code Telegram plugin; Cortex itself just reads telegram_chat_id.
  • Multiple agents writing the same task file can race, and the documentation describes no locking or conflict-resolution mechanism.
  • ~/.cortex/config.yaml is a single global config file, so running multiple teams means changing global configuration.
  • Plugin installation depends on .claude-plugin/marketplace.json, and the non-Claude-Code adapters are examples rather than installable artifacts.

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

Agent Source review Form / cost Stars Updated Language Full support on
Cortex This agent 49 · Major gaps — ★ 13 7mo ago — Claude Code
RepoBrain – Repo Intelligence Engine 54 · Major gaps Agent plugin / skillFree + model costs ★ 1.4k 9d ago Python Codex · Claude Code
Ordewell 87 · Good CLIFree + model costs ★ 211 1d ago TypeScript Codex · Claude Code · OpenAI API · Claude API
Brigade 71 · Some gaps CLIFree ★ 83 today Python —

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Major gaps
49/ 100 5-point scale 2.5 / 5
Trust 12/29
Reliability 6/14
Adaptability 10/18
Convention 10/18
Effectiveness 7/13
Verifiability 4/8
Why each dimension lost points
Trust12 / 29 · 2.1/5

The README explains that coordination uses Markdown files in a shared team directory and that Telegram is handled by a separate plugin, making the main data flow partly visible. /setup asks for a directory and Telegram chat ID, while /join checks for a recent heartbeat and asks whether to start, providing some confirmation. Deductions: worker heartbeat instructions can continue tasks and edit task files; /leave deletes local files and hooks, and /setup writes configuration and directories, without detailed permission boundaries or confirmation for each effect. The configuration stores a Telegram chat ID, with no sensitive-data handling guidance. Dependency-security evidence is limited; external effects and recovery are only lightly covered; author fields exist, but publisher identity is unverified and no clear maintenance or security-update path is shown.

Reliability6 / 14 · 2.1/5

The README, skills, and metadata describe a Markdown protocol and Claude Code plugin without a runtime, with installation and workflow steps. However, /join says it automatically starts a heartbeat while CLAUDE.md describes skills as prompts with no runtime code; the relationship and cron capability dependency are not fully explained. The protocol spec and adapters are referenced but not included in this sample, so availability across runtimes cannot be confirmed. /join, /register, and /setup provide clear stop messages for missing configuration or registration; failure handling for other operations is not shown.

Adaptability10 / 18 · 2.8/5

The README targets users coordinating agents across projects and describes chief-of-staff, worker, Telegram, terminal, and remote-control scenarios. It says other runtimes can join through the protocol; skills distinguish coordinator from worker and define arguments and missing-configuration behavior. Deductions: cross-runtime support is represented by links and summary claims, while adapter details are outside the sample; heartbeat and Claude Code cron/hook behavior impose environment requirements that are not fully described.

Convention10 / 18 · 2.8/5

The repository layout, skill roles, and team-file formats are described clearly. The README includes installation, configuration, slug examples, and task-status examples; the MIT license agrees with the metadata. Deductions: limitations are only lightly documented (for example, reliance on a shared directory and a separate Telegram plugin), no release history is included, CLAUDE.md is contributor guidance rather than user documentation, and author fields do not establish maintenance responsibility or an update path.

Effectiveness7 / 13 · 2.7/5

The product places tasks, status, and session notes in readable shared Markdown files and provides registration, onboarding, offboarding, and periodic heartbeat workflows that support basic coordination. Templates and status examples make the format usable. Deductions: recurring polling, manual synchronization, and directory upkeep add ongoing work, and the documentation does not quantify those costs or identify suitable team sizes.

Verifiability4 / 8 · 2.5/5

Installation steps, paths, fields, and task-status examples make several feature claims traceable to concrete operations; the README, skills, and metadata partly corroborate the product name and version. Deductions: key protocol and adapter files are absent from the sample, and several capabilities appear only as claims in the README or skills. The material generally distinguishes procedures from descriptive claims, but does not systematically label unverified capabilities.

Risks and how to mitigate them
  • Worker heartbeat instructions allow agents to continue tasks and edit task files automatically; review task content and project permissions before use.
  • The README says /leave removes .cortex.md, cleans local configuration, and marks team status inactive. Daily housekeeping also deletes completed tasks older than seven days; confirm directory versioning and recovery arrangements.
  • Configuration stores a Telegram chat ID, and Telegram integration depends on a separate plugin; check configuration access and external message routing.
Evidence confidence: Low Reviewed Nov 08, 2026 Reviewed revision 6ba5646e1bf2
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/cortex.svg)](https://followagents.com/en/agents/cortex)
<a href="https://followagents.com/en/agents/cortex"><img src="https://followagents.com/badge/cortex.svg" alt="FARS review"></a>

FAQ

Does Cortex cost anything?
Cortex itself is an MIT-licensed open-source project and is free to use; the agents still need a model, so you supply the quota or API keys for Claude Code or whichever runtime you use.
Can I use it without Claude Code?
Yes. The protocol is runtime-agnostic: docs/protocol.md defines the team directory format, agent notes, task files and coordination rules, and docs/adapters/ ships examples for Codex, Cursor, Gemini CLI, OpenCode and a generic adapter. Those paths require you to implement polling and task-state updates yourself.
Is Telegram required?
No. telegram_chat_id is optional; Telegram is handled by the separate Claude Code Telegram plugin and Cortex only needs the chat ID to know where to send messages. Without it, you interact with the chief of staff through the terminal or remote control.
Will my task files and session logs be deleted?
The daily review deletes done tasks older than 7 days and trims session logs to the latest entry per agent. The team directory should therefore be a git repo, so pruned content remains retrievable from git log.
What happens if a worker agent goes down mid-task?
Agents update the <!-- cortex:last-tick --> timestamp in their task file; the chief of staff uses it to detect agents holding active tasks with an expired heartbeat and treats them as likely down.
Is Cortex open source?
Yes. The source code is on GitHub (agentweave/cortex) under the MIT licence.
Is Cortex safe to use?
FollowAgents' FARS review (Nov 08, 2026) scored Cortex 12/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is Cortex still maintained?
The GitHub repository has had no commits since 2026-04-07, more than six months ago. That can mean the project is finished or abandoned; check its issues before relying on it.
Who makes Cortex?
Cortex is published on GitHub by the account agentweave. FollowAgents has not verified which person or company is behind that account.
What is Cortex's official website?
The project's GitHub repository lists https://agentweave.github.io/cortex/ as its website. That link is set by the repository owner; the source code itself is on GitHub (agentweave/cortex).
Was this page helpful?
View on GitHub ↗ Install ↓

Host ecosystems

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts