Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* User-level install for Claude Code: the copy of graft's wiring that lives
* outside every repo.
*
* Why this exists. Everything `graft init` writes for Claude Code lands *in* the
* repo — `.mcp.json` and `.claude/settings.json`. A `.gitignore` is free to ignore
* both, and `git worktree add` checks out tracked files only, so a worktree of such
* a repo starts with graft's shims present and neither of the two files that *point
* at* them. No settings.json means no SessionStart hook; no `.mcp.json` means no
* tool server. graft is absent, silently, in a tree that looks correctly wired.
*
* graft already carries the repair for exactly that — `reconcileWiring` rewrites
* both files — and it is unreachable here: `runUpkeep` is called only from the hook
* and from the MCP server, which are the two things that are missing. Seeding can't
* help either, since it runs on the query path, which needs the server.
*
* So the fix cannot live in the repo. `~/.claude/` is not in anyone's working tree,
* no `.gitignore` reaches it, and Claude Code reads it for every project — worktrees
* included. Codex has been installed this way from the start (see ./codex-hooks.ts,
* whose own note says the entries "fire in every repo opened with Codex, not just
* this one"); Claude Code was the one host graft wired repo-only. This module closes
* that gap, and is a deliberate mirror of that file.
*
* The repo-level writes stay exactly as they were. A project that has its own
* `.mcp.json` and settings keeps using them; this is the floor underneath, not a
* replacement.
*/
import { writeFileSync, mkdirSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { hooksShim } from '../claude/shim-template.js';
import { mergeGraftHooks } from '../claude/settings-merge.js';
import { toPosixPath } from '../util/paths.js';
import { readJsonObject, writeOwned, type ConfigWrite } from './config-write.js';
import { mergeJsonKey, serverEntry } from './mcp-config.js';
import type { PlannedWrite } from './plan.js';
import type { Brand } from '../brand.js';
/** Same `{ id, path, action }` contract every other writer in this layer reports. */
export type GlobalWrite = ConfigWrite;
/** The directory the user-level shim lives in — the base every hook command names. */
export function globalHelpersDir(home: string): string {
return join(home, '.claude', 'helpers');
}
/**
* The files a user-level install would touch — pure, no writes, so `--dry-run` and
* the picker can report them up front. All three are scoped 'global': they apply to
* every project opened with Claude Code, not just this one.
*
* `~/.claude.json` holds the *user* MCP scope — the top-level `mcpServers` map, the
* one `claude mcp add --scope user` writes. Not to be confused with the same file's
* `projects["<abs path>"].mcpServers`, which is `--scope local` and per-directory:
* a worktree is its own project entry there, so a local registration would miss it
* for precisely the same reason the repo file does.
*/
export function claudeGlobalTargets(home: string, brand: Brand = 'graft'): PlannedWrite[] {
const g = (id: string, path: string, kind: PlannedWrite['kind'], what: string): PlannedWrite =>
({ hostId: 'claude', id, path, scope: 'global', kind, what });
const writes = [
g('claude-global-shim', join(globalHelpersDir(home), 'graft-hooks.cjs'), 'hook', 'hooks shim (user level)'),
g('claude-global-hooks', join(home, '.claude', 'settings.json'), 'hook', 'SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / PostToolUseFailure / Stop / SessionEnd'),
g('claude-global-mcp', join(home, '.claude.json'), 'mcp', `mcpServers.${brand}`),
];
// trail registers no server for Claude Code: the hooks and the `trail` command do its work.
return brand === 'trail' ? writes.slice(0, 2) : writes;
}
/** Merge graft's hook blocks into a settings file, preserving everything else. */
function upsertGlobalHooks(id: string, path: string, helpers: string): GlobalWrite {
const loaded = readJsonObject(path);
if (loaded === 'unparseable') return { id, path, action: 'skipped-unparseable' };
const { root: existing, existed } = loaded;
const before = JSON.stringify(existing);
const { merged } = mergeGraftHooks(existing, helpers);
if (JSON.stringify(merged) === before) return { id, path, action: 'unchanged' };
mkdirSync(dirname(path), { recursive: true });
writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`);
return { id, path, action: existed ? 'updated' : 'created' };
}
/**
* Install the user-level copy: the shim, the hook entries that call it, and the
* user-scope MCP registration.
*
* The shim is written to `home` and the hook commands name it by absolute path, for
* the reason the repo form can't be reused: `${CLAUDE_PROJECT_DIR}/.claude/helpers/`
* resolves inside whatever project is open, and the whole point is to work in one
* that has no such file. The shim itself is the same one every host gets, and finds
* the installed package the same way (see claude/shim-template.ts).
*
* Best-effort by contract, like every other writer here: a failure is reported as an
* action, never raised, so a bad `~/.claude.json` can't fail a `graft init`.
*/
export function installClaudeGlobal(home: string, brand: Brand = 'graft'): GlobalWrite[] {
const [shim, settings] = claudeGlobalTargets(home, brand);
const mcp = { id: 'claude-global-mcp', path: join(home, '.claude.json') };
const out: GlobalWrite[] = [];
try {
out.push(writeOwned(shim.id, shim.path, hooksShim(), 0o755));
} catch {
out.push({ id: shim.id, path: shim.path, action: 'skipped-unparseable' });
}
// Only wire the hooks once the shim they call is actually on disk — a hook
// entry pointing at a missing file is an error in every session, which is a
// worse failure than not installing.
if (out[0].action !== 'skipped-unparseable') {
try {
// Posix form in the command string: `join` gives backslashes on Windows and
// the template appends `/graft-hooks.cjs`, so the raw path produces a mixed
// `C:\Users\…\helpers/graft-hooks.cjs`. Node accepts forward slashes on
// Windows, so one separator throughout is both correct and readable.
out.push(upsertGlobalHooks(settings.id, settings.path, toPosixPath(globalHelpersDir(home))));
} catch {
out.push({ id: settings.id, path: settings.path, action: 'skipped-unparseable' });
}
}
// trail: no server, and the `trail` one an older trail registered here goes.
// graft's keeps serving every repo still wired as graft; a trail repo turns
// it off for its own folder (see disableGraftServerIn).
if (brand === 'trail') {
// The workspace-brains server `init --connect` adds stays: it serves no repo tools.
out.push(dropUserServer(mcp.id, mcp.path, 'trail', isBrainsServer));
return out;
}
try {
out.push(mergeJsonKey(mcp.id, mcp.path, 'mcpServers', serverEntry({ brand }), brand));
} catch {
out.push({ id: mcp.id, path: mcp.path, action: 'skipped-unparseable' });
}
return out;
}
/** Remove one user-scope server from `~/.claude.json`, leaving everything else; `keep` spares an entry it accepts. */
function dropUserServer(id: string, path: string, name: string, keep?: (entry: unknown) => boolean): GlobalWrite {
try {
const loaded = readJsonObject(path);
if (loaded === 'unparseable') return { id, path, action: 'skipped-unparseable' };
const servers = loaded.root.mcpServers;
if (!servers || typeof servers !== 'object' || !(name in servers)) return { id, path, action: 'unchanged' };
if (keep?.(servers[name])) return { id, path, action: 'unchanged' };
delete servers[name];
writeFileSync(path, `${JSON.stringify(loaded.root, null, 2)}\n`);
return { id, path, action: 'updated' };
} catch {
return { id, path, action: 'skipped-unparseable' };
}
}
/**
* In a repo wired for trail, Claude Code would list graft's user-level server
* beside the repo's own `trail` one: the same tools twice. Claude Code keeps a
* per-folder switch for that, `projects["<folder>"].disabledMcpServers` in
* `~/.claude.json` (what /mcp sets), so graft goes off for this folder only
* and keeps serving every repo still wired as graft. Nothing to do when graft
* has no user-level server. Best-effort, like every writer here.
*/
export function disableGraftServerIn(home: string, folder: string): GlobalWrite {
const id = 'claude-folder-graft-off';
const path = join(home, '.claude.json');
try {
const loaded = readJsonObject(path);
if (loaded === 'unparseable') return { id, path, action: 'skipped-unparseable' };
const root = loaded.root;
if (!root.mcpServers?.graft) return { id, path, action: 'unchanged' };
const projects = (root.projects ??= {}) as Record<string, { disabledMcpServers?: unknown }>;
const here = (projects[folder] ??= {});
const off = Array.isArray(here.disabledMcpServers) ? (here.disabledMcpServers as string[]) : [];
if (off.includes('graft')) return { id, path, action: 'unchanged' };
here.disabledMcpServers = [...off, 'graft'];
writeFileSync(path, `${JSON.stringify(root, null, 2)}\n`);
return { id, path, action: 'updated' };
} catch {
return { id, path, action: 'skipped-unparseable' };
}
}
/**
* A repo wired for trail commits `.mcp.json` with a `trail mcp` server. On a
* teammate's machine that has graft but not the trail command, that server
* can't start. So this folder gets a server of the same name, in Claude Code's
* per-folder scope (which wins over the project's), that runs `graft mcp`: the
* same program. graft's own user-level server goes off here, so the tools
* aren't listed twice. Once `trail` is installed, the per-folder one goes and
* the committed one runs. Takes effect from the next session in the folder.
*/
export function fitTrailServerToMachine(home: string, folder: string, has: { trail: boolean; graft: boolean }): GlobalWrite {
const id = 'claude-folder-trail-server';
const path = join(home, '.claude.json');
try {
const loaded = readJsonObject(path);
if (loaded === 'unparseable') return { id, path, action: 'skipped-unparseable' };
const root = loaded.root;
const here = root.projects?.[folder] as { mcpServers?: Record<string, { command?: string }>; disabledMcpServers?: unknown } | undefined;
const ours = here?.mcpServers?.trail?.command === 'graft';
if (has.trail) {
if (!ours) return { id, path, action: 'unchanged' };
delete here!.mcpServers!.trail;
} else if (has.graft && !ours) {
const projects = (root.projects ??= {}) as Record<string, typeof here>;
const p = (projects[folder] ??= {})!;
p.mcpServers = { ...(p.mcpServers ?? {}), trail: { command: 'graft', args: ['mcp'] } as { command: string } };
if (root.mcpServers?.graft) {
const off = Array.isArray(p.disabledMcpServers) ? (p.disabledMcpServers as string[]) : [];
if (!off.includes('graft')) p.disabledMcpServers = [...off, 'graft'];
}
} else {
return { id, path, action: 'unchanged' };
}
writeFileSync(path, `${JSON.stringify(root, null, 2)}\n`);
return { id, path, action: 'updated' };
} catch {
return { id, path, action: 'skipped-unparseable' };
}
}
/* -------------------------------------------------------------------------- */
/* the workspace's brains, for Claude Code */
/* -------------------------------------------------------------------------- */
/** The flag that makes `trail mcp` serve only the workspace's brain tools. */
export const BRAINS_FLAG = '--brains';
/** Whether a user-scope `trail` entry is the brains-only server (`trail mcp --brains`). */
export function isBrainsServer(entry: unknown): boolean {
const args = (entry as { args?: unknown } | null)?.args;
return Array.isArray(args) && args.includes(BRAINS_FLAG);
}
/**
* Once this machine is connected to a Trail workspace, Claude Code gets one
* `trail` entry at the user MCP scope (`~/.claude.json`, every project): a
* server that serves only the workspace's brain tools. trail gives Claude
* Code no repo-tools server (its hooks and the `trail` command do that work),
* so this one lists the four brain tools and nothing else. Best-effort.
*/
export function installBrainsServer(home: string): GlobalWrite {
const id = 'claude-global-brains';
const path = join(home, '.claude.json');
try {
const { command, args } = serverEntry({ brand: 'trail' });
return mergeJsonKey(id, path, 'mcpServers', { command, args: [...args, BRAINS_FLAG] }, 'trail');
} catch {
return { id, path, action: 'skipped-unparseable' };
}
}
/** Take the brains server out again (`trail logout`). Leaves any other `trail` entry alone. */
export function removeBrainsServer(home: string): GlobalWrite {
return dropUserServer('claude-global-brains', join(home, '.claude.json'), 'trail', (e) => !isBrainsServer(e));
}