Your AI forgot. Your repository won't.
▶ EXPLORE THE INTERACTIVE LANDING PAGE
See the motivation, architecture, installation paths, real evidence and honest limits.
Public beta: CTX404 is ready for real-project testing, but interfaces may change before v1.0. Please report unexpected behavior through Issues.
CTX404 is an open-source Claude Code skill that bootstraps durable, indexed and token-aware context inside new or existing repositories.
For a new repository it initializes Git and installs the context foundation directly. For an existing repository it preserves current files and starts durable context from the installation point forward. If it detects a pre-existing state, planning, memory or decision system, it stops before writing and asks how authority should be handled. Both modes install project-local governance, narrowly scoped Haiku and Sonnet helpers, and deterministic Python validation. Native /init and recap are never run automatically; they remain optional, user-controlled orientation after installation. The global skill is no longer a runtime dependency after installation.
Run once. The skill leaves. The context system stays. Clone the initialized repository on another machine and its rules, current state, index, history, hooks and maintenance helpers travel with the code.
- Claude Code with skill support;
- Python 3 available as
python; - Git available as
git; - Windows, macOS or Linux.
Check before installing:
python --version
git --version
claude --version
Runtime helpers use only the Python standard library. CTX404 installs no Python or Node.js packages in initialized projects.
The commands below let you read exactly what will be installed before running it:
# macOS · Linux · WSL · Git Bash
git clone --depth 1 https://github.com/claudneysessa/ctx404.git
cd ctx404
less install.sh scripts/install.py
python scripts/install.py --force# Windows · PowerShell 5.1+
git clone --depth 1 https://github.com/claudneysessa/ctx404.git
Set-Location ctx404
Get-Content install.ps1
Get-Content scripts/install.py
python scripts/install.py --forceThe installer only copies SKILL.md, scripts/, assets/ and references/ into the user-level Claude skills directory. Replacement is transactional: an existing installation is restored if the new copy fails.
These commands download and execute remote code. Use them only if you trust the repository and prefer convenience over inspection:
# macOS · Linux · WSL · Git Bash
curl -fsSL https://raw.githubusercontent.com/claudneysessa/ctx404/main/install.sh | sh# Windows · PowerShell 5.1+
irm https://raw.githubusercontent.com/claudneysessa/ctx404/main/install.ps1 | iexThen:
- Restart Claude Code if the command is not immediately discovered.
- Open Claude Code in the target project directory.
- Run
/ctx404. - Describe what the project should become.
- Restart the session when
/ctx404finishes. Nothing is recorded until you do.
⚠️ The session that installs CTX404 is not governed by it.CLAUDE.md, the protocol file and theSessionStartandPreToolUsehooks are read once, when a session starts. The session that just wrote them keeps running without them: no status summary, no context gate, no durable context. Keep working there and hours of decisions leave no trace on disk. The same applies after/ctx404 upgrade.
CTX404 detects the repository automatically. Empty projects use the original bootstrap flow. Existing projects use non-destructive adoption: project files and README stay untouched, existing Claude guidance is preserved, settings are merged, and no retrospective repository analysis runs during installation.
Adoption means install now and keep working. CTX404 does not try to reconstruct the project's past, generate speculative documentation or spend a large-model session cataloguing everything. Context grows organically as future work touches each area.
After installation, CTX404 recommends an optional manual baseline. Ask Claude for a concise, evidence-based repository recap or run native /init yourself, review the result, and approve it before saving anything as durable context.
Installation stops instead of overwriting when a CTX404-managed agent, hook, script or context path already exists with unknown ownership.
Preserving files is not enough; CTX404 also preserves how the repository already thinks. Its preflight checks known project-level signals such as state files, planning systems, memory folders and architecture-decision directories. When overlap is possible, it makes no project changes and asks you to choose:
- Index — recommended: existing sources remain authoritative; CTX404 becomes the compact routing and cross-session continuity layer.
- Exclusive: CTX404 becomes the primary durable-context authority. Previous systems are still preserved and may be migrated or retired only through separate explicit work.
- Cancel: stop without installing or initializing Git.
In index mode, .claude/context/index.json records the detected paths under governance.authorities. CTX404 points to those sources instead of copying their content into a second, weaker truth.
Updating the global skill does not update repositories that already contain CTX404. The planted protocol is intentionally self-contained. Rerunning /ctx404 validates the installed project version and reports whether a newer skill exists, but never overlays project files.
Use /ctx404 upgrade explicitly to request a reviewed migration. CTX404 first shows the installed and target versions, exact changes, preserved state and any authority decision. Only after approval does it create a local backup, apply a known version-to-version migration, run the context doctor and restore the backup automatically on failure. Migrations chain, so a project on the oldest beta reaches the current version in one reviewed run: v0.2.0-beta.1 → v0.3.0-beta.1 → v0.4.0-beta.1 → v0.4.0-beta.2 → v0.4.0-beta.3. The plan reports each hop, the files it creates, and the managed files it refreshes. A released version is never removed from that chain: the upgrade refuses any installed version it does not recognize, so dropping one would strand every project still on it.
An upgrade takes effect only in the next session, exactly like an install. Restart when it finishes.
CTX404 does not write its protocol into CLAUDE.md. It adds a marked stub of two imports at the top and leaves the rest of the file untouched:
<!-- ctx404:governance:start version="0.4.0-beta.3" schema="2" -->
@.claude/ctx404-instructions.md
@.claude/context/project-definition.md
<!-- ctx404:governance:end -->
.claude/ctx404-instructions.mdis the always-loaded core protocol. It is managed: a reviewed upgrade replaces it, so upgrading never depends on you having left it alone..claude/context/project-definition.mdholds project identity and scope. It is yours; CTX404 never rewrites it..claude/rules/ctx404-context.mdholds the context-writing procedure. Claude Code loads it on its own only when.claude/context/is touched, so it costs nothing in sessions that never write context.
On a measured install the CTX404 footprint in CLAUDE.md is under 600 characters, and the always-loaded protocol is roughly half of what a single inline block cost. Upgrading a pre-0.4.0 project removes the old inline block and leaves the stub in its place, carrying your edited project definition into the new file.
new-project/
├── .git/
├── .claude/
│ ├── agents/
│ │ ├── context-scout.md
│ │ └── context-curator.md
│ ├── hooks/
│ │ ├── session_context.py
│ │ ├── guard_agent_bash.py
│ │ └── context_gate.py
│ ├── scripts/context_tool.py
│ ├── settings.json
│ ├── ctx404-instructions.md
│ ├── rules/ctx404-context.md
│ └── context/
│ ├── index.json
│ ├── current.json
│ ├── schema.json
│ ├── history.jsonl
│ ├── project-definition.md
│ ├── templates/topic.md
│ └── topics/
├── CLAUDE.md
└── README.md
New sessions receive a compact status summary. They can query the index and load only the topic needed for the current task instead of treating the entire repository as startup context.
Reading context was always a hook, and therefore certain. Writing it was a paragraph of prose asking the model to remember, and a request loses to whatever else holds the turn. The asymmetry had a predictable shape: sessions that produced files got recorded, and sessions that produced only decisions — the ones whose reasoning exists nowhere else — did not.
.claude/hooks/context_gate.py is a Stop hook that closes that gap. It reads the transcript, counts the exchanges since the last complete, and blocks the end of a session that deliberated without recording anything. It blocks once and never twice: Claude Code sets stop_hook_active on the retry and the hook stands down, so a false positive costs one turn. It fails open on an unreadable transcript, a missing context directory, or an auxiliary agent.
Durable context is not defined by files changed. The test is whether a future session would have to ask again — so a decision, an option you rejected and why, a reversal, a structure discussed but never implemented, and a constraint you revealed are each recordable on their own.
Recording is only half of it. find searches summaries and keywords, never topic bodies, so a rejected option written into a topic was stored and unreachable — which, from where you sit, is the same as never written. context_tool.py review --section rejected, --query and --topic read deliberation back out, so an option turned down in June can be reconsidered on purpose in August instead of being re-proposed as if it were new.
CTX404 gives Claude explicit routes and guardrails for delegating low-judgment work to cheaper models:
- Haiku: bounded discovery, file location and factual extraction;
- Sonnet: multi-file reading, synthesis and context curation;
- Opus: architecture, trade-offs, risky changes and final judgment;
- Python: deterministic installation, validation and context maintenance.
Claude still decides whether delegation is worthwhile. Model routing, savings and output quality are not guaranteed. CTX404 does not replace review, judgment or accurate project definitions.
python -m unittest discover -s tests -v
python -m compileall -q scripts assets/templates/.claudeSee the reproducible calculator continuity laboratory and tested environments.
CTX404 keeps project context inside the repository. That makes it portable, but it also means the repository's own visibility and ignore rules matter. Never store passwords, API keys, private keys or other secrets in context files. See SECURITY.md.
Issues, compatibility reports and focused pull requests are welcome in English or Portuguese. Read CONTRIBUTING.md and the Code of Conduct.
CTX404 was created and is maintained by Claudney Sarti Sessa — @claudneysessa.