Choose the workflow before your coding agent starts building.
Cortex gives your coding agent a repeatable way to choose a workflow, specialists and effort level, then record the decision and outcome.
Cortex is Markdown instructions plus a Python CLI. Your coding agent follows the instructions to choose how to approach a task. The CLI keeps a local record of its choices, retrieves past routes and helps you review what happened. The core protocol runs with your existing agent and local tools; the optional hosted adviser is off by default.
You ask your agent to refactor authentication middleware. Before implementation, it declares a route and explains the verification it needs:
Direct > plan-and-verify @ L3
Reason: changing authentication behavior needs a plan and a verifier pass.
The agent logs that decision, does the work and records the outcome. You can inspect the route later or redirect it while the work is underway.
This is an illustrative example. The route depends on the capabilities available in your session and the work you request. Cortex does not execute the workflow itself or automatically switch models.
Cortex is useful when you already use several agent workflows and want a consistent way to choose among them.
| When you ask for… | The protocol helps your agent… |
|---|---|
| A small fix | Keep the approach proportional and use a focused check. Trivial edits skip the full routing ceremony. |
| A risky refactor | Explain why deeper planning and verification are needed. |
| Work across design, backend or other disciplines | Use available specialists for independent concerns and reconcile their results. |
| A review of past decisions | Inspect the chosen workflows, effort levels, corrections and outcomes. |
Start with the tools you already have. You can add workflow systems to your registry as you adopt them.
The guided path below is for Claude Code on macOS or Linux, with Python 3 and Git available. For other agents, see integration options.
1. Install the instructions, CLI and skills.
git clone https://github.com/amitvijapur/cortex.git
cd cortex
./install.shThe installer preserves an existing cortex.md and checks for skill conflicts before copying. See what gets installed for destinations, custom paths and conflict handling.
2. Activate Cortex and build your registry.
Add @cortex.md once to ~/.claude/CLAUDE.md, preserving your existing instructions. Start a fresh Claude Code session, then run:
/cortex-init
The skill discovers your tools, asks about ambiguous choices and proposes a Workflow Registry. It backs up an existing registry and asks for confirmation before writing changes. Only register capabilities your session can actually use.
/cortex-init is an agent-led setup skill. The Python command cortex init performs discovery only.
3. Check setup and try one task.
python3 ~/.claude/bin/cortex doctor --no-probeResolve any setup issues it reports. Then ask your agent:
Review the error handling in this project. Follow Cortex, use only available
capabilities and record the outcome when finished. A direct review is fine.
Before the review, look for a declared workflow, effort tier and reason. After it finishes, inspect the record:
python3 ~/.claude/bin/cortex show --last 3Your task should appear with its route, effort level and outcome. If it does not, check that the instructions loaded and the agent used the CLI. Setup and troubleshooting →
For non-trivial tasks, the agent follows a short protocol:
- Understand the task and choose the rigor. Classify the work and decide how much planning and verification it needs.
- Choose an available workflow. Consult past routes, pick appropriate tools and specialists, then declare and log the decision before implementation.
- Do the work and record the result. Capture the outcome and any correction so you can review the choice later.
| Tier | Approach | Verification |
|---|---|---|
| L1 · Reflex | Direct action for trivial work | Focused check |
| L2 · Standard | A bounded workflow, the default | Spot-check |
| L3 · Deep | Plan and verify | Verifier pass |
| L4 · Max | Iterate until verified | Full verification loop |
Tiers describe rigor, not provider models. Parallel work depends on independent concerns and available agents. More specialists do not automatically mean a higher tier. Routing rules and full protocol →
The instructions occupy context whenever your agent loads them. Keep the registry focused, retain a short routing index and load detailed system notes on demand. Registry design and context overhead →
Routes, outcomes and corrections are separate events in a local, append-only log. You can inspect what the agent first chose and how that choice changed.
hint retrieves recent distinct routes as evidence for the next decision. learn identifies recurring patterns and proposes registry changes for review. Outcomes inform the reader; they do not train a model or rank the hints. Registry improvements require your approval. History, hints and reviewed learning →
The protocol can be adapted to agents that read instruction files and can run the CLI. Setup differs by host:
| Agent | Setup path |
|---|---|
| Claude Code | Guided /cortex-init setup; framework loaded from CLAUDE.md. |
| Codex | Manual AGENTS.md integration. Existing Codex homes also receive log, learn, reroute and delegation skills. |
| Cursor, Gemini CLI, Aider, Windsurf | Manual integration through the agent's rules or instruction configuration. |
The installer currently provides the initialization skill to Claude Code only. A registry entry must match tools that are callable in the current host. Other-agent setup and shared state →
Cortex includes checks for protocol adherence, routing consistency and agent retrieval. They can expose drift between a declared route and recorded behavior.
These checks catch regressions. They do not establish that a route was optimal, that Cortex saves tokens or that it improves delivery speed. The core protocol relies on the host agent following its instructions. Evaluation methods and limits →
| Guide | What you will find |
|---|---|
| Setup | Install destinations, other agents, custom state, troubleshooting and the optional session-start audit. |
| CLI reference | Logging, hints, outcomes, corrections, history and checks. |
| Routing | Protocol, calibration, parallel work and capability boundaries. |
| Registry | Adding workflows, managing context and ecosystem examples with credits. |
| History and learning | Event schema, corrections, hints and reviewed proposals. |
| Evaluation | What the checks measure, their limits and rejected experiments. |
Optional resources include the Jev routing adviser, which is off by default and has no demonstrated routing advantage in the local pilot, skill-use evidence, and the Frontend Design Library.
Issues and pull requests are welcome. Include a concrete task, the expected behavior and what you observed. For documentation changes, check local links and keep examples consistent with the CLI. For routing changes, read the routing guide and run the relevant evaluation checks.
Maintainers can find the running work log and lessons in maintainer notes.
Cortex routes between tools built by their own maintainers. The ecosystem examples and credits link to those projects. They are optional examples you can adapt to your own setup.
MIT. Use it, fork it and adapt it to your workflow.