haze-wiki

A Claude Code skill that turns every coding session into permanent, queryable knowledge.

haze-wiki is an LLM Wiki for Claude Code (and Cursor). It auto-captures your conversations, records your decisions, and grows a self-maintaining knowledge graph in your project — so future sessions start with relevant context loaded instead of from zero.

Inspired by Andrej Karpathy’s “LLM as Compiler” / Vannevar Bush’s Memex: a layered vault of immutable raw sources (raw/) plus an LLM-curated knowledge layer (wiki/), wired together by lifecycle hooks.

The Problem It Solves

A typical week with Claude Code: 30 sessions, dozens of decisions, three deep research dives, hundreds of file edits. After two weeks you’ve forgotten 80% of it. The next session starts from zero context — you re-explain the architecture, re-derive the same trade-off analysis, re-paste the same snippets.

haze-wiki makes the past stick. Every session is auto-captured. The wiki self-maintains. Future sessions load the relevant slice of past knowledge automatically — without you remembering to do anything.

SESSION 1 → captured → ingested → wiki/ pages
                                       │
SESSION 2 ← hot.md context ← index.md ─┘
   │
   produces new knowledge → captured → ingested → wiki/ pages
                                                       │
SESSION 3 ← compounds ← compounds ←────────────────────┘

Knowledge compounds. Sessions get smarter.

How It Works — A Session Lifecycle

Here is what haze-wiki does around a single Claude Code session, after you’ve run /haze init once:

Before you type — `SessionStart` hook fires

Reads wiki/hot.md (recent context cache) and injects it into Claude’s context
Reads wiki/index.md (catalog of all wiki pages) so Claude knows what’s already filed
Reports any files in raw/ that haven’t been ingested yet (so you can /haze ingest --new if you want)

During the session — `PostToolUse` hook fires on every file edit

Tracks every Edit / Write tool call to wiki/code-journal.md
Builds a record of “what code changed” parallel to “what was discussed”
5-second timeout — never blocks Claude

If the conversation auto-compacts — `PostCompact` hook fires

Claude Code shortens long conversations to fit the context window
This hook re-injects hot.md + index.md so the post-compaction context still has the wiki at hand

When the session ends — `Stop` hook fires

Copies the full conversation transcript (JSONL) to raw/transcripts/<timestamp>.jsonl
Prints a reminder to update hot.md if the wiki changed this session
10-second timeout

When you choose to ingest — `/haze ingest`

LLM reads new files in raw/ (transcripts, articles, anything you’ve dropped in)
Updates concept pages in wiki/concepts/: adds new ones, cross-links existing ones, deduplicates
Appends a line to wiki/log.md
Regenerates wiki/index.md

After a few cycles you have a knowledge graph that: - Loads automatically each session - Surfaces past decisions when relevant via /haze lookup - Cross-links concepts across projects (via closure architecture — see below)

The Four Hooks

Hook	Trigger	What it does	Configurable?
`SessionStart`	Session opens (startup or resume)	Inject `hot.md` + `index.md` into context; report pending `raw/` files	`matcher: startup\\|resume`
`PostToolUse`	`Edit` or `Write` tool fires	Append entry to `wiki/code-journal.md`	`matcher: Edit\\|Write`, 5s timeout
`PostCompact`	Conversation auto-summarized	Re-inject `hot.md` + first 50 lines of `index.md` so wiki stays in view	Inline command
`Stop`	Session ends or is interrupted	Save transcript to `raw/transcripts/`; print update-`hot.md` reminder	10s timeout

All four are configured in .claude/settings.json as type: command hooks. They are non-blocking — a hook failure surfaces as a soft error in Claude Code but never aborts the session.

The hook scripts live under haze-wiki/hooks/ and use absolute paths (set up by /haze init), so they work regardless of your current working directory.

What Gets Automated

After /haze init, you no longer have to remember to:

✅ Save your conversations — Stop hook captures every transcript
✅ Surface past context — SessionStart hook loads it
✅ Write summaries — LLM does this during /haze ingest
✅ Cross-link related concepts — LLM detects + links during ingest
✅ Track which files you edited — PostToolUse logs them
✅ Survive context compaction — PostCompact re-injects the wiki
✅ Keep the index up to date — regenerated on every ingest
✅ Know what’s not ingested yet — surfaced at session start

You still drive:

🎯 When to /haze ingest (after meaningful sessions, or batch via /haze ingest --new)
🎯 What sources to drop into raw/ (articles, PDFs, transcripts, screenshots)
🎯 High-level vault organization (parent vaults, project leaves)
🎯 Deep research investigations via /haze shadow-clone

Closure Architecture — Multi-Level Vaults

Vaults can link upward. Knowledge flows from leaves to root:

~/haze-wiki/              ← global vault (top)
    │
    ├── ~/team-vault/      ← team vault, linked to global
    │       │
    │       ├── ~/proj-a/  ← project leaf
    │       └── ~/proj-b/  ← project leaf
    │
    └── ~/personal-vault/  ← linked to global directly

Set up with --parent flags:

# Global vault (root of the closure)
cd ~/haze-wiki && /haze init

# Team vault (links to global)
cd ~/team-vault && /haze init --parent ~/haze-wiki

# Project (links to team)
cd ~/my-project && /haze init --parent ~/team-vault

/haze push <concept> propagates a concept page from leaf → team → global. The global vault becomes a knowledge graph spanning all your projects — Karpathy-style “LLM as Compiler” applied to your entire workflow.

Reference implementation: a closure-vault PoC with 119 leaf workspaces (60 research + 59 Go services) synthesized into 17 hubs + 6 executive concept pages.

Shadow-Clone — Parallel Research (影分身)

For big-picture investigations where one agent isn’t enough:

/haze shadow-clone "compare cursor vs claude code hook systems"

This spawns 3–8 parallel research agents (a 影分身 / shadow-clone), each tackling a sub-topic. Each writes to raw/shadow-<topic>-<date>/ as an independent markdown file. After all clones return, you can /haze ingest to synthesize them into linked concept pages.

A real run on “the Cursor port story” (5 agents, ~$2 of tokens):

5 parallel research files (1556 lines combined)
7 wiki concept pages generated on ingest
1 design doc committed to the dev repo

Reads like a research team. Ships in 5 minutes instead of 5 days.

Sub-Commands Reference

Command	Purpose	When to use
`/haze init`	Scaffold wiki + install hooks	One-time per project
`/haze init --parent <path>`	Link to an upstream vault	Closure architecture
`/haze init --cursor`	Force Cursor port files	If `.cursor/` not yet present
`/haze init --no-cursor`	Skip Cursor port files	If you only want Claude Code
`/haze status`	Vault stats — page count, pending files	Daily sanity check
`/haze check`	Verify hooks + config integrity	Debug
`/haze ingest [file]`	Process a single source	Quick one-off ingests
`/haze ingest --new`	Batch ingest all pending `raw/` files	End-of-day workflow
`/haze ingest --poc`	Synthesize concept pages from `poc/*/` folders	For workspaces with PoCs
`/haze ingest --poc --dry-run`	Preview ingest, no writes, token estimate	Cost check first
`/haze ingest --poc <name>`	Re-index one POC, force overwrite	After PoC evolved
`/haze lookup <topic>`	Search wiki + inject relevant pages	Bring past context into chat
`/haze push [file]`	Send concept page upward to parent vault	Manual closure sync
`/haze config`	Show/edit vault config	Tweak ingest behaviour
`/haze shadow-clone <topic>`	Spawn N parallel research agents	Big investigations
`/haze update`	Re-run installer to pull latest skill version	Stay current
`/haze reinit`	Re-run init without overwriting wiki content	After skill updates
`/haze reset`	Tear down + reinstall (destructive on hooks)	Last resort

Multi-Editor Support (beta)

/haze init auto-detects Cursor (looks for .cursor/) and writes a parallel set of port files so the same wiki works from either editor:

AGENTS.md (the cross-editor standard) + a CLAUDE.md → AGENTS.md symlink
.cursor/commands/haze.md — $ARGUMENTS dispatch (stable in Cursor v1.6+)
.cursor/rules/haze-wiki.mdc — alwaysApply rule with @file injection of hot.md + index.md
.cursor/hooks.json — sessionStart, stop, afterFileEdit, preCompact (Cursor v1.7+)
.cursor/hooks/*.sh — symlinks back to haze-wiki/hooks/*.sh (one script set, two consumers)

⚠ Caveat: Cursor v3.x has a confirmed .md corruption bug (forum #158747, fix targeted v3.3). Until v3.3 ships, use Cursor Nightly for multi-editor mode. See docs/cursor-support.md in the dev repo for open behaviour questions.

To skip Cursor entirely: /haze init --no-cursor.

Vault Structure (after `/haze init`)

your-project/
├── .claude/
│   └── settings.json              ← hooks wired here, absolute paths
└── haze-wiki/
    ├── haze-config.json           ← per-vault config (parent links, etc.)
    ├── hooks/
    │   ├── lib/                   ← shared helpers (cwd resolution, etc.)
    │   ├── lib/debug-log.sh       ← rotating debug logger (sourced by hooks)
    │   ├── session-start.sh       ← SessionStart hook script
    │   ├── track-code-change.sh   ← PostToolUse hook script
    │   └── capture-transcript.sh  ← Stop hook script
    ├── log.md                     ← rotating DEBUG log (hook/skill behaviour, 1MB default)
    ├── raw/                       ← IMMUTABLE source layer
    │   ├── transcripts/           ← auto-captured conversations
    │   ├── shadow-*/              ← multi-agent research outputs
    │   └── *.md *.pdf             ← user-dropped sources
    └── wiki/                      ← LLM-MAINTAINED knowledge layer
        ├── hot.md                 ← recent context (auto-loaded each session)
        ├── index.md               ← catalog of all pages
        ├── log.md                 ← append-only USER-FACING activity log
        ├── code-journal.md        ← code-edit log (PostToolUse output)
        ├── concepts/              ← one file per concept
        └── sessions/              ← transcript summaries (post-ingest)

Two logs, distinct purposes: - haze-wiki/log.md — rotating debug log for hook + skill behaviour. Default 1 MB cap, configurable via haze-config.json’s debug_log_max_mb (e.g. set to 10 for a 10 MB cap). When oversize, the oldest ~50% is pruned in place. For troubleshooting. - haze-wiki/wiki/log.md — append-only user-facing activity log. Format ## [YYYY-MM-DD] <op> | <summary>. Never rotated. For history and audit.

Layer rules:

raw/ is immutable. You add files; the wiki layer reads them. Nothing is mutated.
wiki/ is LLM-maintained. /haze ingest creates, updates, and cross-links pages.
.claude/settings.json is wired with absolute paths so hooks work from any cwd.

Install

Two installers — pick by editor:

Claude Code users (global skill)

curl -fsSL https://haze-gitlab.sssjiwjs.app/haze-public/haze-wiki/-/raw/main/install.sh | bash

Writes the skill to ~/.claude/skills/haze/ (machine-wide, one-time). Then cd into a project and run /haze init from inside Claude Code to scaffold the vault.

Cursor users (per-workspace, no global writes) — beta

cd your-project
curl -fsSL https://haze-gitlab.sssjiwjs.app/haze-public/haze-wiki/-/raw/main/cursor-install.sh | bash

Lays down .cursor/, AGENTS.md, CLAUDE.md → AGENTS.md symlink, and the haze-wiki/ scaffold in $(pwd). Nothing touches ~/.claude/. Per-project install — re-run in each workspace you want to use it in.

⚠ Cursor v3.x has a confirmed .md corruption bug (forum #158747, fix targeted v3.3). Use Cursor Nightly until v3.3 ships.

Both editors in one workspace

Run cursor-install.sh first (lays down the workspace files + CLAUDE.md symlink), then run install.sh to also get the Claude Code skill globally. The two installers don’t conflict.

Manual

git clone https://haze-gitlab.sssjiwjs.app/haze-public/haze-wiki.git
cp -r haze-wiki/.claude/skills/haze ~/.claude/skills/   # Claude Code skill
# or: cp -r haze-wiki/templates/cursor/ /target/.cursor/  # Cursor port files
rm -rf haze-wiki

Update

Re-run whichever install one-liner you used — both installers replace the existing files with the latest from main:

# Claude Code skill
curl -fsSL https://haze-gitlab.sssjiwjs.app/haze-public/haze-wiki/-/raw/main/install.sh | bash

# Cursor workspace (pass --force to overwrite existing haze-wiki/)
curl -fsSL https://haze-gitlab.sssjiwjs.app/haze-public/haze-wiki/-/raw/main/cursor-install.sh | bash -s -- --force

Inside Claude Code: /haze update runs the global skill installer.

Quick Start

cd your-project
claude

# Inside Claude Code:
/haze init        # scaffold + install hooks
/haze status      # confirm everything's wired

Now drop sources into haze-wiki/raw/ (articles, PDFs, transcripts) and run:

/haze ingest --new

After 3–4 sessions you’ll have a self-growing knowledge graph that survives every restart.

Requirements

Claude Code (or Cursor v1.7+ for multi-editor mode)
jq — used by hooks for transcript parsing
bash — POSIX-ish, hooks tested on macOS + Linux

License

MIT

haze (霞) — drifting cloud, ephemeral but persistent. This tool fixes the ephemeral part.