IDE extension — User guide

Home · Docs · Quick start · Install

Extension ID: franklee-dev.contorium
Display name: Contorium — AI Project Intelligence Layer
Requires: VS Code / Cursor 1.85+, folder workspace

The IDE is a peer PIL Runtime with MCP and CLI: sidebar UI, workspace scanning, .contora/ artifacts, Capture / Transfer, governance UI, and runtime dashboard bootstrap.

• Quick start · MCP · CLI · Install

PIL workflow (IDE)

MCP equivalents: capture_* · transfer_* · inspect_*

Command cheat sheet

Install

Option A: VSIX (recommended)

1. Get contorium-0.9.1.vsix (or current version):
   - GitHub Releases, or
   - Repo root: npm run vsix (Node.js 18+)
2. Open VS Code or Cursor
3. Extensions → … → Install from VSIX…
4. Select the .vsix file
5. Developer: Reload Window

Option B: Run from source (development)

git clone https://github.com/ContoriumLabs/contorium.git
cd contorium
npm install
npm run compile

Open the repo in VS Code/Cursor → F5 → open your project folder in the Extension Development Host window.

Option C: Marketplace (if published)

Search Contorium, publisher franklee-dev, then Reload Window.

Verify installation

1. Contorium icon appears in the activity bar
2. File → Open Folder (not single file only)
3. Sidebar shows:
   - Current focus input
   - Copy AI-ready context button
   - Workspace snapshot / Git sections

If the sidebar stays blank, see Troubleshooting.

Usage

Sidebar (main UI)

Command palette

Ctrl+Shift+P (macOS: Cmd+Shift+P), search Contorium:

When runtime handoff is pending, the status bar shows [?] Inject runtime? — click to inject context for your next AI chat (semi-auto; appears automatically on new chat when runtime is active).

Runtime dashboard (CRBP — automatic)

When contora.autoAttachDashboard is enabled (default):

1. Opening a folder → bootstrap runs automatically.
2. Passive line on status bar (from handoff.json + mini-graph).
3. New AI chat → auto notification: Inject context? + status bar [?] (no command).
4. Expanded dashboard — full-screen Cognitive State TUI in the Contorium terminal tab (automatic after bootstrap).
5. Terminal keys: c copy · i / Enter inject · ↑↓ view modes (including LLM Config) · ←→ LLM provider in view E · q quit.

Optional: Ctrl+Shift+C opens IDE Webview panel (secondary view).

CIL AI Layer (optional)

Enable explanation-layer LLM (Why / Story / Essence / DNA / Ask polish):

Sidebar Developer → CIL AI Layer shows status and test. CLI dashboard View E configures per-provider keys in .llm-keys.json.

See AI Layer (GitHub) · Runtime dashboard.

Governance (V4)

The IDE participates in the unified governance pipeline shared with MCP and CLI:

IDE Review Change writes review.json only. Full decision provenance (decision / scope / trace / cycle artifacts) is derived via MCP derive_decision_provenance or CLI contorium decision derive.

See INSTALL.md for the three-adapter governance matrix.

Copy AI-ready context structure (V3.1 canonical)

Same as contorium export / formatCanonicalAiMarkdown (sections appear when data exists):

# TASK ANCHOR
# PROJECT SNAPSHOT          (L4 pure project state)
# WORKING CONTEXT           (active files + recent Git)
# COGNITIVE SNAPSHOT        (graph/snapshot.json)
# CHANGE SET                (handoff modified symbols)
# IMPACT SET                (affected functions)
# AI HANDOFF (V3.1)         (goal / focus / risk / next)
# CODE EVOLUTION            (timeline recent commits)
# INSIGHTS                  (up to 4 weak hints, optional)
# NOTES / INSTRUCTION
---
GOVERNANCE:                  (when governance artifacts exist)
## DECISION
## SCOPE
## TRACE

JSON export (contora.exportFormat: json) includes cognitiveSnapshot when the knowledge graph exists.

Not in main copy: full Intent graph, State conflict details, full knowledge.json (use COGNITIVE SNAPSHOT instead).

Local data layout

All data stays in the project; not uploaded by default:

.contora/
├── state.json
├── events/<sessionId>.jsonl
├── intelligence/              # L5 semantic summary
├── intent-graph/              # L5 intent graph
├── state-builder/             # L4 project state + snapshot.md
├── state-engine/              # v2 conflict audit
├── handoff.json               # CHP v1 AI handoff
├── understanding_graph.json   # call chains + impact
├── change.json / graph.json / timeline.json
├── governance/                # V4 governance artifacts
│   ├── review.json            # Review results (IDE/CLI review)
│   ├── decision.json          # Decision outcome
│   ├── scope.json             # Scope context
│   ├── trace.json             # Summary trace
│   ├── trace-full.json        # Detailed reason_chain
│   └── cycle.json             # Full cycle record + matched_rules
├── runtime.bootstrap.json     # runtime_id (session-level)
├── mcp.auto-context.md        # after user confirms semi-auto injection
├── mcp.handoff-injection.json
├── dashboard.status.json      # view mode only (not state source)
├── dashboard.signal.json
├── dashboard.session.json
├── graph/                     # V3.1 cognitive graph
│   ├── knowledge.json
│   ├── snapshot.json
│   ├── hotspots.json
│   └── metadata.json
├── config/                    # LLM (no secrets in llm.json)
│   ├── llm.json
│   └── .llm-keys.json       # per-provider keys (gitignored)
└── mcp/                       # MCP store_memory (if used)

Add .contora/ to .gitignore (example provided in repo).

Working with MCP / CLI (optional)

Adapters are peers — the extension is not required for MCP/CLI.

Same .contora/ directory. See Install.

Uninstall

Remove extension (keep project data)

1. Extensions → Contorium → Uninstall
2. Developer: Reload Window

Manual removal if corrupted:

Remove-Item -Recurse -Force "$env:USERPROFILE\.cursor\extensions\franklee-dev.contorium-*" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:USERPROFILE\.vscode\extensions\franklee-dev.contorium-*" -ErrorAction SilentlyContinue

Clear workspace Contorium data (optional)

Uninstalling the extension does not remove .contora/:

Remove-Item -Recurse -Force .contora -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force .context-recall -ErrorAction SilentlyContinue

Clear BYOK keys (optional)

API keys use VS Code SecretStorage; may persist after uninstall depending on IDE behavior.

Troubleshooting

Logs: Ctrl+Shift+P → Developer: Show Logs → Extension Host, filter Contorium.