### Run Magic Context Setup Directly

Source: https://github.com/cortexkit/magic-context/blob/master/README.md

Initiate the interactive setup wizard for Magic Context on any operating system.

```bash
npx @cortexkit/magic-context@latest setup
```

--------------------------------

### Install Magic Context on macOS/Linux

Source: https://github.com/cortexkit/magic-context/blob/master/README.md

Use this command to download and run the installation script for macOS and Linux systems.

```bash
curl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash
```

--------------------------------

### Install Dependencies and Run Dashboard

Source: https://github.com/cortexkit/magic-context/blob/master/packages/dashboard/README.md

Navigate to the dashboard directory, install frontend dependencies using Bun, and then run the dashboard in development mode with hot-reloading for both the frontend and backend.

```bash
cd packages/dashboard

# Install frontend dependencies
bun install

# Run in development mode (hot-reload frontend + Rust backend)
cargo tauri dev
```

--------------------------------

### Install Magic Context on Windows

Source: https://github.com/cortexkit/magic-context/blob/master/README.md

Execute this PowerShell command to install Magic Context on Windows.

```powershell
irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex
```

--------------------------------

### Run Dashboard in Serve Mode (Linux)

Source: https://github.com/cortexkit/magic-context/blob/master/packages/docs/src/content/docs/reference/dashboard.md

Execute the installed dashboard binary with the `--serve` flag on Linux systems. This command is used when the embedded WebView fails to start.

```bash
# Linux (.deb / .rpm install puts it on PATH)
magic-context-dashboard --serve
```

```bash
# Linux AppImage
./Magic_Context_Dashboard.AppImage --serve
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/cortexkit/magic-context/blob/master/README.md

Installs project dependencies using the Bun package manager. Ensure Bun is installed and meets the version requirement.

```sh
bun install
```

--------------------------------

### Install Pi Plugin Directly with Pi Installer

Source: https://github.com/cortexkit/magic-context/blob/master/packages/pi-plugin/README.md

Use this command to register the Pi extension package directly with Pi. This method adds the extension to Pi's settings but does not create the magic-context.jsonc file.

```bash
pi install npm:@cortexkit/pi-magic-context
```

--------------------------------

### Example Context Search Hint

Source: https://github.com/cortexkit/magic-context/blob/master/CONFIGURATION.md

An example of the hint format appended to user messages when Magic Context finds related context. This hint provides compressed fragments from memory or commit messages.

```xml
<ctx-search-hint>
Your memory may contain related context (3 related fragments):
- install.sh bunx --bun node stdin redirection
- magic-context fail closed durable storage unavailable
- commit abcd123 5d ago: install: force bun runtime in bunx invocation
Run ctx_search to retrieve full context if relevant.
</ctx-search-hint>
```

--------------------------------

### Run Interactive Setup Sandbox

Source: https://github.com/cortexkit/magic-context/blob/master/tests/docker/README.md

Execute the setup-sandbox.sh script to build a Docker image with the latest published version of Magic Context and enter an interactive shell for manual testing.

```bash
# build @latest (fresh npm fetch) and drop into an interactive shell
tests/docker/setup-sandbox.sh
```

```bash
# pin a specific version, or just (re)build the image
tests/docker/setup-sandbox.sh 0.27.1
tests/docker/setup-sandbox.sh --build-only
```

--------------------------------

### Check Pi Plugin Installation Health

Source: https://github.com/cortexkit/magic-context/blob/master/packages/pi-plugin/README.md

Run this command to verify the installation status and health of the Magic Context Pi plugin.

```bash
npx @cortexkit/magic-context@latest doctor --harness pi
```

--------------------------------

### Run Magic Context Setup for Pi Harness

Source: https://github.com/cortexkit/magic-context/blob/master/README.md

Use this command to set up Magic Context specifically for the Pi harness. Ensure Pi is version 0.74.0 or later.

```bash
npx @cortexkit/magic-context@latest setup --harness pi
```

--------------------------------

### Bypass npm Cache for Magic Context Setup

Source: https://github.com/cortexkit/magic-context/blob/master/packages/docs/src/content/docs/help/troubleshooting.md

If npm configuration like `min-release-age` prevents the latest Magic Context from being available, use `npx --yes` to bypass the cache during setup.

```bash
npx --yes @cortexkit/magic-context@latest setup
```

--------------------------------

### Configure Manual Setup for OpenCode

Source: https://github.com/cortexkit/magic-context/blob/master/README.md

Manual configuration for OpenCode requires adding the Magic Context plugin and disabling built-in compaction in opencode.json. A magic-context.jsonc file should also be placed in the project or config directory.

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

--------------------------------

### Example Session with Compartmenting

Source: https://github.com/cortexkit/magic-context/blob/master/packages/docs/src/content/docs/getting-started/first-session.md

Illustrates how older messages are compressed into compartments during a session, showing the user's perspective and the agent's interaction with tool calls and context searches.

```text
[you]        Build me a new auth middleware for the API
[agent]      I'll create a JWT middleware for Express. Let me look at the existing...
             <tool calls: read files, create files, run tests>
             Done — the middleware is in src/middleware/auth.ts. Tests pass.

[you]        Can you also add a refresh token endpoint?
[agent]      Looking at the current token structure...
             <tool calls: read, edit, test>
             Done. POST /auth/refresh at src/routes/auth.ts.

-- [Historian ran. Earlier messages compartmented] --

[you]        Looks good. Can we add rate limiting next?
[agent]      I'll add rate limiting. First let me check what we've built so far...
             <ctx_search: "auth middleware decisions">
             I see from earlier we used JWT with RS256 and 15-minute expiry...
```

--------------------------------

### Minimal Magic Context Pi Plugin Configuration

Source: https://github.com/cortexkit/magic-context/blob/master/packages/pi-plugin/README.md

This is a minimal configuration example for the Magic Context Pi plugin. It enables the plugin and sets default models for historian and embedding.

```jsonc
{
  "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
  "enabled": true,
  "historian": {
    "model": "anthropic/claude-haiku-4-5"
  },
  "embedding": {
    "provider": "local"
  }
}
```

--------------------------------

### Tagging Format Example

Source: https://github.com/cortexkit/magic-context/blob/master/packages/plugin/docs/archive/MAGIC-CONTEXT-DESIGN.md

Illustrates the section sign plus integer format for tagging messages and tool outputs.

```text
§1§, §42§, §187§
```

--------------------------------

### Clarification Protocol Example

Source: https://github.com/cortexkit/magic-context/blob/master/packages/plugin/scripts/calibrate-tokenizer/fixture-system.txt

Use this structured format when asking for clarification to ensure all aspects of the request are understood and to propose a clear path forward.

```text
I want to make sure I understand correctly.

**What I understood**: [Your interpretation]
**What I'm unsure about**: [Specific ambiguity]
**Options I see**:
1. [Option A] - [effort/implications]
2. [Option B] - [effort/implications]

**My recommendation**: [suggestion with reasoning]

Should I proceed with [recommendation], or would you prefer differently?
```

--------------------------------

### Writing an OpenCode E2E Test

Source: https://github.com/cortexkit/magic-context/blob/master/packages/e2e-tests/README.md

Example of how to set up and drive an OpenCode session within an end-to-end test. This involves mocking the Anthropic server, spawning the OpenCode subprocess, scripting mock responses, and interacting with the OpenCode client.

```typescript
import { MockProvider } from "../src/mock-provider/server";
import { spawnOpencode } from "../src/opencode-runner/spawn";

const mock = new MockProvider();
const {baseURL} = await mock.start();
const opencode = await spawnOpencode({ mockProviderURL: baseURL });

// Script exactly what the main agent should return on each turn.
mock.script([
    { text: "response 1", usage: { input_tokens: 10_000, output_tokens: 50 } },
    { text: "response 2", usage: { input_tokens: 50_000, output_tokens: 50, cache_read_input_tokens: 10_000 } },
]);

// Drive the session via the SDK.
const { createOpencodeClient } = await import("@opencode-ai/sdk");
const client = createOpencodeClient({ baseUrl: opencode.url });
const { data: session } = await client.session.create({ query: { directory: opencode.env.workdir } });
await client.session.prompt({
    path: { id: session!.id },
    body: {
        model: { providerID: "mock-anthropic", modelID: "mock-sonnet" },
        parts: [{ type: "text", text: "turn 1" }],
    },
});

// Assert against captured requests and plugin state.
expect(mock.requests().length).toBe(1);

await opencode.kill();
await mock.stop();

```

--------------------------------

### Common npm Commands for Astro Projects

Source: https://github.com/cortexkit/magic-context/blob/master/packages/docs/README.md

These commands are essential for managing your Astro project. They cover installation, local development, building for production, and previewing the build.

```bash
npm install
```

```bash
npm run dev
```

```bash
npm run build
```

```bash
npm run preview
```

```bash
npm run astro ...
```

```bash
npm run astro -- --help
```

--------------------------------

### Create Astro Project with Starlight Template

Source: https://github.com/cortexkit/magic-context/blob/master/packages/docs/README.md

Use this command to initialize a new Astro project with the Starlight template. This sets up the basic structure for your documentation site.

```bash
npm create astro@latest -- --template starlight
```

--------------------------------

### Preview OpenCode to Pi migration

Source: https://github.com/cortexkit/magic-context/blob/master/packages/docs/src/content/docs/getting-started/migrating-between-harnesses.md

Use the `--dry-run` flag to preview the migration process without writing any files. This is useful for understanding what changes will be made.

```bash
npx @cortexkit/magic-context@latest doctor migrate \
  --from opencode --to pi --session <session-id> --dry-run
```

--------------------------------

### Context Compress Tool ACK Response

Source: https://github.com/cortexkit/magic-context/blob/master/packages/plugin/docs/archive/MAGIC-CONTEXT-DESIGN.md

Example of the acknowledgment response from the context_compress tool, indicating queued operations.

```text
Queued: drop §3§-§5§, summarize §1§,§2§,§9§. Will execute at optimal time.
```

--------------------------------

### Conflict Resolution Example

Source: https://github.com/cortexkit/magic-context/blob/master/packages/plugin/docs/archive/MAGIC-CONTEXT-DESIGN.md

Demonstrates how later operations override earlier ones for overlapping items, specifically when summarizing and dropping messages.

```text
Agent call 1: context_compress({ summarize: "5-10" })
Agent call 2: context_compress({ drop: "7" })

Result: Summarize 5-6, 8-10 (excluding 7). Drop 7 entirely.
If summary was already precomputed including 7, invalidate and re-precompute excluding 7.
```

--------------------------------

### Run Unified Doctor Command

Source: https://github.com/cortexkit/magic-context/blob/master/CONFIGURATION.md

Use the doctor command to auto-detect installed harnesses and resolve common issues. Specify a harness if needed.

```bash
# Auto-detect installed harnesses; if both, picks the first or asks
npx @cortexkit/magic-context@latest doctor

# Target a specific harness explicitly
npx @cortexkit/magic-context@latest doctor --harness opencode
npx @cortexkit/magic-context@latest doctor --harness pi
```

--------------------------------

### Build the Plugin with Bun

Source: https://github.com/cortexkit/magic-context/blob/master/README.md

Builds the Magic Context plugin using Bun. This command compiles the project for deployment or further testing.

```sh
bun run build
```

--------------------------------

### Expand Compressed History with ctx_expand

Source: https://github.com/cortexkit/magic-context/blob/master/packages/plugin/scripts/calibrate-tokenizer/fixture-system.txt

Use ctx_expand to decompress a compartment range and view the original conversation transcript. Requires 'start' and 'end' attributes from compartment tags.

```python
ctx_expand(start=1, end=10)
```

--------------------------------

### Magic Context Full Configuration Example

Source: https://github.com/cortexkit/magic-context/blob/master/CONFIGURATION.md

This JSON configuration object enables and customizes various features of Magic Context, including caching, execution thresholds, model settings for historian and dreamer, embedding provider, memory management, and sidekick behavior. Use this as a template for your own configuration.

```jsonc
{
  "enabled": true,
  "cache_ttl": {
    "default": "5m",
    "anthropic/claude-opus-4-6": "58m"
  },
  "execute_threshold_percentage": {
    "default": 65,
    "anthropic/claude-opus-4-6": 50
  },
  "protected_tags": 10,
  "toast_duration_ms": 12000,
  "history_budget_percentage": 0.15,
  "temporal_awareness": true,

  "historian": {
    "model": "github-copilot/gpt-5.4",
    "fallback_models": ["anthropic/claude-sonnet-4-6"]
  },

  "dreamer": {
    "model": "github-copilot/gpt-5.4",
    "fallback_models": ["anthropic/claude-sonnet-4-6"],
    "tasks": {
      "map-memories": { "schedule": "0 2 * * *" },
      "verify": { "schedule": "0 3 * * *" },
      "verify-broad": { "schedule": "0 4 * * 0" },
      "curate": { "schedule": "0 4 * * 0" },
      "classify-memories": { "schedule": "0 6 * * *" },
      "retrospective": { "schedule": "0 5 * * *" },
      "maintain-docs": { "schedule": "" },
      "promote-primers": { "schedule": "0 3 * * *", "promotion_threshold": 2 },
      "refresh-primers": { "schedule": "0 3 * * *" },
      "evaluate-smart-notes": { "schedule": "0 3 * * *" },
      "review-user-memories": { "schedule": "0 3 * * *", "promotion_threshold": 3 }
    }
  },

  "embedding": {
    "provider": "local"
  },

  "memory": {
    "enabled": true,
    "injection_budget_tokens": 4000,
    "auto_promote": true,
    "auto_search": { "enabled": true, "score_threshold": 0.6, "min_prompt_chars": 20 },
    "git_commit_indexing": { "enabled": false, "since_days": 365, "max_commits": 2000 }
  },

  "sidekick": {
    "model": "github-copilot/gpt-5.4",
    "fallback_models": ["anthropic/claude-sonnet-4-6"],
    "timeout_ms": 30000
  }
}
```

--------------------------------

### Run Dashboard in Serve Mode (Windows)

Source: https://github.com/cortexkit/magic-context/blob/master/packages/docs/src/content/docs/reference/dashboard.md

Execute the dashboard application with the `--serve` flag on Windows. This command is used to run the dashboard as a local web server.

```bash
# Windows
"%LOCALAPPDATA%\Programs\Magic Context Dashboard\Magic Context Dashboard.exe" --serve
```

--------------------------------

### Enable Magic Context System

Source: https://github.com/cortexkit/magic-context/blob/master/packages/plugin/docs/archive/MAGIC-CONTEXT-DESIGN.md

Enable the magic context system and configure its core parameters. The compression model is required when enabled. Cache TTL can be set globally or per-model.

```jsonc
{
  "magic_context": {
    "enabled": true,                              // default: false
    "compression_model": "anthropic/claude-haiku-4.5",  // REQUIRED when enabled
    "cache_ttl": "5m",                            // default for all providers, configurable per-model
    "protected_turns": 5,                         // last N user/assistant turns un-droppable
    "compression_budget": {
      "ratio": 0.3,                               // summary ≈ 30% of original
      "max_tokens": 4096                           // hard cap
    }
  }
}
```

```jsonc
{
  "magic_context": {
    "cache_ttl": {
      "default": "5m",
      "anthropic/claude-sonnet-4-5": "5m",
      "anthropic/claude-opus-4-6": "1h"    // Max plan
    }
  }
}
```