Skip to content

Getting Started

ctx

Prerequisites

ctx does not require git, but using version control with your .context/ directory is strongly recommended:

AI sessions occasionally modify or overwrite context files inadvertently. With git, the AI can check history and restore lost content: Without it, the data is gone.

Also, several ctx features (journal changelog, blog generation) also use git history directly.

Installation

Every setup starts with the ctx binary: the CLI tool itself.

If you use Claude Code, you also install the ctx plugin, which adds hooks (context autoloading, persistence nudges) and 25+ /ctx-* skills. For other AI tools, ctx integrates via generated instruction files or manual context pasting: see Integrations for tool-specific setup.

Pick one of the options below to install the binary. Claude Code users should also follow the plugin steps included in each option.

Requires Go (version defined in go.mod) and Claude Code.

git clone https://github.com/ActiveMemory/ctx.git
cd ctx
make build
sudo make install

Install the Claude Code plugin from your local clone:

  1. Launch claude;
  2. Type /plugin and press Enter;
  3. Select Marketplaces → Add Marketplace
  4. Enter the path to the root of your clone, e.g. ~/WORKSPACE/ctx (this is where .claude-plugin/marketplace.json lives: It points Claude Code to the actual plugin in internal/assets/claude)
  5. Back in /plugin, select Install and choose ctx

This points Claude Code at the plugin source on disk. Changes you make to hooks or skills take effect immediately: No reinstall is needed.

Local Installs Need Manual Enablement

Unlike marketplace installs, local plugin installs are not auto-enabled globally. The plugin will only work in projects that explicitly enable it. Run ctx init in each project (it auto-enables the plugin), or add the entry to ~/.claude/settings.json manually:

{ "enabledPlugins": { "ctx@activememory-ctx": true } }

Verify:

ctx --version       # binary is in PATH
claude /plugin list # plugin is installed

Use the Source, Luke

Building from source gives you the latest features and bug fixes.

Since ctx is predominantly a developer tool, this is the recommended approach:

You get the freshest code, can inspect what you are installing, and the plugin stays in sync with the binary.

Option 2: Binary Download + Marketplace

Pre-built binaries are available from the releases page.

curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-linux-amd64
chmod +x ctx-0.6.0-linux-amd64
sudo mv ctx-0.6.0-linux-amd64 /usr/local/bin/ctx

curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-linux-arm64
chmod +x ctx-0.6.0-linux-arm64
sudo mv ctx-0.6.0-linux-arm64 /usr/local/bin/ctx

curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-darwin-arm64
chmod +x ctx-0.6.0-darwin-arm64
sudo mv ctx-0.6.0-darwin-arm64 /usr/local/bin/ctx

curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-darwin-amd64
chmod +x ctx-0.6.0-darwin-amd64
sudo mv ctx-0.6.0-darwin-amd64 /usr/local/bin/ctx

Download ctx-0.6.0-windows-amd64.exe from the releases page and add it to your PATH.

Claude Code users: install the plugin from the marketplace:

  1. Launch claude;
  2. Type /plugin and press Enter;
  3. Select Marketplaces → Add Marketplace;
  4. Enter ActiveMemory/ctx;
  5. Back in /plugin, select Install and choose ctx.

Other tool users: see Integrations for tool-specific setup (Cursor, Copilot, Aider, Windsurf, etc.).

Verify the Plugin Is Enabled

After installing, confirm the plugin is enabled globally. Check ~/.claude/settings.json for an enabledPlugins entry. If missing, run ctx init in your project (it auto-enables the plugin), or add it manually:

{ "enabledPlugins": { "ctx@activememory-ctx": true } }

Verify:

ctx --version       # binary is in PATH
claude /plugin list # plugin is installed (Claude Code only)

Verifying Checksums

Each binary has a corresponding .sha256 checksum file. To verify your download:

# Download the checksum file
curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-linux-amd64.sha256

# Verify the binary
sha256sum -c ctx-0.6.0-linux-amd64.sha256

On macOS, use shasum -a 256 -c instead of sha256sum -c.

Plugin Details

After installation (either option) you get:

  • Context autoloading: ctx agent runs on every tool use (with cooldown)
  • Persistence nudges: reminders to capture learnings and decisions
  • Post-commit hooks: nudge context capture after git commit
  • Context size monitoring: alerts as sessions grow large
  • 25+ skills: /ctx-status, /ctx-add-task, /ctx-recall, and more

See Integrations for the full hook and skill reference.

Quick Start

1. Initialize Context

cd your-project
ctx init

This creates a .context/ directory with template files and an encryption key at ~/.ctx/ for the encrypted scratchpad. For Claude Code, install the ctx plugin for automatic hooks and skills.

2. Check Status

ctx status

Shows context summary: files present, token estimate, and recent activity.

3. Start Using with AI

With Claude Code (and the ctx plugin installed), context loads automatically via hooks.

With VS Code Copilot Chat, install the ctx extension and use @ctx /status, @ctx /agent, and other slash commands directly in chat. Run ctx hook copilot --write to generate .github/copilot-instructions.md for automatic context loading.

For other tools, paste the output of:

ctx agent --budget 8000

4. Verify It Works

Ask your AI: "Do you remember?"

It should cite specific context: current tasks, recent decisions, or previous session topics.

Next Up: