Related Pages

Related topics: Core Agent Architecture, Context Management & Model Integration, Built-in Tools, MCP, Skills, Permissions & Sandbox, Cortex Code CLI, TUI, Discovery & Operations

Project Overview & Getting Started

Cortex Mono is a TypeScript-based monorepo that hosts a collection of AI-related packages under a unified workspace. The repository is structured around npm workspaces and is intended to be the canonical location for the "cortex" ecosystem of libraries, including the core cortex package and the cortex-code extension package.

Purpose & Scope

The repository serves as the centralized source-of-truth for the cortex project family. Its purpose is to:

• Provide a single coordinated workspace where multiple related packages live side-by-side.
• Enable shared development tooling (formatting, linting, building, testing) across all packages via the root configuration.
• Document how individual packages fit into the larger ecosystem.

According to the root README, the repository hosts several packages including cortex and cortex-code, both of which are actively developed within this monorepo Source: README.md:1-40. The root package.json defines the workspace layout as "workspaces": ["packages/*"], indicating that any directory directly under packages/ is treated as a workspace member Source: package.json:1-50.

Repository Structure

The monorepo follows a conventional packages/* layout. Each package contains its own package.json and README.md describing its individual scope and usage. The root package.json is minimal and primarily orchestrates the workspaces rather than shipping runnable code itself Source: package.json:1-50.

Core Packages

`cortex`

The cortex package is positioned as the foundational library of the ecosystem. Its package manifest is the defining source for its runtime metadata, dependencies, and entry points Source: packages/cortex/package.json:1-50. The package ships its own README documenting its individual purpose and usage instructions, which should be consulted when working with the library directly Source: packages/cortex/README.md:1-40.

`cortex-code`

The cortex-code package builds on top of the core and is targeted at code-related AI workflows. Like cortex, it is configured as an independent workspace member with its own manifest and README Source: packages/cortex-code/package.json:1-50. Its README describes package-specific behavior and serves as the entry point for users of this sub-package Source: packages/cortex-code/README.md:1-40.

Development Tooling & Workflow

The root package.json registers workspace-wide npm scripts that operate across all packages simultaneously. By relying on the workspaces field, contributors can install dependencies once at the root and have them propagate to every package Source: package.json:1-50. This is the standard npm workspaces pattern and is the recommended way to bootstrap a development environment.

Typical contributor workflow:

1. Clone the repository and run the package manager's install command at the root; npm resolves and links all workspaces defined in packages/* Source: package.json:1-50.
2. Read the root README.md for any project-wide conventions or contribution notes Source: README.md:1-40.
3. Navigate into a specific package (for example packages/cortex or packages/cortex-code) and consult its individual README for package-level commands, configuration, and usage examples Source: packages/cortex/README.md:1-40 Source: packages/cortex-code/README.md:1-40.
4. Run root-level scripts to execute tooling across every workspace at once.

flowchart TD
    A[Clone cortex-mono] --> B[npm install at root]
    B --> C{Workspace resolves packages/* }
    C --> D[packages/cortex]
    C --> E[packages/cortex-code]
    D --> F[Read packages/cortex/README.md]
    E --> G[Read packages/cortex-code/README.md]
    F --> H[Run package-level scripts]
    G --> H
    H --> I[Run root-level scripts across all workspaces]

Getting Started Checklist

Before contributing or integrating, ensure the following:

• The repository uses npm workspaces; any tooling that supports npm workspaces (npm CLI, pnpm with workspace config, yarn classic) can be used, but the canonical configuration is npm Source: package.json:1-50.
• Each package's README is authoritative for that package's API surface, commands, and dependencies Source: packages/cortex/README.md:1-40 Source: packages/cortex-code/README.md:1-40.
• The root README provides top-level context and lists the packages contained in the monorepo Source: README.md:1-40.

This page intentionally stops at the project-wide entry point. For deeper information on any individual package, refer to the dedicated wiki pages for cortex and cortex-code, or directly read each package's own README and package.json listed above.

Related Pages

Related topics: Project Overview & Getting Started, Built-in Tools, MCP, Skills, Permissions & Sandbox

Core Agent Architecture, Context Management & Model Integration

Purpose and Scope

The Cortex core stack defines how an autonomous agent reasons over long-running sessions, manages the context window it presents to a language model, persists durable knowledge across sessions, and routes requests to the appropriate model provider. The system is designed to separate the agent reasoning loop from the transient context state, while keeping the boundary to underlying model providers thin enough to swap vendors or tiers without rewriting agent code. Source: docs/cortex/cortex-architecture.md:1-40

The scope covers four concerns that together form the agent's runtime:

• The reasoning loop that drives tool use and message production.
• The context windowing layer that decides what to send to the model.
• The memory substrate that survives context compaction.
• The model provider abstraction that hides API differences.

Anything outside this loop — UI, transport, persistence backends for memory — is intentionally out of scope for the docs in this folder. Source: docs/cortex/cortex-architecture.md:42-58

Agent Loop and State Boundaries

The Cortex agent follows a standard perceive–reason–act cycle, but the documentation explicitly splits the cycle into three cooperating components: the agent core, the context manager, and the provider manager. The agent core is responsible only for sequencing — it calls the context manager to assemble a prompt, hands it to the provider manager, parses the model's reply into tool calls, and either invokes tools or terminates. Source: docs/cortex/cortex-architecture.md:60-95

State is held in three layers, each with a different lifetime:

Source: docs/cortex/cortex-architecture.md:97-120

flowchart LR
  A[Agent Core] -->|assemble prompt| B[Context Manager]
  B -->|compacted messages| A
  A -->|completion request| C[Provider Manager]
  C -->|model reply| A
  A -->|tool invocation| D[Tools]
  D -->|observation| B
  B -.->|flush summaries| E[Observational Memory]

The agent core never reads raw message history directly; it always goes through the context manager. This invariant is what allows compaction and memory flushes to happen transparently. Source: docs/cortex/context-manager.md:12-30

Context Management and Compaction

The context manager owns the prompt sent to the model on every turn. It treats the conversation as a stream of typed segments — system prompt, tool definitions, recent turns, recalled observations, and a tail of most-recent user/assistant exchanges — and packs them into a budget measured in tokens rather than messages. Source: docs/cortex/context-manager.md:32-58

When the projected token cost exceeds the configured budget for the active model tier, the compaction strategy is invoked. Compaction is not a single operation; it is a pipeline of progressively cheaper transformations applied in order:

1. Trimming of redundant tool outputs.
2. Summarization of older turns into a single condensed block.
3. Offloading of high-value facts into observational memory before they are dropped from the window.
4. Hard truncation of any remaining overflow as a last resort.

Source: docs/cortex/compaction-strategy.md:20-60

Observational memory is the durable companion to compaction. Instead of storing verbatim transcripts, the memory subsystem stores structured observations — facts, preferences, resolved tasks — produced by a dedicated summarization pass that runs alongside compaction. On later turns, the context manager can recall these observations by topic and inject them as a prepend block ahead of recent turns. Source: docs/cortex/observational-memory-architecture.md:14-45

The compaction strategy is intentionally conservative: it prefers keeping recent turns intact and instead summarizes or offloads older content, because recent context is empirically more predictive of the next tool call. Source: docs/cortex/compaction-strategy.md:62-78

Model Integration and Provider Routing

The provider manager is the single seam between the agent and any language model backend. It exposes a uniform completion interface that accepts a normalized request — messages, tool definitions, sampling parameters — and returns a normalized response — text, tool calls, usage metadata — regardless of whether the underlying provider is OpenAI-compatible, Anthropic, a local inference server, or a routing proxy. Source: docs/cortex/provider-manager.md:1-35

Models are not configured as flat strings but as tiers. Each tier bundles a provider, a model identifier, a context budget, and policy hints such as whether the tier supports tool use, vision, or extended reasoning. The agent core and context manager consult the active tier to decide how aggressively to compact and which tool schemas to expose. Source: docs/cortex/model-tiers.md:1-30

Typical tier roles documented in the project include a fast/cheap tier for routine turns and tool-result processing, a reasoning tier for planning and synthesis, and a long-context tier used when recalled observations exceed the default budget. The provider manager resolves the tier name to a concrete endpoint at call time, which means swapping a tier — for example, to route through a different provider for cost reasons — requires no agent code changes. Source: docs/cortex/model-tiers.md:32-65, docs/cortex/provider-manager.md:37-60

Failures from a provider surface as typed errors rather than raw HTTP exceptions, and the provider manager is responsible for translating between vendor-specific error shapes and the agent's internal error vocabulary. This keeps the agent core free of vendor conditionals and is what allows observational memory, compaction, and tier selection to compose cleanly. Source: docs/cortex/provider-manager.md:62-80

Related Pages

Related topics: Core Agent Architecture, Context Management & Model Integration, Cortex Code CLI, TUI, Discovery & Operations

Built-in Tools, MCP, Skills, Permissions & Sandbox

The Cortex CLI exposes a layered tool system that lets the model interact with the user's machine safely and predictably. At the base layer sit built-in tools (filesystem reading, searching, editing, and shell execution). Above them sit MCP servers that contribute additional tools via the Model Context Protocol. Around both layers, Cortex layers a Skills system for packaging reusable workflows, a Permissions system that gates sensitive actions, and a Sandbox that constrains where shell commands and edits may operate.

Built-in Tools

The built-in tools are documented individually under docs/cortex/tools/. They form the minimal surface the agent needs to inspect and modify a project.

The README introduces this set and explains how each tool is invoked from the agent loop. Source: docs/cortex/tools/README.md:1-40

Filesystem tools

read retrieves file contents and supports reading portions of large files by offset and line count, enabling the model to navigate repositories without loading entire files into context. Source: docs/cortex/tools/read.md:1-40

edit performs targeted, surgical modifications to a file by matching an exact string and replacing it. It rejects ambiguous or non-unique matches rather than guessing, which keeps the model from corrupting files when patterns recur. Source: docs/cortex/tools/edit.md:1-40

Discovery tools

glob expands shell-style patterns against the working directory so the agent can locate files by name. Source: docs/cortex/tools/glob.md:1-30 grep runs a regex search over file contents with file-glob filtering, supporting both literal and pattern-based searches across a codebase. Source: docs/cortex/tools/grep.md:1-40

Shell tool

bash runs arbitrary shell commands and returns their combined stdout/stderr along with an exit code. It is the most powerful built-in tool because it inherits the user's environment, which is why every bash call is subject to the permissions layer described below. Source: docs/cortex/tools/bash.md:1-40

MCP (Model Context Protocol) Integration

Beyond the built-ins, Cortex can attach to MCP servers that publish additional tools through the Model Context Protocol. MCP servers are configured per-project and contribute their tool definitions into the same namespace the model sees, so the agent does not have to distinguish between a built-in and an MCP-provided tool at call time. The Permissions and Sandbox layers apply uniformly across both. Source: docs/cortex/tools/README.md:40-90

Skills

Skills bundle a sequence of tool invocations and instructions into a named, reusable unit. A skill encapsulates a workflow that the model would otherwise have to rediscover each session — for example, "investigate a failing test" or "prepare a release." The Skills system is layered on top of the tool layer: a skill is not a new primitive the model can call directly, but a packaged pattern that drives the existing tools. Source: docs/cortex/tools/README.md:90-130

Permissions & Sandbox

Every tool invocation that could affect the user's system — notably bash, edit, and any destructive MCP tool — flows through Cortex's permissions and sandbox controls before it executes.

Permissions. Before a sensitive tool runs, Cortex evaluates whether the action is allowed under the current policy (allow-list, deny-list, or interactive prompt). Actions that would write files, execute shell commands, or contact the network fall under this gate. The policy is consulted uniformly for built-in tools and MCP tools. Source: docs/cortex/tools/README.md:130-170

Sandbox. When an action is permitted, the sandbox determines *where* it may run. Filesystem and shell operations are constrained to the project working directory by default, preventing the model from reaching outside the user's project. The sandbox is the enforcement arm of the permissions system: policy decides *whether*, the sandbox decides *where*. Source: docs/cortex/tools/README.md:170-210

Together, these two layers mean a tool call is only executed when (a) policy permits the action class and (b) the sandbox confirms the target lies within the allowed scope. The bash tool is the primary example: it is gated by both layers on every invocation. Source: docs/cortex/tools/bash.md:1-40

Related Pages

Related topics: Project Overview & Getting Started, Built-in Tools, MCP, Skills, Permissions & Sandbox

Cortex Code CLI, TUI, Discovery & Operations

Cortex Code is the CLI-first, agentic coding surface of the Cortex mono-repository. It pairs a non-interactive command-line interface with a rich terminal user interface (TUI), exposes repository and workspace discovery as first-class operations, and coordinates the operational loop that drives an LLM agent against a project. This page summarizes the purpose, architecture, and operational design of that surface, drawing strictly from the in-repo design documents.

Purpose and Scope

Cortex Code is positioned as the primary developer entry point into the Cortex platform. The product vision calls for a CLI that is fast, scriptable, and approachable, while still offering a polished interactive experience when the user wants it. Source: docs/cortex-code/product-vision.md.

Its scope covers:

• Workspace discovery — finding projects, manifests, and configuration.
• Interactive sessions — driving an agent loop with rich terminal rendering.
• Headless operation — running the same capabilities in CI, scripts, and automation.
• Operations — tool execution, context assembly, and tool-result handling surfaced to the user.

The CLI is the unified surface: every interactive feature is also reachable from a flag-driven command, and every command can be promoted into an interactive session.

Architecture Overview

The architecture document separates concerns into a small number of cooperating subsystems. The CLI parser and command dispatcher sit at the top, dispatching into either a non-interactive executor or the interactive TUI runtime. Both share a common context engine that assembles the inputs for the model, and a tool runner that executes the model's selected tools and returns structured results. Source: docs/cortex-code/architecture.md.

flowchart LR
  User[User / Shell] --> CLI[CLI Parser & Dispatcher]
  CLI -->|non-interactive| Exec[Headless Executor]
  CLI -->|interactive| TUI[TUI Runtime]
  TUI --> Engine[Context Engine]
  Exec --> Engine
  Engine --> Model[LLM Provider]
  Model --> Tools[Tool Runner]
  Tools --> Renderers[Per-Tool Renderers]
  Renderers --> TUI
  Tools --> Exec

Key invariants in this design:

• A single context-engine implementation is reused by both headless and interactive modes. Source: docs/cortex-code/context-design.md.
• Rendering is decoupled from tool execution: tools return structured data, and the TUI decides how to display them. Source: docs/cortex-code/per-tool-renderers.md.
• Discovery is a tool like any other, so the same discovery operations work in batch mode and inside an interactive session.

CLI, Discovery, and Headless Operations

The CLI is structured around subcommands that map to operations: workspace selection, session start, tool invocation, and status queries. Discovery in particular is treated as a typed operation: the CLI can list workspaces, inspect their manifests, and resolve which Cortex project a directory belongs to, all without entering the TUI. Source: docs/cortex-code/architecture.md.

Headless operation is not a separate code path. The same executor that powers interactive turns also runs when the user passes a one-shot command, so behavior stays consistent. This is also why context assembly has a single implementation rather than parallel interactive/batch variants. Source: docs/cortex-code/context-design.md.

Operational concerns covered by the CLI include:

• Resolving and caching the active workspace.
• Constructing the initial context from files, configuration, and prior session state.
• Running a single agent turn and emitting a structured result.
• Streaming tool output to stdout in a scriptable form while the TUI is not attached.

TUI Design and Per-Tool Rendering

The TUI is designed to feel responsive even while the model is generating, by separating *transport* from *presentation*. Tool calls arrive as structured records, and a per-tool renderer turns each record into the right visual widget — diffs for edits, tables for search results, fenced blocks for file reads, and so on. Source: docs/cortex-code/tui-design.md and docs/cortex-code/per-tool-renderers.md.

The renderer registry is open: new tools register a renderer rather than the core loop growing conditionals. This keeps the interactive loop small and makes it straightforward to add tools without regressing the UI. The TUI also owns input handling — keystrokes for queuing messages, cancelling a turn, scrolling history, and toggling panes — all routed through a single input dispatcher. Source: docs/cortex-code/tui-design.md.

A related concern is terminology: historical code referenced a "loop" abstraction that has been renamed to "context" to better reflect its role as the assembled state handed to the model. The migration document tracks this rename so that operators reading older guides or logs can still map concepts. Source: docs/cortex/loop-context-terminology-migration.md.

Putting It Together

Operationally, a typical Cortex Code invocation follows a predictable path: the CLI resolves the workspace, the context engine assembles inputs, the model proposes tool calls, the tool runner executes them, and the per-tool renderers present the results — either inline in the TUI or as structured output on stdout. Because the same components serve both modes, automation written against the CLI transfers directly into interactive use, and interactive sessions can be driven non-interactively when needed. Source: docs/cortex-code/architecture.md, docs/cortex-code/context-design.md, docs/cortex-code/tui-design.md, docs/cortex-code/per-tool-renderers.md, and docs/cortex/loop-context-terminology-migration.md.

Doramagic Pitfall Log

Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Identity risk - Identity risk requires verification.

1. Identity risk: Identity risk requires verification

• Severity: medium
• Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/Craigtut/cortex-mono

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Craigtut/cortex-mono

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Craigtut/cortex-mono

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Craigtut/cortex-mono

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Craigtut/cortex-mono

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Craigtut/cortex-mono

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Craigtut/cortex-mono

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Craigtut/cortex-mono

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using cortex-mono with real data or production workflows.

• Identity risk requires verification - GitHub / issue