Installation

The setup wizard detects which harnesses you have installed, configures the plugin, and handles compatibility conflicts automatically. Run it once to get started.

Requirements

• Node.js 22.16 or later on the 22 line, or Node.js >= 24 for the CLI (Node 23 is not supported)
• OpenCode (current version) — for OpenCode installs. On OpenCode 2, or when upgrading an existing install from OpenCode 1 to 2, read OpenCode 2 first
• Pi >= 0.74.0 — for Pi installs
• OMP >= 17.1.7 — for Oh My Pi installs

Run setup

npx @cortexkit/magic-context@latest setup

The wizard auto-detects OpenCode, Pi, and OMP. It then:

1. Registers the plugin using the harness’s native package manager
2. Disables built-in compaction where Magic Context takes ownership
3. Disables OMP automatic memory to prevent duplicate recall/retention
4. Prompts you to pick models for the historian and dreamer agents
5. Resolves conflicts with other context-management plugins
6. Writes a shared magic-context.jsonc with sensible defaults

Target one harness explicitly with --harness opencode, --harness pi, or --harness omp.

When setup succeeds in an interactive terminal, it offers to install the Magic Context Dashboard desktop app, verified against its release signature; pass --dashboard to install it without asking or --no-dashboard to skip the offer.

Note

Why is compaction disabled? Magic Context manages context itself. Host compaction would interfere with the historian and double-compress history. Setup turns it off automatically. OMP’s automatic memory backend is also disabled because two memory injectors would duplicate context and writes. Existing OMP memory data is not deleted.

What gets configured

OpenCode

Setup adds the plugin to your opencode.jsonc and turns off compaction. This example is OpenCode 1; on OpenCode 2 the key is plugins (see OpenCode 2):

{
  "plugin": ["@cortexkit/opencode-magic-context@latest"],
  "compaction": { "auto": false, "prune": false }
}

It also creates a magic-context.jsonc config file in the shared CortexKit location (the same across all harnesses; project overrides user):

Path	Scope
<project>/.cortexkit/magic-context.jsonc	Project
~/.config/cortexkit/magic-context.jsonc	User-wide defaults

Pi

Setup adds the extension to Pi’s settings and creates a magic-context.jsonc config file in the shared CortexKit location (the same across all harnesses; project overrides user):

Path	Scope
<project>/.cortexkit/magic-context.jsonc	Project
~/.config/cortexkit/magic-context.jsonc	User-wide defaults

Note

Pi setup prompts for thinking_level if you pick a github-copilot/* reasoning model — Copilot requires it and rejects the default value Pi would send otherwise. The wizard handles this for you.

Oh My Pi (OMP)

Setup installs @cortexkit/pi-magic-context through omp plugin, verifies it is effectively enabled for the current project, and writes the same shared CortexKit config used by OpenCode and Pi. It honors named OMP profiles, PI_CODING_AGENT_DIR, PI_CONFIG_DIR, and initialized XDG layouts.

OMP setup transactionally applies:

omp config set compaction.enabled false
omp config set memory.backend off

If plugin registration or config writing fails, the prior OMP settings are restored.

Manual setup (OpenCode)

If you cannot run the wizard, add this to opencode.jsonc (on OpenCode 2, write plugins instead of plugin):

{
  "plugin": ["@cortexkit/opencode-magic-context@latest"],
  "compaction": { "auto": false, "prune": false }
}

Then create magic-context.jsonc with the one setting the historian needs:

{
  "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
  "historian": {
    "opencode": { "model": "provider/model-id" }
  }
}

• Recommended: Set historian.opencode.model to a real provider/model-id so historian quality and cost are independent of the main coding model. When omitted, historian runs fall back to the live session model; if no runnable model is available, older history is not summarized and repeated failures appear in status.
• Optional: the dreamer model/disable block. Omit it to leave periodic memory consolidation off.
• Optional: embedding. Omit it to use the local Xenova/all-MiniLM-L6-v2; turning embeddings off removes semantic/embedding-backed search, but keyword search and context management continue.

User-level config is ~/.config/cortexkit/magic-context.jsonc on macOS/Linux and %USERPROFILE%\.config\cortexkit\magic-context.jsonc on Windows (or $XDG_CONFIG_HOME/cortexkit/magic-context.jsonc when set). OpenCode Desktop users can use the dashboard’s config editor or hand-edit that file; Desktop does not include the CLI setup wizard.

Verify the install

After setup, restart your harness (or run /reload-plugins in OMP) so the plugin loads.

OpenCode

Run /ctx-status in the OpenCode TUI or Desktop. You should see a status view with context usage, tag counts, and historian state. A live sidebar in the TUI also shows a real-time context breakdown after every message.

Pi

Run /ctx-status in Pi. You should see a status line with context usage and Magic Context state. Pi also shows a status line in the footer when the plugin is active.

Oh My Pi (OMP)

Run /ctx-status in OMP. The Magic Context footer/status should be active, and doctor --harness omp should report native compaction and automatic memory as disabled.

Check an existing install

If Magic Context is already installed and something isn’t working, run the doctor:

npx @cortexkit/magic-context@latest doctor

Doctor auto-detects your harnesses and checks: plugin registration, config validity, conflicts, database integrity, and the embedding endpoint. It prints a PASS X / WARN Y / FAIL Z summary. If both OpenCode and Pi are installed, doctor asks which harnesses to diagnose; use --harness opencode or --harness pi to select one without prompting. When it finds multiple OpenCode installations, it prints a table with the active path, version, and source so a shadowed binary is visible.

Add --force to automatically fix what doctor can — it clears stale plugin caches and repairs common config issues. Add --issue to generate a sanitized bug report ready to file.

Model configuration

The setup wizard helps you pick models for the historian and dreamer. Historian summary quality depends on this separate model, so use one that follows structured summarization instructions reliably. A model that bills per request can keep background-work cost flat. A configured historian uses only its primary and explicit fallback_models, reporting failure when they are exhausted rather than using the session model. With no historian model, OpenCode inherits the session model; Pi and Oh My Pi do not summarize. See the historian configuration reference.

Dashboard

Magic Context ships a companion desktop app for browsing memories, session history, cache diagnostics, and dreamer runs. See the dashboard reference or download it from the GitHub releases page.