Quick Start

Install

go install github.com/abdul-hamid-achik/cortex/cmd/cortex@latest
# or from a clone:
task build   # → ./bin/cortex

Cortex is a single pure-Go binary, but Git is required for repository identity, diffs, scope drift, and revision-bound verification. The specialist tools it composes are optional — check what's available with:

cortex doctor

If you are developing Cortex from a clone, task doctor separately checks the development toolchain (Go, Task, Bun, Glyphrun, and lint tooling).

Anything missing simply degrades: the corresponding adapter reports tool_unavailable instead of fabricating output.

A full task, open to finish

Cortex tracks work as a case. Every action advances a phase machine and appends to the case file under $XDG_STATE_HOME/cortex/sessions/<repo>/<taskId>/ by default. Set cases_dir / CORTEX_CASES_DIR only when you want repo-local or custom storage; cortex config prints the resolved path.

1. Open — resume safely or start once

cortex open "Fix post-login checkout redirect" \
  --surface code --surface browser \
  --actor agent-auth --idempotency-key checkout-redirect

Cortex returns an existing case for the idempotency key, so retrying after a lost response cannot duplicate work. Without a key it resumes the newest active case matching the normalized goal, mode, workspace, and branch. Only a real first call records git identity, probes tool health, and creates the taskId; use cortex start when you intentionally want a new case.

2. Investigate — discover, then resolve structure

cortex investigate task_06FK… "where is the OAuth return URL handled"

The router sends vague behavioral questions to vecgrep (discovery) then codemap (structure) — discovery runs first, and what it found feeds into codemap (structure) as candidates. Each result is recorded as evidence with a confidence band — search hits are low/medium candidates, never proof.

3. Plan — the gate

cortex plan task_06FK… \
  --hypothesis "returnTo is dropped before callback :: run login-from-checkout browser flow" \
  --file src/auth/callback.ts --symbol HandleCallback \
  --uncertainty "unsure whether state signing also strips it"

The planning gate rejects any plan whose hypotheses lack a disproof path, and any change task that declares no boundary. The statement :: disproof shorthand pairs a hypothesis with how it could be falsified (or use paired --hypothesis / --disprove flags).

4. Begin change — claim the writer lease

cortex begin-change task_06FK… --actor agent-auth

The task enters changing under a 15-minute lease. A same-actor retry is safe; another actor is rejected while the lease is active. Renew long work with cortex lease renew … --actor agent-auth or release it deliberately with cortex lease release … --actor agent-auth.

5. Edit, then verify an exact claim

Make your edits within the declared boundary, then:

cortex verify task_06FK… \
  --claim "the OAuth callback preserves the return URL" \
  --claim-surface browser \
  --claim-verifier cairntrace \
  --claim-contract specs/cairntrace/checkout_return.yml \
  --actor agent-auth \
  --browser-spec specs/cairntrace/checkout_return.yml

The surface and contract make the proof obligation exact instead of guessing from the sentence. Verify runs the planned checks and detects scope drift. Each named claim gets a receipt; a claim whose exact verifier/contract did not run is not_run, never passed. Receipts bind to the current HEAD and dirty-tree digest, so later edits make them stale.

If the planned change intentionally produces no diff, pass --no-op. This acknowledges the no-op so verification may proceed; it does not create a pass or make the task verified.

6. Remember — complete the task

cortex remember task_06FK… \
  "returnTo was dropped from signed state; fixed and browser-verified" \
  --tag auth --tag oauth

Completion uses one canonical assessment: verified, partial, failed, or unverified. Normal completion requires verified. If adequate proof could not be completed and the assessment is partial or unverified, use --unverified; if it is failed, use --accept-failed. Cortex preserves the real assessment rather than letting an incomplete or failed outcome masquerade as a clean pass.

Inspect anytime

cortex status task_06FK… --detail full   # phase, hypotheses, scope drift, missing verification, tool health
cortex show task_06FK…                   # assessment, pending decision, first structured action
cortex list                              # all tasks, newest first
cortex read-evidence task_06FK… ev_06FK… # a full evidence record
cortex handoff task_06FK…                # bounded transfer packet for another person or agent
cortex studio                            # live read-only operator view across repos

Add --json to any non-interactive read command for machine output. Output is styled at a terminal and plain when piped. Studio is interactive; use sessions --json or show --json instead.