Cortex

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

Stars
★ 12
Last updated
5mo 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.

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.

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 42 · Major gaps — ★ 12 5mo ago — Claude Code
RepoBrain – Repo Intelligence Engine 49 · Major gaps Agent plugin / skillFree + model costs ★ 1.3k 17d ago Python Codex · Claude Code
Brigade 87 · Good CLIFree ★ 72 1d ago Python —
AI Doc Gen (Divar) 50 · Major gaps CLIFree + model costs ★ 763 2mo ago Python Claude Code · OpenAI API

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Major gaps
42/ 100 5-point scale 2.1 / 5
Trust 10/29
Reliability 6/14
Adaptability 9/18
Convention 8/18
Effectiveness 6/13
Verifiability 3/8
Why each dimension lost points
Trust10 / 29 · 1.7/5

The README clearly states agents never communicate directly and all coordination flows through a shared markdown directory, giving decent data-flow transparency (data_flow_transparency=2). Least privilege is only implied at the file read/write level; no sandbox, path scope, or command-execution boundaries are defined (least_privilege=1). /setup, /register, and /join create directories, write ~/.cortex/config.yaml, and modify CLAUDE.local.md, yet no confirmation or dry-run prompt is described (user_confirmation=1). Telegram chat IDs and config are written to local files with no discussion of sensitive-data storage or redaction (sensitive_data_handling=1). Heartbeat polling, daily briefings, and automatic deletion of done tasks older than 7 days are described but lack consent and recovery mechanisms (external_effects=1). Rollback relies only on the recommendation that the team directory be a git repo and that git log preserves history; no explicit rollback procedure is provided (rollback=1). No dependency manifest or lockfile is present, so dependency security cannot be assessed (dependency_security=0). Source attribution points to agentweave and the Shuttle Protocol link, but publisher identity is unverified (source_attribution=1).

Reliability6 / 14 · 2.1/5

The README is internally consistent: protocol, task status lifecycle, slug rules, and directory structure align (self_consistency=2). Dependency availability is uncertain because installation depends on the Claude Code plugin marketplace and an external Telegram plugin, and referenced files such as docs/protocol.md and docs/adapters/ are not present in the evidence (dependency_availability=1). Failure messaging is limited to the chief detecting stale agents as likely down; there are no error codes, logs, or recovery guidance (failure_messages=1).

Adaptability9 / 18 · 2.5/5

Audience and scenarios are well described, covering Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and a generic adapter (audience_and_scenarios=2). Capability boundaries only state that agents do not talk directly; the scope of permitted actions or prohibitions is not defined (capability_boundaries=1). Trigger precision is partial: heartbeat interval and daily briefing/review times are configurable, but task status matching rules are coarse (trigger_precision=1). Environment fit is good, as the team directory can be an Obsidian vault, a git repo, or any directory, and mixed runtimes are supported (environment_fit=2).

Convention8 / 18 · 2.2/5

Information architecture is clear, with well-organized README sections, plugin structure, directory structure, and skill reference (information_architecture=2). Install notes are concrete, providing both local and GitHub marketplace install commands (install_notes=2). Naming stability is good, with a slug derivation table and examples (naming_stability=2). Examples and FAQ are thin: only task-file examples exist, with no FAQ or troubleshooting (examples_and_faq=1). Known limitations are entirely absent, e.g., concurrent write conflicts, markdown parsing ambiguity, or race conditions from multiple agents polling (known_limitations=0). The MIT license is complete (license=2). Version 0.4.0 appears in package.json, but there is no CHANGELOG or version history (versioning_changelog=1). Maintenance responsibility is only an agentweave author field, with no maintainer contact or governance notes (maintenance_responsibility=1).

Effectiveness6 / 13 · 2.3/5

Output usability is good: task file format, status lifecycle, and briefing mechanics are concrete and directly consumable by agents (output_usability=2). Marginal value is limited: using markdown files as a message bus is lightweight, but the incremental benefit over native runtime task orchestration is not quantified (marginal_value=1). Cost-benefit is unclear: maintaining the team directory, heartbeat polling, and daily reviews implies cost, but neither cost nor benefit is compared against alternatives (cost_benefit=1).

Verifiability3 / 8 · 1.9/5

Claim traceability is partial: the README claims runtime-agnostic operation and out-of-the-box mixed teams, but the supporting docs/protocol.md and adapter docs are not in the evidence (claim_traceability=1). Cross-source corroboration is limited to README, LICENSE, and package.json; the package.json skills list roughly matches the README skill descriptions, but there are no tests or code to corroborate (cross_source_corroboration=1). Fact-inference separation is acceptable: the README distinguishes protocol spec from implementation details, though phrases like 'works out of the box' remain unverified inference (fact_inference_separation=1).

Risks and how to mitigate them
  • Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
  • No dependency manifest or lockfile is provided, so third-party dependency security cannot be assessed.
  • Installation and setup write ~/.cortex/config.yaml and modify CLAUDE.local.md without any described confirmation or dry-run mechanism.
  • Destructive operations such as deleting done tasks older than 7 days and trimming session logs rely only on git history, with no explicit rollback procedure.
  • Referenced files docs/protocol.md and docs/adapters/ are absent from the evidence, so claims of runtime-agnostic operation and out-of-the-box mixed teams cannot be verified.
  • Known limitations such as concurrent write conflicts, markdown parsing ambiguity, or multi-agent polling races are not discussed.
  • Publisher identity is unverified, and maintenance responsibility and update path are unclear.
Evidence confidence: Low Reviewed Sep 26, 2026 Reviewed revision 6ba5646e1bf2
See the full review method →

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.
View on GitHub ↗ Install ↓

Compare agents like this one

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

Related agents