All the context, in one place.
SuperCtx keeps AI coding assistant instruction files aligned through one shared .ctx/SUPERCTX.md hub. It backs up original instruction files, then keeps tool-specific files as generated shims that point back to the shared project context.
AI coding tools expect project instructions in different places, such as CLAUDE.md, AGENTS.md, GEMINI.md, or tool-specific folders. When one repository uses multiple assistants, those files can drift.
SuperCtx gives the repository one local source of truth so Claude Code, Codex, Gemini, Copilot, Cursor, Antigravity, and similar tools can share the same project guidance.
SuperCtx creates a project-local hub:
.ctx/SUPERCTX.md
Tool-specific instruction files remain where each assistant expects them, but become generated shims:
.ctx/SUPERCTX.md # shared project context hub
.claude/CLAUDE.md # generated shim
.codex/AGENTS.md # generated shim
GEMINI.md # generated shim
Original instruction files are backed up under .ctx/sources/ before SuperCtx replaces live instruction files with shims.
Install SuperCtx directly from GitHub in Claude Code:
/plugin marketplace add MrShininnnnn/SuperCtx
/plugin install superctx@superctx
After installing or updating, restart Claude Code if the SuperCtx commands do not appear immediately.
Marketplace installation is planned for a future release.
Set up, check, repair, and report SuperCtx state for the current repository.
Use this as the main command when entering a repository or when project context needs attention.
Add or connect one specific instruction file to the shared context hub.
Use this when you have a local instruction file that SuperCtx should manage with the rest of the project context.
Agent-facing reference skill for using SuperCtx correctly.
Most users do not need to run this directly; it exists so agents can orient themselves around the repository's shared context.
Before SuperCtx:
.claude/CLAUDE.md
.codex/AGENTS.md
GEMINI.md
After /superctx:sync:
.ctx/
SUPERCTX.md
manifest.toml
sources/
.claude/
CLAUDE.md
.codex/
AGENTS.md
GEMINI.md
.claude/CLAUDE.md
.codex/AGENTS.md
GEMINI.md
The files at .claude/CLAUDE.md, .codex/AGENTS.md, and GEMINI.md remain available to their tools, but they point back to .ctx/SUPERCTX.md.
SuperCtx also ships a Python CLI for source checkouts:
superctx sync
superctx add <path>The same commands can be run as a module:
python -m superctx sync
python -m superctx add <path>To update the installed Claude Code plugin:
/plugin marketplace update superctx
/plugin update superctx
/reload-plugins
To force a reinstall:
/plugin uninstall superctx
/plugin install superctx@superctx
/reload-plugins
SuperCtx is local-first:
- project context stays in the repository
- original instruction files are backed up under
.ctx/sources/ - generated shims are disposable and can be repaired
- SuperCtx has no remote backend
- SuperCtx does not provide telemetry or analytics
Do not put secrets, credentials, API keys, or sensitive personal data in project instruction files.
SuperCtx requires Python 3.9 or newer. Python 3.11+ is recommended.
From a fresh clone:
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'
python -m pytest tests/ -vRun local validation before opening a pull request:
python -m pytest tests/ -v
claude plugin validate .For contribution details, see CONTRIBUTING.md.
SuperCtx is created and maintained by Ning Shi (Shining).
MIT