---
name: cortex-connect
description: "EXPLICIT INVOCATION ONLY. Connect Cortex to the current repository. Use only for /cortex-connect or an explicit request to connect Cortex to a project."
user-invocable: true
disable-model-invocation: true
---

# Cortex Connect

Create or select a brain for the current repository and connect Claude Code and Codex.

## Usage

```text
/cortex-connect
/cortex-connect --name <brain-name>
```

Accept only the optional `--name`. Its value must be nonempty and have no surrounding whitespace; never trim or reinterpret it.

## 1. Inspect

Run:

```sh
cortex-local connect --inspect
```

The command returns the project root, its current brain binding, and a suggested name.

Choose the brain name in this order:

1. the explicit `--name`;
2. the current binding;
3. for an unbound repository, ask the user to use the suggested name, enter another name, or cancel.

Tell an unbound user that choosing an existing name shares that brain. If the chosen name differs from the current binding, show both names and obtain confirmation before continuing.

## 2. Propose

Read the README, primary manifests, top-level source layout, and only the domain or architecture documents needed to understand the repository. If the user's main goal is still unclear, ask at most one question: understanding the code, modeling the domain, tracking work, or a balanced default.

Read [the schema v4 reference](references/schema-v4.md). Prepare one flat YAML document with:

- `schema_version: 4`;
- `brain.name` exactly equal to the chosen name;
- usually 3–6 repository-specific note types;
- only useful relationships and fields;
- a full-text `search` query;
- at least one query serving the user's stated goal.

Do not use retired fields such as `grounding` or `query_engine`. Show the name, information kinds, relationships, and ways to find information. Incorporate requested corrections or stop if the user cancels. Show the full YAML only when asked, and do not write a schema file.

## 3. Apply

Pipe the accepted YAML to:

```sh
cortex-local connect --yaml -
```

For a confirmed rebind, append `--rebind-from <current-binding>`, passing the current binding as one shell-escaped argument. Never supply that option without the confirmation from step 1.

The command owns repository selection, validation, brain registration or adoption, project-local MCP and lifecycle-hook configuration, and the final repository binding. Do not reproduce those operations or edit their targets yourself. Do not create or modify agent instruction files, model selection, or configured system prompts.

Handle the command outcome without guessing:

- Success: report the returned brain and configured clients, tell the user to restart them, then verify with `query({"action":"catalog"})` after restart.
- Rebind confirmation required: show the returned old and new names; rerun only after confirmation.
- Stale project state: report the completed and pending effects exactly; do not retry automatically.
- Unknown registration outcome: no project files were written; permit only a user-approved rerun with the identical YAML and brain name.
- Any other error: report it exactly and stop.

Do not create seed notes unless asked. Changing an adopted brain's schema requires a later explicit `configure_brain(action: "evolve_schema")` request.