feat(notes): session notes in ~/.trail, shown by trail ask

[anirudhkumar-nanonets]

Moves: note_saved (the supply) and the notes property on query (the demand), both in PostHog DB 11. Both are 0 on 2026-10-07 because they're new. This is the first part of the Trail brief, and it feeds connect through the trail login prompt in the cloud PR.

A session's agent can now save what it worked out, and the next session on the same code gets it before exploring. The note includes what it cost to figure out. Notes stay on the person's machine and never go into the repo, so nothing shows up in git status or in anyone's PR.

• trail note --title "…" saves a note with the body on stdin, under ## Decided, ## Tried and ruled out and ## Watch out.
  • Minutes and tokens come from the Claude Code transcript, counted since the session's last note.
  • The touched files come from git and from the files the session edited.
• Where notes go: ~/.trail/repos/<key>/notes/. The key is the remote (github.com/owner/name), or the path when there's no remote.
  • Every clone, worktree and subfolder of one repo shares one folder.
  • A submodule or nested repo gets its own.
  • A renamed remote finds its old notes through the repo's first commit.
  • A folder that holds several repos reads all of theirs.
  • A session that edited two repos leaves the note in both, each with its own files.
• Where notes show up:
  • ask prints the matching notes above the code, in both the CLI and MCP find_code.
  • The session-start hook tells the agent how many notes there are and to leave one when it's done.
  • The statusline shows the count, and trail status gets a notes row.
• The trail skill says when to reach for it. Claude Code reads only a skill's description before deciding to load it, and the description was graft's, about code search. It now also says to run trail ask before exploring and trail note when a task took real digging. The body opens with those moments instead of ending with them.
• trail init wires trail-named hooks, skill and MCP server, and replaces graft-named ones. It also makes the notes folder, and writes nothing about notes into the repo. Whether a repo is trail-wired is read from its committed wiring, so teammates on either command write the same files.
• Telemetry: note_saved with has_cost and touches_bucket, and notes on query. Titles, text and paths are never sent.

Tests: npm test, 1,413 pass. test/trail-home.test.ts covers the repo-key edge cases against real git repos and worktrees.

[trailhq-graft]

🌱 graft blast radius

5 areas changed → 7 areas can be affected. 28 dependent symbols, depth 2.
Tests: Host Configuration has tests the diff did not touch; 3 areas updated their tests.
Tag: @shhdwi — 10 of 12 areas

flowchart TB
  A0(("Host Initialization<br/>8 symbols"))
  A1(("Brain Communication<br/>7 symbols"))
  A2(("Tool Invocation<br/>4 symbols"))
  A3(("Session Metrics<br/>4 symbols"))
  A4(("Workspace Federation<br/>2 symbols"))
  AX(("2 smaller areas<br/>3 symbols"))
  classDef reached fill:#D9EDF3,stroke:#3AA7C9,stroke-width:1.5px,color:#0E313C;
  class A0,A1,A2,A3,A4 reached;
  classDef tail fill:#EEF2F3,stroke:#9AA4A9,stroke-width:1px,color:#3A4247;
  class AX tail;

Loading

Can be affected	Symbols	Nearest hop	Reached from
Host Initialization	8	src/hosts/antigravity.ts:L36-L46 installAntigravitySkill — calls, depth 1	Claude Configuration, Host Configuration
Brain Communication	7	src/brain/autopush.ts:L1-L270 autopush.ts — imports, depth 1	Claude Configuration, Contract Management +1
Tool Invocation	4	src/mcp/tools.ts:L247-L329 callSingleTool — calls, depth 1	Command Execution, Note Management +1
Session Metrics	4	src/claude/session-metrics.ts:L1-L214 session-metrics.ts — imports, depth 1	Contract Management
Workspace Federation	2	src/graph/workspace-cli.ts:L88-L97 runWorkspaceAsk — calls, depth 1	Command Execution, Note Management
Telemetry Tracking	2	src/telemetry/sessions.ts:L1-L113 sessions.ts — imports, depth 1	Contract Management
1 smaller area	1	Wiring Rewrite	see below

Who knows this code — 1 person across 12 areas

Area	Who knows it
Contract Management · changed	@shhdwi — 1 commit, last 28d ago
Claude Configuration · changed	@shhdwi — 1 commit, last 28d ago
Command Execution · changed	@shhdwi — 1 commit, last 28d ago
Host Configuration · changed	@shhdwi — 1 commit, last 28d ago
Host Initialization · affected	@shhdwi — 1 commit, last 28d ago
Tool Invocation · affected	@shhdwi — 1 commit, last 28d ago
Session Metrics · affected	@shhdwi — 1 commit, last 28d ago
Workspace Federation · affected	@shhdwi — 1 commit, last 28d ago
…4 further areas

Ownership is git history over each area's own files, weighted towards recent work (120-day half-life). Merge commits and bots are dropped, and you are dropped from your own PR. A name with no @ has no GitHub handle in its commit email — tag them by hand, or add a .mailmap entry. A suggestion from history, not a CODEOWNERS rule.

All 28 dependent symbols, grouped by area

Host Initialization — 8 symbols in 6 files

• src/hosts/antigravity.ts:L36-L46 — installAntigravitySkill (calls, depth 1)
• src/hosts/claude-global.ts:L93-L125 — installClaudeGlobal (calls, depth 1)
• src/hosts/codex-hooks.ts:L61-L90 — installCodexHooks (calls, depth 1)
• src/hosts/cursor-hooks.ts:L84-L109 — installCursorHooks (calls, depth 1)
• src/hosts/registry.ts:L1-L133 — registry.ts (references, depth 1)
• src/hosts/claude-global.ts:L68-L78 — upsertGlobalHooks (calls, depth 2)
• src/hosts/init.ts:L40-L98 — runHostsInit (calls, depth 2)
• src/hosts/init.ts:L1-L99 — init.ts (imports, depth 2)

Brain Communication — 7 symbols in 5 files

• src/brain/autopush.ts:L1-L270 — autopush.ts (imports, depth 1)
• src/brain/pull.ts:L1-L332 — pull.ts (imports, depth 1)
• src/brain/push.ts:L287-L293 — pickedAgents (calls, depth 1)
• src/brain/watch-trail.ts:L1-L395 — watch-trail.ts (imports, depth 1)
• src/brain/push.ts:L248-L279 — buildEarlyDigest (calls, depth 2)
• src/brain/push.ts:L313-L378 — buildLocalDigest (calls, depth 2)
• src/brain/wire.ts:L1-L148 — wire.ts (imports, depth 2)

Tool Invocation — 4 symbols in 1 file

• src/mcp/tools.ts:L247-L329 — callSingleTool (calls, depth 1)
• src/mcp/tools.ts:L153-L199 — callWorkspaceTool (calls, depth 1)
• src/mcp/tools.ts:L216-L244 — callTool (calls, depth 2)
• src/mcp/tools.ts:L1-L330 — tools.ts (imports, depth 2)

Session Metrics — 4 symbols in 4 files

• src/claude/session-metrics.ts:L1-L214 — session-metrics.ts (imports, depth 1)
• src/claude/state.ts:L1-L104 — state.ts (imports, depth 1)
• src/claude/stats.ts:L1-L27 — stats.ts (imports, depth 2)
• src/claude/sync-run.ts:L1-L42 — sync-run.ts (imports, depth 2)

Workspace Federation — 2 symbols in 2 files

• src/graph/workspace-cli.ts:L88-L97 — runWorkspaceAsk (calls, depth 1)
• src/graph/workspace.ts:L240-L558 — federateAsk (calls, depth 2)

Telemetry Tracking — 2 symbols in 2 files

• src/telemetry/sessions.ts:L1-L113 — sessions.ts (imports, depth 1)
• src/telemetry/track.ts:L1-L161 — track.ts (imports, depth 1)

Wiring Rewrite — 1 symbol in 1 file

• src/upkeep-run.ts:L42-L51 — rewriteWiring (calls, depth 1)

Test signal per changed area — 3 ✓ · 1 ⚠ · 1 –

Reached = a node under a test path has a resolved edge into the changed symbol. It undercounts anything called indirectly — through a CLI, a spawned process or a dynamic import — so read a low ratio as “look here”, never as a coverage gate.

• – Contract Management — 1 test file changed here: test/telemetry-contract.test.ts
• ✓ Claude Configuration — 6 of 24 reached · 3 test files changed here: test/claude-init.test.ts, test/claude-settings-merge.test.ts, test/trail-notes.test.ts
  • not reached: retrievalBody, teamNotesDirective, hookTimeoutIn, main, claudeTargets, claudeTargetsFor, wiringName, slCmd, …10 more
• ✓ Command Execution — 5 of 15 reached · 1 test file changed here: test/trail-notes.test.ts
  • not reached: repoWiredForTrail, readStdin, wholeNumber, runInitCommand, wireTarget, statusCommand, ask, fallthroughNoteFor, …2 more
• ✓ Note Management — 22 of 53 reached · 2 test files changed here: test/trail-home.test.ts, test/trail-notes.test.ts
  • not reached: attachNotes, pointerFile, add, currentBranch, git, noteAuthor, ownPath, safeUser, …23 more
• ⚠ Host Configuration — 3 of 9 reached · 5 test files reach it, none changed here
  • not reached: mergeJsonKey, removeJsonKey, isGraftCmd, stripClaudeSettings, stripCodexHooks, targets

36 test suites also reference this code

42 symbols, kept out of the diagram and the table so they cannot crowd out the areas a reviewer has to look at.

• test/ask-fusion.test.ts
• test/ask-index.test.ts
• test/ask.test.ts
• test/brain-context-files-pull.test.ts
• test/brain-push-agents.test.ts
• test/brain-trail-watch.test.ts
• test/claude-format.test.ts
• test/claude-hooks.test.ts
• test/claude-shim-resolve.test.ts
• test/claude-skill-template.test.ts
• test/claude-state.test.ts
• test/claude-statusline.test.ts
• test/claude-tally.test.ts
• test/cli-picker.test.ts
• test/generic-extract.test.ts
• test/graph-posix-paths.test.ts
• test/graphrank.test.ts
• test/hosts-antigravity.test.ts
• test/hosts-claude-global.test.ts
• test/hosts-codex-hooks.test.ts
• …16 more

⚠️ 1 changed file not in the graph (TELEMETRY.md) — no parser claims the extension, or the index predates the file.

_{graft blast · refs/graft/base...HEAD · depth 2 · 29 changed files}

Open the interactive graph → — click an area to see the code that changed, and the line that reaches it.

[anirudhkumar-nanonets]

Folded into #558, which now carries this change along with the rest of trail.