Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"mcpServers": {
"trail": { "command": "npx", "args": ["-y", "@trailhq/trail-code", "mcp"] }
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: "The MCP Registry listing reads the npm package, so the repo keeps the graft package name"
author: Shrish
date: 2026-10-29
branch: feat/mcp-directory-listing
cost: { minutes: 51, tokens: 345870 }
id: l-8e6ab5f6
scope: repo
status: active
src: agent
touches:
- package.json
- scripts/pack-trail.mjs
- server.json
- scripts/pack-graft.mjs
- test/graft-to-trail.test.ts
---

## Decided
- Trail Code is listed in the official MCP Registry as io.github.trailhq/trail-code. The registry only accepts the entry when the npm package it names carries a matching mcpName, so only @trailhq/trail-code carries it. It is added where the trail package is laid out, not in the repo's package.json.
- Shrish decided (2026-10-30) the repo's package.json keeps the @nanonets/graft name. Echoic's listing checklist asked for the rename, but no directory needs it: the registry reads npm, Cursor Directory reads .mcp.json, and the rest are submitted by hand.

## Tried and ruled out
- Renaming the repo's package to @trailhq/trail-code and laying out graft from it instead: 4 tests broke, because they assume this checkout runs as graft (the postinstall nudge, the upgrade advice under npx, the graft-to-trail move).
- One package with both the trail and graft commands, as the checklist suggested: anyone with both packages installed would get a clash on the graft command.

## Watch out
- The registry entry must pass the `mcp` argument: bare `npx @trailhq/trail-code` starts the CLI, not the MCP server. Its description must be 100 characters or less.
- The entry names a fixed npm version and does not follow npm by itself. Bump both version fields and publish it again when a release should be what directories show.
- Publishing under io.github.trailhq/ needs `mcp-publisher login github` by a trailhq org member.

In the code:
- scripts/pack-trail.mjs sets mcpName; server.json is the registry entry; .mcp.json at the root is for Cursor Directory.
- Check the entry with `mcp-publisher validate`, publish with `mcp-publisher publish`.
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
title: "The MCP Registry listing reads the npm package, so the repo keeps the graft package name"
author: Shrish
date: 2026-10-30
branch: feat/mcp-directory-listing
cost: { minutes: 27, tokens: 274615 }
id: l-5a79b41c
scope: repo
status: active
replaces: l-8e6ab5f6
src: agent
touches:
- package.json
- scripts/pack-trail.mjs
- server.json
- ".github/scripts/npm-downloads-badge.mjs"
- ".github/workflows/npm-downloads-badge.yml"
- README.md
---

## Decided
- Trail Code is listed in the official MCP Registry as io.github.trailhq/trail-code. The registry accepts the entry only when the npm package it names carries a matching mcpName, so only @trailhq/trail-code carries it, added where the trail package is laid out.
- Shrish decided (2026-10-30) the repo's package.json keeps the @nanonets/graft name. No directory needs the rename: the registry reads npm, Cursor Directory reads .mcp.json, the rest are submitted by hand.

## Tried and ruled out
- Renaming the repo's package to @trailhq/trail-code: 4 tests broke, because they assume this checkout runs as graft.
- One package with both the trail and graft commands: installing both packages would clash on the graft command.
- Publishing after the plain GitHub device login: the registry refused with 403, because that login can't read the org role and only allows io.github.<your-user>/*.

## Watch out
- Publishing under io.github.trailhq/ needs a trailhq owner signed in with a classic GitHub token that has read:org, or a GitHub Actions run (OIDC). The registry's sign-in lasts minutes, so run the login and the publish in one line.
- The entry must pass the `mcp` argument (bare `npx @trailhq/trail-code` starts the CLI), and its description must be 100 characters or less.
- The entry names a fixed npm version; bump both versions and publish it again when a release should be what directories show.

In the code:
- scripts/pack-trail.mjs sets mcpName; server.json is the entry; .mcp.json is for Cursor Directory.
- `mcp-publisher validate`; `mcp-publisher login github --token <read:org token> && mcp-publisher publish`.
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
---
title: "Packing the graft package rebuilds it even with --ignore-scripts, which drops the telemetry key unless it's still set"
author: Anirudhkumar-nanonets
date: 2026-11-16
branch: release/0.30.2
id: l-87a404a2
scope: repo
status: active
src: agent
touches:
- scripts/stamp-telemetry-key.mjs
- scripts/pack-trail.mjs
- package.json
---

## Decided
- Keep `GRAFT_POSTHOG_KEY` (and `GRAFT_POSTHOG_HOST`) set in the environment for the whole pack, not just the stamp, so the rebuild `npm pack` starts stamps the key again. Then check each tarball's key length before publishing, as the release order already says.
- Publishing a `.tgz` runs none of the package's scripts, so the tarball you checked is exactly what ships.
- 0.30.2 went out as `@trailhq/trail-code` only: the publishing account had no write access to `@nanonets/graft`, and the fix (share-session) only matters in the trail package. graft stayed at 0.30.1.
- Without the key at hand, it can be read from an installed earlier release's `dist/telemetry/key.js` (`posthogKey()`, `posthogHost()`) straight into the environment, never printed.

## Watch out
- On npm 10.9.9, `npm pack --ignore-scripts` at the repo root still ran `prepare` (build, then stamp). With the key already unset, dist was rebuilt after the stamp and the graft tarball shipped an empty key, while `build/trail` (copied earlier by pack-trail) kept it. Nothing failed or warned; only the key-length check caught it.
- With 2FA set to auth-and-writes, `npm publish` waits for a browser approval and opens it only on Enter in that terminal. Give the person the printed npmjs.com/auth/cli link instead.
- The registry took about 5 minutes to list the new version after npm printed the `+ package@version` line.

In the code: scripts/stamp-telemetry-key.mjs, scripts/pack-trail.mjs, package.json `prepare` (`npm run build && node scripts/stamp-telemetry-key.mjs`).
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: "share-session's preview is four short sections, then one line that says what to type: y, n, or folder numbers to leave out"
author: Anirudhkumar-nanonets
date: 2026-11-17
branch: fix/share-ask-offers-leave-out
cost: { minutes: 42, tokens: 740869 }
id: l-9cb501d1
scope: repo
status: active
replaces: l-69e4953a
src: agent
touches:
- src/cloud/share-bundle.ts
- src/cli.ts
- test/share-bundle.test.ts
---

## Decided
- The preview stays four headed sections: what's sent, from these folders, removed before sending, after you say yes. Its last line is where the copy is. A flat list of about 15 rows made a teammate miss the question entirely (16 Nov).
- After it comes one line saying what to type and what each answer does, then a bare `→` prompt: "Type y to send it all, n to send nothing, or folder numbers to leave out (like 2 3)." Enter still sends nothing.
- Folder numbers are offered whenever more than one folder is still in. With only "→ Send it? [y/N]", Aarsh (17 Nov) didn't know folders could be kept back, though typing numbers still worked.
- Leaving out can happen more than once: the preview is shown again with what's left, and the line asks about "the rest". The example numbers never name every folder still in, and a folder already left out can't be picked again.

## Tried and ruled out
- "→ Send it? [y/N, or folder numbers to leave out]": two questions in one line. The user (17 Nov) asked for a line that says what to enter instead.
- Dropping the folder option from the question (16 Nov): people couldn't find it.
- "Not sent" as the heading of the removed list: too terse. The heading is "Removed before sending".

## Watch out
- Review copy changes in a real terminal: run `node --import tsx src/bin/trail.ts share-session --once` under `script` with a throwaway HOME (a `~/.trail/cloud.json` pointing at a local stand-in that answers `/api/cli/shared-sessions/allowed` and the POST). Type the answers after the prompt shows: piped input ends first and reads as no.

In the code: `sendAsk` and `parseLeaveOut` in src/cloud/share-bundle.ts; the answer loop in `shareWholeClaude` in src/cli.ts.
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: "Sharing scrubs a session line too deep to walk as plain text, and leaves out a session it can't scrub instead of stopping"
author: Anirudhkumar-nanonets
date: 2026-11-17
branch: fix/share-session-deep-nesting
cost: { minutes: 1, tokens: 1550 }
id: l-96699c8a
scope: repo
status: active
src: agent
touches:
- src/cloud/share-session.ts
- src/cloud/share-bundle.ts
- src/cloud/share-sync.ts
- src/trace/redact.ts
---

## Decided
- A session line nested more than 200 objects or arrays deep is scrubbed as plain text (`redactText`, then `anonymize`), the same way a line that isn't JSON is. Walking it with the recursive `walk`, and the `JSON.stringify` after it, ran out of stack at about 3,000 levels. That threw "Maximum call stack size exceeded" partway through scrubbing and ended the whole share with nothing sent. A teammate hit it on 17 Nov at session 29 of 83.
- A .env read nested that deep is left out (counted in `leftOut`): its values can only be found in parsed tool output, not in the raw text.
- A session the scrub still throws on never stops the run and is never sent unscrubbed. `prepareBundle` leaves it out and lists it in the manifest's `unreadable` and in SUMMARY.md. `runSync` skips it the way it skips a session that's too big, until the session grows.
- The scrub's regexes may only start where a run of their characters starts (a lookbehind): `IN_WORD`'s link-password pattern in redact.ts, and `EMAIL` in share-session.ts. Allowed to start at every letter, they re-read a long word to its end from each one, and a 1 to 2 MB word never finished.

## Tried and ruled out
- `JSON.parse` as the limit: V8 parses a line nested 12,000 deep without trouble. The overflow comes from walking the parsed value and writing it back.
- Making only `walk` iterative: `JSON.stringify` of the cleaned value recurses too, so one depth check before the walk covers both.

## Watch out
- A deep line scrubbed as text stays valid JSON unless `redactText` has to replace the whole line (`[redacted] line (…)`). Anything that reads shared bundles must accept non-JSON lines, as it already must for lines that weren't JSON to begin with.
- A new pattern in the scrub or in `secretReason` needs the same care: test it on a 1 MB run of the characters it matches.

In the code: `nestsDeeper` and `MAX_WALK_DEPTH` in src/cloud/share-session.ts; `unreadable` and `scrub` in src/cloud/share-bundle.ts; `scrub` in src/cloud/share-sync.ts; `IN_WORD` in src/trace/redact.ts. Repro: one `.jsonl` line `{"type":"user","toolUseResult":{"a":{"a":…}}}` nested 3,000 deep, run through `bundleSession`.
114 changes: 113 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,67 @@
# Changelog

## Unreleased
## 0.30.5

- **`trail share-session` says what to type, and lets you leave folders
out.** After the preview, one line says what each answer does: `y` sends
it all, `n` sends nothing, and folder numbers leave those folders out
(like `2 3`). The preview then shows what's left, and you can leave out
more before sending (#847).

## 0.30.4

- **`trail share-session` no longer stops on one unusual session.** A
session holding deeply nested JSON from a tool crashed the scrub with
"Maximum call stack size exceeded", and nothing was sent. A line that deep
is now scrubbed as text. A session the scrub still can't read is left out
and named in the summary, and the rest still go. Two scrub patterns no
longer slow to a halt on a very long word (#844).

## 0.30.3

- **`trail share-session`'s preview is shorter and asks one question.** It
now shows four short sections: what's sent, from which folders, what's
removed before sending, and what happens after you say yes. Then it asks
`→ Send it? [y/N]`, where Enter means no. Typing folder numbers there
still leaves those folders out (#840).

## 0.30.2

- **`trail share-session` keeps sending after a trail upgrade.** The first
Claude Code session after an upgrade rewrites trail's hooks in
`~/.claude/settings.json`, and that rewrite used to take out
share-session's hook with them. It now leaves it in place; only `--stop`
and `--delete` take it out (#838).

## 0.30.1

- **`trail share-session` needs no flag.** It's still for the Trail team
only: Trail's server checks the signed-in email before anything is read.
On a laptop that isn't signed in, it opens the sign-in the way
`trail login` does, then carries on (#836).

## 0.30.0

### Added

- **Trail just for you.** `trail init` asks who trail is for. Enter keeps the
team setup that commits as before. "Just me" keeps trail's files out of git
for that clone and saves every learning in `~/.trail` (#750).
- **Claude Desktop and Codex.** AGENTS.md gets a Learnings part, and hooks
report the host they ran in, so learnings work in both (#733).
- **Stale learnings are flagged.** A learning whose `touches:` names code
that's gone is shown as "may be stale", with what's gone and how to replace
it. No model call (#731).
- **`trail init --claude-memory <file>`** imports a Claude memory export.
It keeps only facts about code, never personal ones or secrets, and offers
them just for you (#732).
- **One learning file per session.** A later `trail note` in the same session
and branch adds to that file; a new branch starts a new one (#748).
- **`trail summary one-line`** turns each sources-diff block into one line
(#729).
- **New languages:** Julia, Bash, GLSL and PowerShell in the breadth tier,
`.svelte` and `.astro` through their script blocks, Elixir calls through
`alias`, and Pi as a host (#379, #354, #358, #550, #444, #351, #776).
- **Structural graph failures can now fail the build command with `--strict`**
instead of printing a successful wiring banner. Partial graph artifacts remain
available, workspace builds report failed children, and `--allow-partial`
Expand All @@ -21,6 +79,20 @@

### Fixed

- **Your terminal title keeps the repo name.** Trail adds its status line
only when you don't already have one, and takes back the line an older
init wrote (#749, #756, #780).
- **Share sync re-sends a session only when it grew**, instead of on every
touched timestamp (#828).
- **More callers found.** TypeScript barrel re-exports, named imports,
interface-typed receivers and JSX components; Go package and interface
calls; Kotlin constructors; Python class receivers; PHP type usages
(#726, #335, #768, #764, #766, #687, #316, #339).
- **Windows:** no more console windows flashing from child processes, and the
post-edit blast radius shows (#683, #769, #755).
- The tokens-saved counter counts the learnings hooks hand over, so it keeps
moving in long sessions (#747). Telemetry events carry the time they were
sent, with the event's own time as `occurred_at` (#728).
- Prevent telemetry helpers from repeatedly starting new copies when a sandbox
blocks writes to the telemetry state. Internal flush commands skip startup
upkeep, and background flushes require a saved timestamp before spawning.
Expand All @@ -37,6 +109,46 @@
multi-clause heads collapse to one target. Measured on a 219-file app against
`mix xref graph`: cross-file call-edge precision 0.38 → 0.93, recall 0.41 → 0.64.

## 0.29.0

### Added

- **A sign-in link to your team's Trail.** At the end of Claude's reply in a
repo with learnings, trail now offers "sign in to Trail" by default. It
used to need `TRAIL_CLOUD=1`. It stays off with `DO_NOT_TRACK`, with
telemetry off, in CI, or with `TRAIL_CLOUD=0` (#730).
- **`trail share-session` can send your whole Claude setup**: the last 30
days of Claude Code sessions, your memory notes and setup, scrubbed on your
laptop and sent only after you say yes. It's off unless
`TRAIL_SHARE_SESSION=1` is set. `--stop` and `--delete <code>` always work,
so anyone who tried it can take everything back (#740).

### Fixed

- **Background builds no longer pile up and hang a laptop.** The build lock
counted as abandoned after 5 minutes even while its build was still
running, so a slow laptop could run two or three builds at once. The lock
now names the process holding it, and background builds run at low CPU
priority (#736).
- **Lower peak memory on big repos.** Rebuilds after an edit run in their own
short-lived process instead of the MCP server, queries no longer copy the
whole search index, and map files are written as plain ASCII. On a repo
with 88k symbols, one turn peaked at 2.9 GB instead of 4.3 GB (#737).
- **Install and upgrade without sudo.** `trail upgrade` clears what a stopped
npm install leaves behind (ENOTEMPTY, EEXIST) and tries again, and on
EACCES it shows how to install into your home folder instead. On a Node
older than 20.16 or 22.3, `trail` stops with one plain line (#734).
- **Installing compiles nothing.** The depth tier (TypeScript, Python, Go,
Java, Kotlin, Swift, PHP, R) now parses on WASM, so a laptop without a C
toolchain installs cleanly. The map is the same (#707).
- `trail init`'s list of always-follow learnings says what each one makes
Claude do, and who gets it is said once as a heading (#724).

## 0.28.1

- Lists Trail Code's MCP server in MCP directories (`mcpName`, `server.json`,
`.mcp.json`). The code is the same as 0.28.0.

## 0.28.0

### Added
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 6 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
{
"name": "@nanonets/graft",
"version": "0.28.0",
"version": "0.30.5",
"description": "Build a repo's context graph as a folder of linked markdown files: a local, regenerable cache that every query keeps in sync with your code.",
"keywords": [
"mcp",
"mcp-server",
"model-context-protocol",
"claude-code",
"cursor",
"ai",
"agents",
"knowledge-graph",
Expand Down
3 changes: 3 additions & 0 deletions scripts/pack-trail.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,9 @@ const trail = {
name: '@trailhq/trail-code',
description:
"Your team's shared memory for coding agents: a code map on your machine, and the learnings, decisions and skills your whole team shares. Formerly graft.",
// The official MCP Registry accepts server.json only when the npm package it
// names carries this, and it belongs to @trailhq/trail-code alone.
mcpName: 'io.github.trailhq/trail-code',
keywords: [...new Set(['trail', ...(pkg.keywords ?? [])])],
bin: { trail: 'dist/bin/trail.js' },
// Built already; nothing to compile in the published tree.
Expand Down
29 changes: 29 additions & 0 deletions server.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "io.github.trailhq/trail-code",
"title": "Trail Code",
"description": "A local code map for coding agents: find code, trace callers, read a file's API, map a repo.",
"websiteUrl": "https://trailhq.com/trail-code",
"repository": {
"url": "https://github.com/trailhq/Trail-Code",
"source": "github",
"id": "1288325627"
},
"version": "0.30.5",
"packages": [
{
"registryType": "npm",
"identifier": "@trailhq/trail-code",
"version": "0.30.5",
"transport": {
"type": "stdio"
},
"packageArguments": [
{
"type": "positional",
"value": "mcp"
}
]
}
]
}
Loading
Loading