cortex: Instructions file for Codex

AGENTS.md

Instructions for AI agents (and humans) working on the cortex codebase. This is the canonical source-of-truth doc. README.md is the public-facing intro. Architecture, behavior, and contributor rules that must remain durable belong here. Design rationale and working notes belong in the Obsidian vault at ~/notes/projects/cortex/, not the repo.

Project Overview

cortex is a local-first, evidence-guided agent kernel for software-engineering agents. It sits between an LLM and a set of specialist tools (Bob, codemap, vecgrep, cairntrace, glyphrun, fcheap, vidtrace, tvault, veclite) and enforces a stateful reasoning loop:

orient → investigate → form hypotheses → declare a boundary → change → verify → preserve evidence

Cortex does not replace the model's planning or coding ability. It supplies what models are bad at preserving across long tool-using tasks: a durable case file, explicit evidence and uncertainty, disciplined tool routing, bounded changes, and verification tied to user-visible behavior.

Two surfaces over one kernel (the ecosystem pattern — cf. codemap/vecgrep):

• CLI — human commands and --json machine output for agents (Cobra + Charm v2 lipgloss).
• MCP server — cortex serve (stdio), a 23-tool agent profile by default; --profile all exposes the full 30-tool operator surface.

Product docs: docs/quick-start.md (humans), docs/mcp.md (agents). Monitor sessions with cortex sessions / cortex show --json instead of the removed Studio TUI (docs/studio.md).

Directory Structure

cortex/
├── cmd/cortex-trajectory/    # opt-in trusted empirical harness; separate from runtime/release CLI
├── cmd/cortex-trajectory-claude/ # reference arm launcher (Claude Code CLI, isolated raw_tools/cortex arms)
├── cmd/cortex/               # Cobra CLI, split per-command. Each RunE is THIN → builds a
│                             #   kernel (kernelFor) → calls internal/kernel. Files carry the
│                             #   header `/* Copyright © 2026 abdul hamid <[email protected]> */`.
│   ├── main.go               #   root command, persistent --workspace/-C and --json flags
│   ├── open / start / investigate / plan / change / verify / remember / status .go
│   ├── note / decision / handoff / doctor / serve .go
│   ├── longrunning.go        #   finding / dossier / coverage / workplan / resume / job command groups
│   └── render.go             #   lipgloss v2 styled view + --json emit (TTY-gated color)
├── internal/
│   ├── domain/               # core types — NO deps on adapters/store/transport
│   │   ├── case.go           #   CaseFile + Phase machine (transitions, invariants)
│   │   ├── acceptance.go     #   optional immutable criteria + transport-independent bounds
│   │   ├── evidence.go       #   Evidence, EvidenceKind, Confidence, Sensitivity
│   │   ├── hypothesis.go     #   Hypothesis + Disproof (the disproof-path gate)
│   │   ├── plan.go           #   Plan + planning-gate validation
│   │   ├── verification.go   #   typed claims + VerificationRecord + statuses
│   │   ├── lease.go decision.go # change ownership + resumable human decisions
│   │   ├── envelope.go       #   the shared MCP/CLI result envelope
│   │   ├── policy.go         #   routing matrix, budget, surface→verifier map
│   │   └── finding.go dossier.go coverage.go workplan.go job.go # long-running work records
│   ├── kernel/               # SHARED SERVICE LAYER — CLI + MCP both call this
│   │   ├── kernel.go         #   Kernel struct, evidence stamping, phase transition helper
│   │   ├── orient.go open.go #   new task + idempotent open/resume
│   │   ├── investigate.go    #   Investigate (route → discovery → candidates → structural expansion → record evidence)
│   │   ├── plan.go           #   Plan (rejects no-disproof / no-boundary plans)
│   │   ├── change.go lease.go #  explicit begin-change + bounded ownership
│   │   ├── verify.go assessment.go # typed verification + canonical task assessment
│   │   ├── persist.go        #   Remember (durable memory + summary.md + completion invariant)
│   │   ├── resolve.go        #   Resolve (confirm/challenge/reject a hypothesis)
│   │   ├── recall.go         #   Cross-case disproof recall: index hooks + recall
│   │   ├── observe.go decision.go handoff.go actions.go artifact.go # human/agent collaboration + projections
│   │   ├── status.go         #   Status / AbortTask / ReadEvidence / ListTasks
│   │   ├── scope.go          #   scope-drift detection vs the declared boundary
│   │   ├── freshness.go      #   evidence `commit` stamping + stale detection (git ChangedSince, bounded)
│   │   ├── finding.go dossier.go survey.go workplan.go checkpoint.go jobs.go # long-running work (docs/long-running.md)
│   │   └── jobs_unix.go jobs_other.go # detached worker spawn (Setsid) + terminate
│   ├── adapters/             # one file per tool; flat package sharing exec/redact plumbing
│   │   ├── adapter.go        #   Adapter interface, Request/Result/Fact, Capability/Status
│   │   ├── exec.go           #   runner (fakeable), timeout, redaction, ErrToolMissing
│   │   ├── registry.go       #   Registry + concurrent Health probe
│   │   ├── bob.go codemap.go vecgrep.go fcheap.go cairntrace.go glyphrun.go vidtrace.go tvault.go veclite.go command.go
│   │   └── util.go           #   pluralize / decodeJSON / clip helpers
│   ├── store/
│   │   ├── casefs/           #   JSON/JSONL case-file persistence ($XDG_STATE_HOME/cortex/sessions/<repo>/<id>/)
│   │   │                     #   + findings/coverage/workplan/jobs/checkpoint files and RepoStore (repos/<slug>/dossier.json)
│   │   └── redact/           #   secret-shape redaction (last-line filter before model output)
│   ├── mcp/server.go         # stdio MCP server — THIN pass-through (23 agent / 30 all; longrunning.go holds the six long-running tools)
│   ├── tui/board.go          # Legacy Charm v2 board (not wired to the CLI)
│   ├── config/               # XDG paths + cortex.yaml (budget/redact/cases_dir/recall/verifiers) + env
│   ├── ids/                  # time-sortable Crockford-base32 IDs (task_/ev_/hyp_/vr_/dec_/raw_)
│   ├── eval/                 # deterministic scorecard + separate opt-in trajectory runner contract
│   ├── forge/forge.go        # PR review action (ModeReview: PR fetch + APPROVE/REQUEST CHANGES verdict)
│   └── version/version.go    # Version/Commit/Date (ldflags-injected)
├── docs/                     # VitePress site (product docs ONLY) → deploy to Vercel
├── desktop/                  # Cortex Deck — Electron operator console over CLI+MCP+case store;
│                             #   no bundler/framework; own README, tests (node --test) and a
│                             #   headless smoke pass that screenshots every view
├── contracts/v1/             # public deterministic JSON/MCP conformance schema + fixtures
├── evaluations/              # trusted empirical manifests, repository fixtures, and independent oracles
├── specs/                    # glyphrun E2E specs (*.yml)
├── .github/workflows/        # ci.yml (test+race+build+lint+docs) · release.yml (goreleaser on tags)
├── Taskfile.yml .golangci.yml .goreleaser.yaml
└── README.md AGENTS.md CHANGELOG.md LICENSE