ctx — Past Mistakes, Documented

Track WHY code is the way it is.

ctx init                   →  .ctx/WHY.md + .ctx/mistakes/
ctx setup opencode         →  adds rules to AGENTS.md

ctx check src/foo.ts       →  "Workers 10MB limit forced chunked upload"
ctx add src/foo.ts "..."   →  quick note
ctx story src/foo.ts "..." →  full post-mortem with "we tried X, it failed" details

Why

AI assistants can read code. They can't read pain.

The code shows while (i < items.length). It doesn't show "we tried .map() but it ran all items and broke the early exit." That knowledge only exists in the head of whoever debugged it.

ctx captures that knowledge. Before editing, check past mistakes. After fixing something painful, write one.

Design

• Silent success = no entry. If it worked first time, nothing is written.
• Two layers: WHY.md for quick lookup, mistakes/ for full post-mortems.
• Lazy-loaded: ctx check greps WHY.md — only matching lines returned. Full stories are never read unless the AI explicitly opens them.
• Bash + awk. Zero deps. Works everywhere.

Install

npm install -g ctx-sh

Or manually:

curl -fsSL https://raw.githubusercontent.com/pantorn/ctx/main/ctx.sh -o /usr/local/bin/ctx
chmod +x /usr/local/bin/ctx

Quick start

cd my-project

# 1. Initialize
ctx init

# 2. Wire your AI
ctx setup opencode

# 3. Quick note after a fix
ctx add src/lib/upload.ts "Workers 10MB limit forced chunked upload"

# 4. Full post-mortem after a painful debug
ctx story src/lib/upload.ts "Workers 10MB limit" <<'STORY'
## What we tried
1. Increased body parser limit — didn't help. Still 413.
2. Checked Worker logs — nothing. No error logged.
3. Found 413 in nginx access logs — it never reached the Worker.

## Root cause
Cloudflare Workers hard limit is 10MB for fetch().
Nginx intercepts and returns 413 BEFORE the Worker runs.

## Fix
Split files into 5MB chunks. ChunkedUploadService in lib/chunked.ts.

## What to preserve
Must stay under 10MB per request. If Workers raises the limit
or you switch to R2 direct upload, replace the whole thing.
STORY

Next session

ctx check src/lib/upload.ts
# → ## 2026-06-17: Workers 10MB limit
# → Files: src/lib/upload.ts
# → → Full story: .ctx/mistakes/2026-06-17-workers-10mb-limit.md

AI reads the short entry. If it's just fixing a typo, it skips the story. If it's refactoring upload, it reads the full story first.

Commands

| Command | Description | |---|---| | ctx init | Create .ctx/WHY.md + .ctx/mistakes/ | | ctx check <file> | Show past mistakes for a file | | ctx add <file> <msg> | Quick note to WHY.md | | ctx add <file> | Quick note from stdin (Ctrl+D) | | ctx story <file> "Title" | Full post-mortem (reads stdin) | | ctx setup opencode | Add rules to AGENTS.md | | ctx setup cursor | Create .cursor/rules/ctx.mdc | | ctx setup claude | Add rules to CLAUDE.md | | ctx setup aider | Add rules to .aider.custom-rules.md | | ctx tree | Show project tree | | ctx help | This message |

The .ctx/ format

my-project/
  .ctx/
    WHY.md              ← short entries with file paths + story links
    mistakes/           ← full post-mortems, one per scar
      ├── 2026-06-17-workers-10mb-limit.md
      └── 2026-06-10-auth-race-condition.md

WHY.md

## 2026-06-17: Workers 10MB limit (src/lib/upload.ts)
Files: src/lib/upload.ts
→ Full story: .ctx/mistakes/2026-06-17-workers-10mb-limit.md

mistakes/2026-06-17-workers-10mb-limit.md

# Workers 10MB limit

**File:** src/lib/upload.ts
**Date:** 2026-06-17

## What we tried
1. Increased body parser limit — didn't help.
2. Checked Worker logs — nothing.
3. Found 413 in nginx logs.

## Root cause
Workers hard limit 10MB. Nginx masks the error.

## Fix
ChunkedUploadService, 5MB slices.

AI Integration (AGENTS.md)

## ctx — Project Mistakes

- Before editing a file, run `ctx check <filepath>` for past mistakes.
- After fixing something painful, run `ctx add <filepath> <reason>`.
- For full post-mortems, run `ctx story <filepath> "Title"`.

License

MIT