Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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`).
89 changes: 88 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,42 @@
# Changelog

## Unreleased
## 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 +54,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 +84,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.2",
"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.2",
"packages": [
{
"registryType": "npm",
"identifier": "@trailhq/trail-code",
"version": "0.30.2",
"transport": {
"type": "stdio"
},
"packageArguments": [
{
"type": "positional",
"value": "mcp"
}
]
}
]
}
Loading