CORA User Manual

Get started in 10 minutes

This guide walks you from registration to a working CORA setup. Follow the universal flow first, then complete the IDE-specific activation steps for your coding agent.

Prerequisites

Before installing CORA, make sure you have:

  • A registered Horizon Labs account with download access (Register to Download).
  • Docker installed and running (Docker Desktop on macOS/Windows).
  • An absolute path to your project workspace.
  • GitHub CLI is not required. The installer signs in with Cognito and brokers private binaries and GHCR pulls.
Windows users: run installer commands in PowerShell, not CMD or WSL, for the validated flow.

10-minute quickstart

These steps are the same on every platform. Replace placeholders with your project values. Current release: v0.1.4-beta.

Step 1 — Register and run bootstrap Complete registration, then download cora-installer for your OS from /cora/download and run it. Bootstrap downloads cora-cli into your user PATH (~/.local/bin on Unix, user Path on Windows).
macOS / Linux (bash/zsh)
chmod +x ./cora-installer-*
./cora-installer-* --version v0.1.4-beta
cora-cli version
Windows (PowerShell)
.\cora-installer-*.exe --version v0.1.4-beta
cora-cli version
Step 2 — Install CORA in your workspace

Run install from your repository root. This writes cora.<project>.yaml, MCP wiring, hooks, and skills.

macOS / Linux (bash/zsh)
export VERSION="v0.1.4-beta"
export PROJECT="myapp"
export WORKSPACE="/absolute/path/to/workspace"

cora-cli install \
  --project "$PROJECT" \
  --workspace "$WORKSPACE" \
  --version "$VERSION" \
  --accept-hooks \
  --non-interactive

cd "$WORKSPACE"
Windows (PowerShell)
$Version = "v0.1.4-beta"
$ProjectSlug = "myapp"
$RepoPath = "C:\path\to\workspace"

Set-Location $RepoPath

cora-cli install `
  --project $ProjectSlug `
  --workspace $RepoPath `
  --version $Version `
  --accept-hooks `
  --non-interactive
Step 3 — Refresh indexed context
macOS / Linux
cora-cli refresh --project "$PROJECT" --workspace "$WORKSPACE"
Windows (PowerShell)
cora-cli refresh --project $ProjectSlug --workspace $RepoPath --version $Version

GHCR authentication

Default path: run cora-installer or cora-cli login. Cognito brokers a short-lived GHCR credential; you do not need GitHub CLI or a personal PAT. Manual Docker login is only a fallback if brokered login is unavailable.

macOS / Linux
docker logout ghcr.io || true
read -s GHCR_PAT
echo "$GHCR_PAT" | docker login ghcr.io -u <github-username> --password-stdin
unset GHCR_PAT
Use the PAT owner username when logging in. On Windows, authenticate Docker with the same scopes before running install or refresh.

Verify setup

Confirm CORA is healthy before using it in your agent workflow.

macOS / Linux
cora-cli status --project "$PROJECT"
cora-cli doctor --project "$PROJECT"
Windows (PowerShell)
cora-cli status --project $ProjectSlug
cora-cli doctor --project $ProjectSlug
Expected: container/runtime checks pass, MCP config files exist, and refresh reports indexed files greater than zero.

IDE activation (after universal setup)

Installer writes agent config files automatically. Some clients still need one extra activation step.

Cursor

Uses .cursor/mcp.json directly after install. Restart Cursor and confirm the CORA MCP server is connected.

Claude Code

Installer writes .claude/settings.json. If Claude reports not configured, register once per project:

claude mcp add -s project cora-myapp docker -- <same docker args as generated config>
claude mcp list

OpenAI Codex

Installer writes .codex/config.toml and deploys .agents/skills/cora/SKILL.md. Ensure project-local Codex config is trusted so MCP settings load.

Use --accept-hooks to deploy context enforcement hooks. Add --accept-hooks-strict only when you want fail-closed pre-edit blocking. Without --agent, installer auto-detects available agent roots (.cursor, .claude, .codex). Use --agent all to force wiring for every supported agent.

Daily workflow with CORA

Before code edits, agents should use CORA MCP tools in this order:

  1. cora_application_context
  2. cora_file_context (for target files)
  3. cora_change_impact
  4. cora_patch_plan

Then apply the smallest safe change and run your normal validation checks.

Useful maintenance commands
# Re-index + enrich after major repo changes
cora-cli refresh --project <project_slug>

# Install + refresh in one command
cora-cli update --project <project_slug>

# Upgrade cora-cli binary
cora-cli upgrade --version <tag>

Troubleshooting

  • MCP not connected: run cora-cli doctor, then complete IDE-specific activation above.
  • Claude says “not configured”: run claude mcp add -s project ... once per project.
  • Stale context: run cora-cli refresh and retry MCP calls.
  • Private image pull failures: run cora-cli login, then retry cora-cli install. Manual GHCR PAT login is a fallback only.
  • CLI command missing: re-run bootstrap (cora-installer) or use cora-cli upgrade.
  • Windows refresh failures on older installers: upgrade to v0.1.4-beta or newer.

FAQ

What is the difference between update and upgrade?

update reinstalls/refreshes project runtime wiring and context. upgrade updates the cora-cli binary itself. Re-run bootstrap (cora-installer) only when you need a fresh CLI download.

Do I need to run install for every IDE?

No. One install can wire multiple agents. Use --agent all or let installer auto-detect .cursor, .claude, and .codex.

Where do I download CORA?

Use the registration-gated page at /cora/download.

What's new in v0.1.4-beta?

Local AI enrichment on your machine, a product scope beacon from your docs, clearer change guidance, and faster enrichment. See the release notes.

Ready to install CORA?

Register to download the installer, then follow this guide to activate CORA in your workspace.

Register to Download Back to product page