ClaudeLens
CLAUDE.md67 starsChanged 40 days agoMITView on GitHub
Guidance for Claude Code in this repository. The nested files load with their directory: src/CLAUDE.md, src/components/CLAUDE.md, src/components/project/CLAUDE.md, electron/modules/CLAUDE.md. Editing these files. They are loaded into every session that touches their directory, so every line has a cost. Keep a line only if an agent would make a concrete mistake without it: a command, a rule, a gotcha. They are not a changelog and not a feature catalogue — the story of a fix goes in its commit message, the reason…
- Commits and pushes
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- src/CLAUDE.mdCLAUDE.md
- arch-analysisSkill
- build-dmgSkill
- github-issueSkill
- github-prSkill
- new-claude-modelSkill
- run-appSkill
- transcript-driftSkill
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 1 is distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 36
Prefer integration to mocks.
- Very specific: line 39
Renderer tests: run in jsdom — opt in per file with a // @vitest-environment jsdom docblock.
- Very specific: line 67
Only discriminant values are ever recorded — the corpus is the user's real work.
- Distinctive: line 76
Before creating a GitHub Release, in order:
- Very specific: line 82
If the release has a feature worth telling the user about, add one entry to src/data/whats-new.ts keyed to the version you are bumping to …
- Very specific: line 88
Commit both together, e.g.
- Very specific: line 89
Create the GitHub Release with a ## Highlights section at the top.
- Very specific: line 152
IPC result shape: every handler returns { data: T | null, error: string | null }.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Guidance for Claude Code in this repository. The nested files load with their directory:
src/CLAUDE.md, src/components/CLAUDE.md, src/components/project/CLAUDE.md,
electron/modules/CLAUDE.md.
Editing these files. They are loaded into every session that touches their directory, so every line has a cost. Keep a line only if an agent would make a concrete mistake without it: a command, a rule, a gotcha. They are not a changelog and not a feature catalogue — the story of a fix goes in its commit message, the reason behind a non-obvious line of code in a comment beside it, and what a test proves in the test itself.
Commands
npm run dev / build / typecheck / lint / format / test (all in package.json).
typecheckcovers three projects: renderer (tsconfig.json), main + preload (tsconfig.electron.json) and tests (tsconfig.test.json).- The style gate is strict: Prettier is enforced repo-wide, Markdown included, and
lintruns with--max-warnings 0— fix a new warning or add an inlineeslint-disablewith a reason. - Do not launch the app to verify a change (neither
npm run devnor therun-appskill): it is unreliable in this setup. Verify withtypecheck+lint+test, add a renderer test when a hook or stream state changes, and leave the visual check to the user.
Tests
Vitest, under test/. CI (.github/workflows/ci.yml) runs format:check + typecheck + lint +
test + build on every push and PR.
- Node 22 and 24 both, because
enginessays>=22. A bound that describes an allocation isBuffer.poolSize, never a literal that happens to match it on one version (#258). - Test order is randomised (
sequence.shuffle): everyitis an independent claim. Fixtures go inbeforeEach, never in the test that happens to run first, and module-level state (resetParseCache,resetSessionTails,resetSessionReadCache, …) is reset there too. Reproduce a red run with the seed it prints:npx vitest run --sequence.seed=<n>. - Prefer integration to mocks.
session-sdk-*andsubagents-forkrun the real Agent SDK over files on disk (no model turn, no API key); theremote-*tests run the real connect script through every login shell the machine has, against a stubclaudeunder a temp home. - Renderer tests run in jsdom — opt in per file with a
// @vitest-environment jsdomdocblock; the default staysnode— against the fake preload bridgetest/helpers/fake-electron-api.ts: request methods arevi.fn()s returning the{ data, error }envelope,on*channels areChannels a test emits on, andChannel.listenerCountcatches a subscription that outlives its component. Extend the fake as tests reach further. - Mount inside
React.StrictMode, assrc/main.tsxdoes. Testing Library'srenderdoes not, and a provider that broke on StrictMode's remount once shipped with all its tests green. - Probes whose outcome depends on this machine's
~/.claudeare opt-in and never part ofnpm test:npm run census:replay,npm run graph:probe, andCLAUDELENS_PLAYBOOK_CORPUS=1 npx vitest run test/playbook-real.test.ts.
Transcript format drift
Claude Code extends the transcript format without notice, and a new row type or content block
simply never shows up in the app (#245 and #246 sat unnoticed for months). Use the
transcript-drift skill after every Claude Code upgrade and whenever a session renders
oddly; it holds the procedure.
npm run census— what we don't read: diffs the corpus's row types, subtypes, content blocks and key-paths againstscripts/transcript-manifest.mjsandscripts/transcript-baseline.json. Exit 1 on drift.npm run census:replay— what we read wrong: a sweep for content blocks thatparseContentArraydrops.- The manifest records decisions: every shape is
read(naming the module),ignored(with the reason) orcandidate(not read, and it should be). Write the verdict, thennpm run census:accept. Without a verdict the finding returns on every run; withcensus:accepta field finding is retired for good. - Only discriminant values are ever recorded — the corpus is the user's real work. A map keyed by
data (file paths, model ids, question text) collapses to
{*}. scripts/transcript-exercise.mjs --yesspends real model turns to provoke shapes; it is never part of a verify.- The
transcript-drift-watchagent is deliberately not scheduled: it writes the manifest and the baseline on its own, andcensus:acceptdestroys the evidence of a misjudged finding.
Release
Before creating a GitHub Release, in order:
node scripts/prepare-release.js— writes the locally installed Claude Code version intoclaudeCodeVersioninpackage.json. It leavesremoteMinClaudeCodeVersionalone: that one is raised by hand, only when the Remote path needs a newer CLI. It warns whensrc/data/whats-new.tshas no entry newer than the current version.- If the release has a feature worth telling the user about, add one entry to
src/data/whats-new.tskeyed to the version you are bumping to (skip it for a fix-only release): English, one or two highlights of one sentence each, and avisualthat is a real ClaudeLens component — a key ofVISUALSinsrc/components/WhatsNewDialog.tsx— never a screenshot. - Bump
versioninpackage.json(semver). - Commit both together, e.g.
chore: bump to v2.1.2, claude-code 2.1.191. - Create the GitHub Release with a
## Highlightssection at the top.
- Binaries are built by CI: pushing the
v*tag (whichgh release createdoes) runs.github/workflows/release.yml— macOS x64 + arm64, Windows, Linux, about 9 minutes — and uploads them to the existing Release without touching its notes. Don't runnpm run electron:buildor attach assets by hand; check withgh release view vX.Y.Z --json assets. Rebuild an existing tag withgh workflow run release.yml -f tag=vX.Y.Z. package-smokein CI (electron-builder --dir) is the only check that the app still packages. When a new Electron major breaks packaging on the ABI, bump thenode-abipin inoverridesinstead of reverting Electron.- macOS signing (
docs/macos-signing.md): Developer ID + notarization when the repo has the five Apple secrets, otherwise an ad-hoc signature undercom.claudelens.app— never unsigned, because macOS files Local Network and the other privacy grants under the signing identifier. The app stays unsandboxed: it reads~/.claude, drives arbitrary project dirs and spawnsclaudethrough a pty. When a signed build ships, the quarantine workaround goes stale in README,QUARANTINE_CMDin Settings → General andUpdateBanner.tsx.
Architecture
An Electron app that reads Claude Code's local data from ~/.claude/.
Main process (electron/main.ts) registers the IPC handlers by namespace: memory, cost,
claudeMd, sessions, rules, tasks, plans, workflows, teams, agents, skills,
plugins, mcp, projects, live, ai, export, markdownFile, settings, config,
prefs, telemetry, updates, search, exchange, files, images, vault, clipboard,
notifications, studio, playbook, notes, terminal, remote. The backend modules are
described in electron/modules/CLAUDE.md.
- The chat runs on the Agent SDK in streaming input mode (
modules/chat-runner.ts): one long-livedChatSessionper chat view drives onequery()fed by a push-generator, so turns ride the same warm session.startMessagepre-generates the session id,stopMessageis aninterrupt()that keeps the session,endChatdisposes it. OneChatSessionis in flight at a time; if its query dies on its own, main still emits a finalchatDoneso the composer is not stuck on Stop. - Every chat stream payload is an envelope tagged with its
sessionId(Chat*Eventinelectron/shared/chat-types.ts, the one definition shared with the renderer):useLiveChatdrops events from a superseded session instead of trusting arrival order. - Tool approvals go through the SDK's
canUseToolto a renderer dialog that queues concurrent requests and answers them one at a time; stop, end and supersede deny everything pending. /btw(sessions:sideQuestion) is answered by the live query only, and refused when the chat has no live session: a second process cannot read its prompt cache.- Watchers (chokidar):
~/.claude/projects/and the other data dirs are watched at depth 5, because workflow sub-agent transcripts sit at{hash}/{sessionId}/subagents/workflows/<runId>/. A change emitsdata:changedcarrying the namespaces it can affect (modules/data-change-scope.ts;nullmeans unknown and must invalidate everything). The live-session registry~/.claude/sessions/has its own channel,live:activeSessions, so its churn does not invalidate every query. - Remote (
remote:*,terminal:createRemote, #242/#294) is additive and removable on purpose: an upstream way to attach to a session on another machine would retire it, soterminal:create,chat-runnerand the readers are not rewired around a host. Mapis not transferable over IPC: serialize it to a plain object first.
Preload (electron/preload.ts) exposes window.electronAPI through contextBridge with
context isolation — the renderer's only seam to the main process.
Renderer (src/, see src/CLAUDE.md): one page, no router — tabs/ProjectOverview.tsx
switches on the View union in components/project/types.ts. Every React Query hook lives in
hooks/useIPC.ts (unwrap() throws on error), and useDataChangedRefetch() in App.tsx
invalidates only the namespaces a data:changed names.
Conventions
- IPC result shape: every handler returns
{ data: T | null, error: string | null }; the renderer unwraps it withunwrap(). - Project identity: data lives in
~/.claude/projects/{hash}/, wherehashis the absolute path with every non-alphanumeric character →-(/Users/foo/my.app→-Users-foo-my-app;encodeProjectHashinelectron/utils.ts). The inverse is a guess: read the real cwd withresolveRealPath. Claude Code hashes the resolved path, so a macOS temp dir lands under-private-var-folders-…. - ClaudeLens's own state (preferences, playbook, remote hosts) lives in
~/.claudelens/, apart from~/.claude—~/.claudelens-devin a dev build (modules/claudelens-dir.ts). - Memory format: topic files are YAML frontmatter (
name,description,type) plus a markdown body;MEMORY.mdindex lines are- [file.md](file.md) — description. - Fixtures are synthetic. The app reads the contributor's own
~/.claude, so nothing in the repo is copied from it: a fixture keeps a real row's shape (path depth, extensions, odd characters) with names that stand for nothing. ThePreToolUsehook.claude/hooks/guard-private-terms.shchecks what a commit, push, PR, issue or release adds against a word list kept outside the repo (~/.config/claudelens/private-terms.regex; without it the hook is a no-op).removeCommentsintsconfig.electron.jsonkeeps main-process comments out of the packaged app. - Clipboard reads go through
clipboard:readText: the packaged renderer runs fromfile://, wherenavigator.clipboardcan write but its read path needs a permission the app never grants. - The UI is English only.
- Build outputs:
dist/(Vite) anddist-electron/(tsc).
Brand palette
| Role | HEX | Notes |
| Accent | #C15F3C | Terracotta — primary brand accent |
| Paper | #FFFFFF | Base canvas (light theme) |
| Paper-2 | #F4F3EE | Warm off-white surface / cards |
| Warm gray | #B1ADA1 | Muted ink / dividers (reference hue) |
The only brand colours, encoded in src/index.css as --cl-accent, --cl-paper,
--cl-paper-2 and the warm-gray hue, lifted in [data-theme='dark']. No new accent hues: vary
lightness and chroma on the same hue (40°). --cl-ink-4 is darkened to ~#7c7669 in the light
theme so meta text meets WCAG AA on white.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

