context-manager

context-manager

A Claude Code skill that maintains a live, hierarchical map of your codebase through .folder-context.md files — one per folder. Claude reads these files to navigate large codebases without loading everything into context, and keeps them current automatically as you edit.

---

Why this matters

Every Claude Code session starts fresh. On a large codebase, that means Claude either burns context loading files it may not need, or operates blind. Both are expensive.

context-manager solves this by maintaining a lightweight index of your codebase in plain Markdown files, stored alongside your source. Each .folder-context.md captures what every file in that folder does, what it exports, and its current WIP state. Claude reads these top-down to find relevant code fast — without touching source files it doesn't need.

The result:

• Faster navigation — Claude locates relevant code by reading context files, not by scanning directories or loading full source
• Session continuity — after /clear or a new session, Claude reconstructs project understanding in seconds rather than re-reading everything
• Accurate WIP tracking — in-progress state, known issues, and recent changes persist across context resets
• Lower token cost — hierarchical context files are small; loading a 200-line .folder-context.md beats loading 20 source files

---

Installation

Prerequisites

1. Install Claude Code

Claude Code is Anthropic's official CLI for interacting with Claude directly in your terminal and editor. Install it via npm:

npm install -g @anthropic-ai/claude-code

Then log in:

claude

This opens a browser to authenticate with your Anthropic account. Once complete, you can run claude in any project directory to start a session.

If you already have Claude Code installed, make sure it's up to date before proceeding:

npm update -g @anthropic-ai/claude-code

The /plugin command required below was added in a recent version. If you see "unknown command" when running /plugin, update first.

---

2. Have Python 3 available

The hook script that keeps context files current is written in Python. Verify it's installed:

python3 --version

If not installed, download it from python.org or use your system package manager (brew install python3, apt install python3, etc.).

---

Step 1: Register this repo as a plugin source (one time)

Claude Code installs plugins from registered sources. This plugin is hosted directly on GitHub, not on any official marketplace — so you register the GitHub repo itself as a source.

Inside a Claude Code session, run:

/plugin marketplace add pklawansky/context-manager

Despite the name, this command just registers a plugin source — it isn't limited to "official" marketplaces. You only need to do this once; it persists across all sessions and projects.

---

Step 2: Install the plugin

/plugin install context-manager@context-manager

The @pklawansky-context-manager suffix is how Claude Code identifies which registered source to pull from (it converts the owner/repo format to owner-repo). This downloads the plugin and makes the context-manager skill available globally in all your Claude Code sessions.

---

Step 3: Reload plugins

/reload-plugins

This activates the newly installed plugin in your current session. After reloading, Claude will confirm the skill is loaded.

---

Step 4: Verify the installation

/plugin

Navigate to the Installed tab. You should see context-manager listed. If it appears under errors, check that Python 3 is available in your shell.

---

Step 5: Activate in a project

Navigate to your project directory and open Claude Code:

cd /path/to/your/project
claude

Then invoke the skill:

/context-manager

On first run, Claude will:

1. Add .folder-context.md to your project's .gitignore (creating one if needed)
2. Copy mark-context-dirty.py into .claude/scripts/ inside your project
3. Register a PostToolUse hook in .claude/settings.json that fires after every file write or edit
4. Walk the entire project tree and generate .folder-context.md files for every folder with relevant content
5. Write .claude/context-manager.json to record that initialization is complete

This initial generation may take a moment on large codebases. Once complete, Claude will confirm and the skill is fully active.

Subsequent invocations detect the marker file and skip re-initialization — invoking /context-manager again is always safe.

---

What gets added to your project

After initialization, two things are added to your project that you should be aware of: