Ctxfolio
Live site: anshroshan.github.io/ctxfolio
A project-local context wiki lets a fresh coding agent recover decisions, contracts and next steps without rediscovering everything. This skill scaffolds that wiki, routes tasks to relevant pages, and flags context that needs review.
Every session, your coding agent re-derives the same facts about the same repo — tokens spent rediscovering what it did last time. Context is compiled, not retrieved: this system has the agent write down what it learns, once, at change time, into an interlinked markdown wiki (context/); future sessions — any tool, any teammate's machine — orient from those files in ~2–5k tokens instead of re-exploring.
raw (code + context/raw/) ──► wiki (context/** pages) ◄── schema (AGENTS.md + context/index.md)
code + source snapshots agent-owned, human-reviewed how to maintain it
Hooks and lint check context bookkeeping alongside the code diff. In configured Claude sessions, Stop can request missing page/coverage/state updates; its repeat-pass bypass and no-git limits mean it is not a safety or correctness guarantee. Other tools use explicit checks or CI. Hook contract.
60-second start
Windows: enable Developer Mode (or obtain the symbolic-link privilege) before creating/cloning real links. Start-Process 'ms-settings:developers' opens the setting; the skill never toggles it automatically. You may turn it off after verified creation, but future clones/checkouts/link repairs can require it again. New setup uses real relative symlinks and local Git core.symlinks=true; unsupported permissions fail clearly, not as copied files. --portable-pointers is an explicit legacy opt-out.
Recommended from your project root:
npx [email protected] setup
Or install the zero-dependency CLI globally:
npm install -g [email protected]
ctx setup
The npm package installs the ctx command. Setup creates the project-local CLI and routing skill; no separate global skill install is required.
# Alternative: clone and install the skill into ~/.agents/skills/ctxfolio
# Use --tool claude|qoder or --dest to steer discovery
git -c core.symlinks=true clone https://github.com/AnshRoshan/ctxfolio
node ctxfolio/scripts/ctx.mjs install
# 2 — set up any repo: greenfield or brownfield, any language (run from its root)
cd your-project && node <skill-dir>/scripts/ctx.mjs setup
# 3 — work. The agent orients, routes, records, and hands off through files.
node context/ctx.mjs brief src/auth/login.ts # what to read for this task
node context/ctx.mjs task start 03 # one unit at a time, enforced
Or tell your agent: "Run npx [email protected] setup from this repository's root." For a skill-only install, clone https://github.com/AnshRoshan/ctxfolio and run its installer. Setup is idempotent and upgrade-safe — re-run setup any time; filled content is never clobbered, and after updating the skill it upgrades the project in place.
What lands in your repo
| Piece | What it does |
|---|
AGENTS.md | the schema every agent reads first — ≤120 lines, routed, with a Lessons section that turns each of your corrections into a permanent one-liner |
context/ | the wiki: router index, append-only log, architecture/standards/decisions pages, codebase map + module pages with covers: globs, feature specs, immutable raw/ for ingested docs |
context/progress-tracker.md | the task ledger — In progress (max one) / Blocked / Up next / Completed, moved by ctx task |
context/ownership.md | the responsibility map: where a fact belongs, and where it must not be repeated |
.agents/{agents,rules,skills}/ | canonical reusable instruction bodies, rule routers and internally authored skills |
| Native resource symlinks | Claude agents/rules/skills and Cursor skills share canonical folders; Cursor rules link one central native-format view folder; host settings remain separate |
docs/ | human-facing docs; agents read context/ — one fact, one home, linked never duplicated |
context/ctx.mjs | the zero-dependency CLI the project carries forever |
Why it holds up
- Any project, detected not assumed —
ctx setup reads manifests (Node, Python, Go, Rust, Java, Ruby, PHP, Dart, Elixir, C++…), classifies the shape (web-app / api / cli / library / mobile / data / monorepo), and scaffolds only what fits. A FastAPI repo gets no Next.js-flavored pages.
- Delegates, doesn't hand-roll —
ctx tools finds graphify, ctags, aider, dependency-cruiser; the structural pass runs on real code-intelligence, the wiki keeps the distilled result.
- Evidence-aware routing —
ctx brief <task> --budget 6000 --json returns ranked pages, TL;DRs, costs, skipped candidates and verification warnings. Retired pages stay out unless --history.
- Git-backed review signals —
ctx stale/ctx impact map changed paths to responsible pages. Checks identify review work; they do not prove claims are true.
- Built for teams — one unit = one branch = one owner; merge collisions (duplicate task/spec/decision IDs) surface as lint errors, not arguments.
ctx archive rotates growth out of the hot files. See references/multi-user.md.
- Prompts are products — specs and subagent briefs follow ASD-STE100 (Simplified Technical English) discipline: one action per sentence, one word one meaning. references/prompt-craft.md.
- Tested as a CLI — this repo runs its own context system;
node tests/run.mjs drives disposable git repos and the copied tool, including budgets, filenames, hook edge cases and non-destructive setup. Supported-platform CI and published release results live in verification evidence; local results alone do not certify remote CI.
The CLI
setup · init · detect · tools one-command scaffold, profile, delegation targets
brief · rules · coverage · status route a task to pages; what applies to THIS file
task add|start|block|done|list the ledger, one unit at a time
impact · stale · stamp · lint --fix keep pages true to code (git-based)
index · log · new · archive catalog, timeline, page scaffolds, growth rotation
doctor · install · hook wiring checks, skill installer, Claude hooks
adapters [--check] [--migrate] recorded layout refresh and central metadata views
symlinks [--check] [--migrate] real relative link audit/migration and local Git configuration
facts [--write] · quarantine · ingest derived metadata and hash-bound raw-source governance
eval · evalpack · query file · adr routing measurements, evidence packets, filed answers, decision lifecycle
capture digest|approve|promote metadata-only digest and explicit draft promotion
hosts · check · symbols · search declared compatibility, portable checks and derived tooling
mcp · team · cursor --agent ID read-only protocol tools and explicit team cursor ownership
Read-only commands speak --json ({command, ok}) for scripts and CI. Configured Claude hooks provide orientation reminders and limited working-tree bookkeeping checks; see the hook contract and bypass limits.
Measured evidence and limits
The frozen ten-question routing fixture is measured by ctx eval, not an LLM judge. Its current result is hit@8 1.0, precision 0.15; see routing output. These measure whether expected pages were retrieved, not answer correctness, billed tokens or savings. The actual ten-question cold-start run was independently graded 8 correct and 2 partial; see raw answers, grades, and testing evidence. This is one reader/grader pair with concurrent-checkout limits; unavailable token/cost fields remain unknown. No matched with/without-wiki baseline was run, so this project does not claim measured token savings or generalized task-success improvements.
The five laws
- Decide what to build first — a line changed in a plan is free; a decision spread through the codebase is a rewrite.
- Make the hard calls on purpose — every addition gets an explicit cost recorded.
- Keep the state in files — updated while working, enforced by tooling, not goodwill.
- Never let the AI decide something important silently — conflicts are flagged to the human.
- Read cheap, then deep — index line → TL;DR → page → source. Stop at the first level that answers.
Release tracks
The skill/CLI and npm/package/plugin versions have separate identities. Tags follow the skill track; node tests/check-versions.mjs --require-tag checks each track, this mapping and the newest reachable release tag.
| Skill / CLI | Package / plugin | Release tag |
|---|
| 2.8.0 | 3.8.0 | v2.8.0 |
Docs
INSTALL.md · SKILL.md (the method agents follow) · references/ctx-cli.md (every flag) · references/operations.md (the nine playbooks) · references/llm-wiki-pattern.md (the architecture) · CHANGELOG.md
This repo vs your project: dev history (CHANGELOG, tests, this README) stays here; ctx install ships only the skill; ctx setup writes only pages about your project — no version chatter, no lineage, test-guarded on both boundaries.
Lineage & license
v1 distilled five senior-engineer AI-build courses plus audits against Anthropic docs, agents.md, OpenAI Codex guidance, GitHub Spec Kit and obra/superpowers. v2 rebuilt it on Andrej Karpathy's LLM-Wiki pattern (raw / wiki / schema; ingest / query / lint) with progressive-disclosure context engineering, git-backed staleness, and enforcement tooling.
MIT — see LICENSE. Copy, adapt, reuse.
