Cortex
Give your AI agents a chief of staff, coordinating them through plain markdown files.
- Source repo
- agentweave/cortex
- Stars
- ★ 12
- Last updated
- 5mo ago
- License
- MIT
- FA score
- 42/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformClaude CodeCodex · OpenAI API · Claude API (Partial support)
- You'll need
- 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.
- Source review
- 42/100 · Major gaps 1 safety controls not found
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.
- 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.
- 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.
- 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/.
- Worker agents cannot be online when the chief writes tasks and must pick up work later from the file queue on a heartbeat.
- You want an auditable assigned/started/completed timeline in the task files plus git history for previously pruned tasks.
- 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@agentweaveInstall from GitHub:
claude plugins marketplace add https://github.com/agentweave/cortex --scope user
claude plugins install cortex@agentweaveThe 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 StaffThis 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 DevThen in the worker's project directory:
/join Billing DevUse /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?
- 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.
- 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?
Why each dimension lost points
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).
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).
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).
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).
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).
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).
- 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.