SuperCtx
All the context, in one place.
SuperCtx keeps AI coding assistants aligned on one shared project context. It creates a project-local .ctx/ hub from files like CLAUDE.md, AGENTS.md, and GEMINI.md, then keeps tool-specific instruction files as thin generated shims pointing back to that hub.
Many coding tools use their own project instruction files:
CLAUDE.md
AGENTS.md
GEMINI.md
.github/copilot-instructions.md
When you use more than one tool, those files can drift apart. SuperCtx gives the project one context layer and exposes it consistently across Claude Code, Codex, Gemini, Antigravity, Copilot, Cursor, and other AI coding tools.
Why SuperCtx?
Use SuperCtx when a repository has more than one AI coding tool and you want those tools to share the same project assumptions.
SuperCtx helps you:
- reduce repeated copy-paste between tool-specific instruction files
- keep context project-local instead of sending it to a cloud memory service
- inspect which instruction files are connected to the shared context hub
- detect missing or broken generated shims and missing inactive backups
- dogfood project context workflows across Claude Code, Codex, Gemini, and related tools
How It Works
SuperCtx uses a project-local context folder:
.ctx/
The .ctx/ folder is the centralized hub for project context. SuperCtx makes .ctx/SUPERCTX.md the canonical hub, and generates thin shims pointing back to it:
┌─> CLAUDE.md (shim)
.ctx/SUPERCTX.md ┼─> AGENTS.md (shim)
└─> GEMINI.md (shim)
SUPERCTX.md is a version-controlled Markdown file and the canonical shared context hub. You can inspect or edit it directly if needed, but the normal workflow is to ask the agent to update project context. Original tool instruction files are backed up and converted to thin referential shims.
A built-in write guard also intercepts direct edits/writes to protected instruction files, guiding the agent to update the shared context hub instead.
Agent-Native Bootstrapping
SuperCtx includes a built-in agent reference skill, /using-superctx. This is an agent reference / advanced skill. Normal users do not need to run this command; the agent uses it automatically to orient itself on the project's context boundaries and active files.
When SuperCtx is active, the agent uses .ctx/SUPERCTX.md as shared project context through generated shims. You normally ask the agent to update project context naturally instead of managing Markdown or TOML by hand.
When SuperCtx is actively helping, the agent may use a short cue such as:
Using SuperCtx to check context health.
The cue should stay task-specific and brief. SuperCtx should not explain hub, shim, or backup internals unless you ask.
What SuperCtx Auto-Detects
SuperCtx scans the project directory during setup, status checks, session start, and protected instruction-file writes:
- Verified Instruction Files (Auto-connected):
Root-level
CLAUDE.md, AGENTS.md, GEMINI.md, and hidden standard paths like .claude/CLAUDE.md, .codex/AGENTS.md, and .github/copilot-instructions.md. These are automatically added to .ctx/manifest.toml.
- Supported Folder Candidates (Surfaced, not auto-connected):
Known standard folder layouts like
.agents/rules/ and agents/skills/ are surfaced as candidates for future connection work.
- Legacy or Uncertain Candidates (Surfaced, not auto-connected):
Legacy layouts such as
.agent/rules/ or .agents/skills/ are reported.
- Unverified Local Candidates (Surfaced, not auto-connected):
Local conventions such as
.agy/ or .agy/ANTIGRAVITY.md are surfaced and labeled as unverified local candidates (not official support).
User Installation
SuperCtx is early software. Today, install it directly from GitHub for Claude Code or run the Python CLI from a source checkout.
Install directly from GitHub today
From inside Claude Code, add this repository as a plugin marketplace and install the superctx plugin:
/plugin marketplace add MrShininnnnn/SuperCtx
/plugin install superctx@superctx
Claude Code copies marketplace plugins into Claude's local plugin cache. After installing or updating the plugin, restart Claude Code if the new skills do not appear immediately.
Load the plugin in Claude Code
After installation, the primary command to check context health is:
/superctx:status
[!NOTE]
SuperCtx is fully agent-guided. Use /superctx:status to check health. The agent will guide setup, add, and repair when needed. Normal users do not need to operate the other commands directly.
For advanced troubleshooting or developer verification, the following commands are available:
/superctx:init: Scaffold/migrate the context hub./superctx:sync: Repair generated shims./superctx:add <path>: Register a new local instruction file.
Coming Soon: Claude Community Marketplace
