Skip to content
ctxfolio
GitHubInstall the skill
Menu

Open source context infrastructure

Context is compiled,
not retrieved.

Give coding agents a source-backed markdown wiki, so each session starts with context instead of starting over.

Install the skill Read the source
The context workspaceInteractive, synthetic example
Source codesrc/auth/**Compiled wikicontext/Next sessionread · verify · continue
synthetic wiki demo: context/codebase/modules/auth.md 
---
title: Authentication
type: module
status: active
covers: src/auth/**
confidence: verified
updated: 2026-10-02
---

TL;DR

  • Session tokens are httpOnly cookies with a 15 minute lifetime.
  • The refresh token rotates on every use. The old one is void at once.
  • Never log a token payload. Lint catches token-shaped strings.
Contract
POST /auth/login returns 200 and two cookies. It returns 429 after 5 attempts in 60 seconds.
Invariant
A revoked session voids its refresh token in the same request. There is no grace window.

Synthetic wiki example, not this repository. With JavaScript it simulates a commit, a review signal, a page update and a stamp. No CLI command runs here.

release
latest release
tests
run evidence
CLI dependencies
0
license
MIT

Node 22/24, per runtime declarations. Supported-platform results: published baseline.

Release v2.8.0

Retrieval asks the same question twice. Compilation writes the answer down.

Repeated exploration is a workflow cost. This skill asks the agent to write down what it learns, once, at change time, into a markdown wiki. Later sessions can start from those files, then verify against source.

The workflow aims to reduce repeated exploration. Token savings and answer-quality improvements have not been measured in an evaluation.

Without persistent project notes, a coding agent can re-derive the same facts. It greps. It reads. It reasons from scratch. The work is thrown away when the session ends, and the next session pays for it again.

This system has the agent write the understanding down instead. Not into chat, and not into a folder of stale notes. Into interlinked markdown pages with front matter, a TL;DR, and a covers glob that ties each page to the code it describes.

A fresh session, a teammate, or a different tool starts from those files. The orientation policy sets a reading target, not a measured token guarantee. Source checks still matter.

Record understanding at change time. Reuse it at read time, with source checks.

references/llm-wiki-pattern.md, after Andrej Karpathy’s LLM wiki
Workflow comparison, with illustrative token assumptions rather than measured savings.
dimension agent explores each session compiled wiki
when synthesis happens every task, from scratch once, at change time
assumed reading per session 20k to 100k tokens, model inputs 2k to 8k tokens, model inputs
knowledge of why absent. code shows what, not why decisions, invariants, gotchas recorded
consistency across tools each agent builds its own model one shared model
contradictions invisible structural issues flagged; meaning reviewed by a human

The cost of forgetting, compounded.

This model repeats the same assumed reading cost across sessions. Move the counter and read the modeled total.

Illustrative assumptions from the existing COST model, following the wiki pattern. Not empirical bounds or a benchmark.

Illustrative token-cost assumptions per session, multiplied across 40 sessions. Not measured performance.
mode per session by session 40
re-explores the repo 20k to 100k 0.8M to 4.0M
reads the compiled wiki 2k to 8k 80k to 320k
output quality unmeasured; no degradation threshold established

Illustrative COST model, not measured usage or quality. Totals exclude maintenance and output costs. With JavaScript, drag the counter to compare the same assumptions.

Raw, wiki, schema.

Three layers, three owners, three operations. The pattern is Karpathy’s LLM wiki, applied to a repository. 

raw      immutable. the human curates
wiki     agent writes, human reviews
schema   human and agent co-evolve

  1. Raw

    the human curates

    The code as the source of truth, plus context/raw/ for PRDs, meeting notes, vendor docs and exports. Policy forbids editing raw evidence; implementation work still changes source code. Where a source disagrees with a page, the conflict goes to the human.

  2. Wiki

    agent writes, human reviews

    Interlinked pages under context/. Every page has front matter, a TL;DR first, and a cap of 160 lines. Pages record why, contracts, invariants and gotchas. They never restate the code.

  3. Schema

    co-evolved

    AGENTS.md is read first and stays at 120 lines or fewer. Its Lessons section turns each of your corrections into one permanent line. context/index.md routes a task to the pages worth reading. Its catalog is regenerated from front matter; routing and meaning still need review.

The three operations, plus update-on-change.
operation what runs
ingest Read the source. Summarize it. Update the affected pages, usually 3 to 15. Log it.
query Run ctx brief. Read TL;DRs. Answer with citations. File a reusable answer as a page.
lint Check structure, git freshness, orphans and links. Errors exit 1. Semantic truth still needs review.
update-on-change Code changed, so review the covering pages in the same diff. Bookkeeping alone cannot prove their meaning is true.

The core loop.

Seven steps, every unit. Recording is not a chore at the end of a pull request. It is part of the diff, and tooling checks it.

Step 5 prompts review against changed code. The next section illustrates an initial Stop block, not a guarantee that the documentation is true.

  1. Orient

    Read AGENTS.md, index.md, memory.md. Skim the tracker. Run ctx brief. Read routed pages before exploring source. The reading target is guidance, not a measured token result.

  2. Plan

    Write the spec. Add the ledger entry. Ask five questions or fewer, one at a time. The human reviews the scope and rejects weak plans; review time depends on the task.

  3. Build

    Start one unit. The command line enforces one at a time. Interface first with mock data, logic second, and the logic ships its failing test first.

  4. Record

    Write decisions, bugs and lessons as they happen. A correction that is not written down is a correction you will receive again.

  5. Context-diff

    Run ctx impact. Fix every page it marks. Cover every uncovered file. Then stamp. This is the step the next section demonstrates.

  6. Verify

    Lint, typecheck, build. Drive the real flow. Review against the spec checklist. Scale the effort to the risk.

  7. Close

    Regenerate the index. Lint. Log the build. Write memory.md with the exact next step. Then a cold agent can continue from the files alone.

The Stop hook flags missing updates.

With a configured Claude hook and Git, an initial Stop can exit 2 when working-tree changes lack page or recording updates. It checks bookkeeping, not semantic truth.

The hook contract permits repeat passes with literal stop_hook_active: true. No Git or malformed input skips the audit; already committed changes are outside this working-tree check. 

hooks   SessionStart  re-inject orientation
        Stop          check working-tree bookkeeping

lint    structural and freshness signals
doctor  scaffold and adapter checks, not loader proof
tests   published evidence linked below

Illustrative legacy v2.4.x Stop transcript, not current CLI output or measurement. Step with the rail, or press keys 1 to 6. Current verification evidence is separate.

illustrative legacy v2.4.x transcript, six steps

$ node context/ctx.mjs task start 07
tracker: Feature 07 -> In progress (1 unit in progress, max 1)

$ edit src/auth/session.ts    # rotate refresh tokens
$ create src/auth/rotate.ts   # synthetic helper
$ edit src/api/routes/sessions.ts

$ exit
[ctxfolio] Before ending the session:
- Context pages not updated for changed code: context/codebase/modules/auth.md,
  context/api-contracts.md. Update them (or confirm nothing they describe changed)
  then run `node context/ctx.mjs stamp <page>`.
exit 2

$ node context/ctx.mjs impact
changed code (working tree):
  M src/auth/session.ts
  A src/auth/rotate.ts
  M src/api/routes/sessions.ts
pages that must be updated:
  x context/codebase/modules/auth.md     covers src/auth/session.ts
  x context/api-contracts.md             covers src/api/**
uncovered files (BLIND SPOT):
  ! src/auth/rotate.ts                   add to a covers: glob or ctx new module

$ edit context/codebase/modules/auth.md   # review; expand covers to src/auth/**
$ edit context/api-contracts.md           # review the changed contract
$ node context/ctx.mjs stamp context/codebase/modules/auth.md context/api-contracts.md
stamped 2 page(s): updated 2026-10-07, verified_at 8ae5d7d

$ node context/ctx.mjs task done 07 -m "rotate refresh tokens; session test"
tracker: Feature 07 -> Completed
$ edit memory.md   # record next step

$ exit
hook stop: pass. illustrative bookkeeping result, not semantic verification.

One file, project-local commands.

setup copies scripts/ctx.mjs to context/ctx.mjs. Your project carries the tool with it. The copied CLI has zero package dependencies; the website uses a separate frontend toolchain. Current CLI contract.

Commands documented with --json emit JSON. Every payload carries command and ok. Continuous integration reads ok as a health signal, not correctness proof. 

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  git-based freshness and page-update signals
index · log · new · archive          catalog, timeline, scaffolds, growth rotation
doctor · install · hook              structural checks, installer, Claude hooks

Illustrative legacy v2.4.x examples, not current CLI output or measurements. With JavaScript, pick brief, impact, stale, lint, doctor, task list, coverage, status, rules, tools, archive or index. See the current CLI contract alongside.

Detected, not assumed.

ctx setup reads the manifests that exist. It classifies the shape: web-app, api, cli, library, mobile, data or monorepo. Then it scaffolds only what fits.

A FastAPI repository gets no Next.js flavoured pages. A docs repository gets no testing page. On existing code, setup drafts codebase/map.md from the real file census, with confidence: inferred.

Files that ctx setup writes into your repository.
piece what it does
AGENTS.md The schema every agent reads first. 120 lines or fewer. Its Lessons section turns each correction into a permanent one-liner.
context/ The wiki: router index, append-only log, architecture, standards, decisions, codebase map, module pages with covers globs, feature specs, immutable raw.
progress-tracker.md The task ledger: in progress, max one; blocked; up next; completed. Moved by ctx task, never by hand.
.claude/rules/ Path-gated conventions. A rule loads only when an agent touches matching files. Zero tokens spent on what does not apply.
.claude/agents/ Native access to canonical .agents/ roles, with project-local memory. Verify actual host loading.
docs/ Human-facing docs. Agents read context. One fact, one home, linked and never duplicated.
memory.md Current state, exact next step, working set, open questions, context debt. Written at session end, read at session start.
context/ctx.mjs The zero-dependency tool, refreshed on every re-run of setup.

Setup preserves filled pages and refreshes its CLI with a reported backup when needed. Doctor checks scaffold/version wiring, not actual host loading. See the setup contract.

One unit. One branch. One owner.

The wiki is a committed artifact, so treat it like code. Branches own units, merges reconcile, and tooling catches collisions. Nobody negotiates in chat.

Per-unit files are the concurrency trick. Two people building two features edit two different files. Per-person files are gitignored, so nobody’s scratch leaks into anyone’s checkout.

synthetic legacy v2.4.x ledger

## In progress   (max one)
- Feature 07  refresh token rotation       @ana   branch feat/07

## Blocked
- Feature 09  stripe webhook replay        @ravi  waiting on sandbox key

## Up next
- Feature 10  session list pagination
- Feature 11  audit log export

## Completed
- Feature 06  login rate limit             2026-09-28
- Feature 05  password reset flow          2026-09-21

Illustrative legacy v2.4.x ledger, not this repository or a measured lint run. With JavaScript, simulate a collision and its reviewed resolution.

Where collisions happen, and which tool catches them.
shared file collision caught by
progress-tracker.md two branches claim Feature NN lint error: listed twice
feature-specs/ two specs share a number lint flags duplicate IDs; review and renumber
decisions.md both branches write D-07 lint error: duplicate id
log.md both appended append-only format; review merge conflicts
a module page both edited the same area keep both facts, then stamp

The method in five laws.

Everything else in SKILL.md serves these five. Lint rules and hooks check parts of the workflow; review and host permissions remain separate.

  1. Decide what to build first.

    A line changed in a plan is free. A decision spread through the codebase is a rewrite.

  2. Make the hard calls on purpose.

    Every addition gets an explicit cost recorded in decisions.md: the options, the lost alternative, the cost paid, reversibility, and the correctness policy.

  3. Keep the state in files.

    The policy asks the agent to update them while working. Tooling flags missing bookkeeping; it cannot guarantee that the agent follows the policy.

  4. Never let the AI decide something important silently.

    Conflicts and gaps are flagged to the human. Every guess the text prevents is a decision that stays with you.

  5. Read cheap, then deep.

    Index line, then TL;DR, then the full page, then source code. Stop at the first level that answers.

Prompts are products.

Specs, subagent briefs, clarify questions and Lessons follow ASD-STE100, the aerospace documentation standard, as writing guidance rather than a certified compliance claim. In prompts, clear wording helps expose assumptions.

ASD-STE100 rules, with a weak and a strong example each.
rule weak clear
one action per sentence The user can upload a file and it should be parsed and stored. Accept one .csv file. Parse it with the rules in data-model.md. Store rows in uploads.
name the actor The data is validated then saved. The API validates the payload. The API saves the row.
exact numbers A few retries, small file. 3 retries, 2 s apart. File size 5 MB or less.
state the result Do not make it slow or broken. The list renders in under 200 ms for 1,000 rows.
split conditions If signed in and the plan allows and the file is small, allow upload. Allow the upload only when all three are true: the user is signed in; the plan allows uploads; the file is 5 MB or less.

Tested on itself.

This repository runs its own context system. The 2026-10-21 published main baseline run passed all six Ubuntu/macOS/Windows Node 22/24 test jobs. Each reported 132 passed, 0 failed, 0 skipped; strict self-context checks also passed. Testing evidence owns the dated results, not the demo fixtures.

Development history stays here: the changelog, the tests, this README. ctx install ships only the skill. ctx setup writes only pages about your project. Both boundaries are test-guarded.

ci live workflow latest release CLI dependencies 0 Node 22/24 published tag checks passed MIT claude code, codex, cursor, copilot, gemini, qoder

Give your agent the repo, not the rerun.

Ctxfolio scaffolds a populated standard wiki; explicit full setup adds profile extras and a codebase draft. Doctor checks structural wiring, not live host loading or permissions. Install prerequisites and recovery limits.

Or tell your agent: “Run npx ctxfolio@3.8.0 setup from this repository’s root.” Package: ctxfolio on npm.

  1. Set up Ctxfolio from your project root. Windows needs Developer Mode or symlink privilege for native links.

    npx ctxfolio@3.8.0 setup

  2. Optional: install the global ctx command, then set up any project from its root.

    npm install -g ctxfolio@3.8.0 && ctx setup

  3. Work with your own paths and unit number. The commands below are illustrative.

    node context/ctx.mjs brief src/auth/login.ts
node context/ctx.mjs task start <your-unit>