Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(init): never clobber a user-defined statusline (#191) (#199)

Frankie-Xua86fa6d64271
diff --git a/.env.example b/.env.example
index 6c8a966a..76a3c31a 100644
--- a/.env.example
+++ b/.env.example
@@ -55,6 +55,12 @@
# GRAFT_NO_GITIGNORE=1 — skip writing graft/ into .gitignore (e.g. you already ignore it globally)
# GRAFT_NO_IGNORE=1 — skip writing .ignore (ripgrep re-admit); only if you manage search yourself
+# --- Init (Claude Code) -------------------------------------------------------
+# Skip writing statusLine / subagentStatusLine during `graft init` (same as
+# `--no-statusline`). Use this when you already have a custom Claude Code
+# statusline — a project-level field would hide one in ~/.claude/settings.json.
+# GRAFT_NO_STATUSLINE=1
+
# --- Benchmark (bench/) -------------------------------------------------------
# Per-role model overrides for the benchmark harness.
# BENCH_AGENT_MODEL=anthropic/claude-sonnet-5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a004ade..51dba43d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,17 @@
# Changelog
+## Unreleased
+
+### Added
+
+- **`graft init --no-statusline`** (and `GRAFT_NO_STATUSLINE=1`) skips writing
+ Claude Code's `statusLine` / `subagentStatusLine`. A custom bar — in the
+ project's `.claude/settings.json` or in `~/.claude/settings.json` — stays in
+ front: a project-level field would otherwise hide the user-level one. The
+ choice is recorded in the wiring stamp, so a later session refresh cannot
+ put Graft's bar back. Graft still recognises its own helper
+ (`graft-statusline.cjs`) and will update that command on re-init.
+
## 0.15.0
### Added
diff --git a/README.md b/README.md
index f1a28f40..028a3013 100644
--- a/README.md
+++ b/README.md
@@ -271,6 +271,7 @@ With no TTY to prompt on — CI, a Dockerfile, a piped shell — `init` writes *
| `--list-agents` | print the known agent ids and exit |
| `--no-mcp` | skip MCP server registration |
| `--no-hooks` | skip hook installation |
+| `--no-statusline` | skip writing Claude Code `statusLine` (same as `GRAFT_NO_STATUSLINE=1`) |
| `--no-global` | skip writes outside this repo (the `~/.codex/` entries below) |
#### Writes outside the repo
@@ -324,7 +325,7 @@ Where a CLI agent supports user-level `hooks.json`, `init` also installs Graft's
<br/><sub>edit a file → blast radius appears inline → graph auto-resyncs → confirmed in <code>graft viz</code></sub>
</p>
-`graft init` is idempotent and never clobbers your existing `.claude/settings.json` — it merges its blocks and leaves the rest alone. Want the LLM summaries too? Run `graft build --deep` (with a key) whenever you like; auto-sync will never do it for you.
+`graft init` is idempotent and never clobbers your existing `.claude/settings.json` — it merges its blocks and leaves the rest alone. A `statusLine` that is not Graft's (anything whose command does not name `graft-statusline.cjs`) is left untouched; re-running `init` will refresh Graft's own helper command if it is already installed. Pass `--no-statusline` (or `GRAFT_NO_STATUSLINE=1`) to skip installing one at all — a project-level `statusLine` would otherwise hide a custom one in `~/.claude/settings.json`. Want the LLM summaries too? Run `graft build --deep` (with a key) whenever you like; auto-sync will never do it for you.
---
@@ -382,6 +383,7 @@ graft init --dry-run # list every file it would touch, then exit
graft init --agents cursor kiro # wire only these agents, no prompt (ids: agents, cursor, gemini, grok, copilot, kiro, windsurf, adal, claude)
graft init --yes # no prompt; wire every detected agent
graft init --no-global # skip writes outside this repo (~/.codex/ config + hooks)
+graft init --no-statusline # skip Claude Code statusLine (same as GRAFT_NO_STATUSLINE=1)
graft init --no-build # wire the files only; don't build the graph
graft init --all-agents # wire every known agent, detected or not
graft init --list-agents # list known agent ids and exit
diff --git a/src/claude/init.ts b/src/claude/init.ts
index 258c8fae..ca563e93 100644
--- a/src/claude/init.ts
+++ b/src/claude/init.ts
@@ -56,7 +56,7 @@ export interface InitResult {
built: boolean;
}
-export function runInit(dir: string, opts: { build?: boolean; cliPath?: string } = {}): InitResult {
+export function runInit(dir: string, opts: { build?: boolean; cliPath?: string; statusline?: boolean } = {}): InitResult {
// Same list `--dry-run` and the picker report, so the two can't drift apart.
const [settings, statusline, hooks, skill, mcpTarget] = claudeTargets(dir).map((t) => t.path);
@@ -65,7 +65,7 @@ export function runInit(dir: string, opts: { build?: boolean; cliPath?: string }
const settingsPath = settings;
let existing: Record<string, any> = {};
try { existing = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch { /* none/invalid → start fresh */ }
- const { merged, warnings } = mergeGraftSettings(existing);
+ const { merged, warnings } = mergeGraftSettings(existing, { statusline: opts.statusline });
writeFileSync(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
const sl = statusline;
diff --git a/src/claude/settings-merge.ts b/src/claude/settings-merge.ts
index 36685a8a..9b886eeb 100644
--- a/src/claude/settings-merge.ts
+++ b/src/claude/settings-merge.ts
@@ -1,6 +1,9 @@
type Json = Record<string, any>;
const SL_CMD = 'node "${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/graft-statusline.cjs"';
+/** Stable marker for "this statusLine is Graft's", not the full command string —
+ * an older shim path or a GRAFT_DIR wrapper still names this file. */
+const GRAFT_STATUSLINE_HELPER = 'graft-statusline.cjs';
const FOOTER = 'graft/[\\w./-]+\\.md';
// Every form graft is actually invoked as. 'graft:*' covers a global install;
// the other two cover a repo working on graft itself (or any consumer running it
@@ -60,17 +63,59 @@ export function isGraftFooterRegex(re: unknown): boolean {
return String(re).includes('graft/');
}
-export function mergeGraftSettings(existing: Json): { merged: Json; warnings: string[] } {
+function envNoStatusline(): boolean {
+ const v = process.env.GRAFT_NO_STATUSLINE;
+ return v !== undefined && v !== '' && v !== '0' && v !== 'false';
+}
+
+/** True when init should write (or refresh) Graft's Claude Code statusLine. */
+export function statuslineWanted(opts: { statusline?: boolean } = {}): boolean {
+ return opts.statusline !== false && !envNoStatusline();
+}
+
+function isGraftStatusline(value: unknown): boolean {
+ if (!value || typeof value !== 'object') return false;
+ const command = (value as Json).command;
+ return typeof command === 'string' && command.includes(GRAFT_STATUSLINE_HELPER);
+}
+
+function applyStatusline(
+ merged: Json,
+ key: 'statusLine' | 'subagentStatusLine',
+ warnings: string[],
+ wanted: boolean,
+ foreignWarning: string,
+): void {
+ const current = merged[key];
+ const ours = isGraftStatusline(current);
+ if (!wanted) {
+ if (!current || ours) delete merged[key];
+ else warnings.push(foreignWarning);
+ return;
+ }
+ if (!current || ours) {
+ merged[key] = { type: 'command', command: SL_CMD };
+ return;
+ }
+ warnings.push(foreignWarning);
+}
+
+export function mergeGraftSettings(
+ existing: Json,
+ opts: { statusline?: boolean } = {},
+): { merged: Json; warnings: string[] } {
const merged: Json = { ...(existing ?? {}) };
const warnings: string[] = [];
+ const wanted = statuslineWanted(opts);
- if (!merged.statusLine) merged.statusLine = { type: 'command', command: SL_CMD };
- else if (merged.statusLine.command !== SL_CMD)
- warnings.push('Existing statusLine left untouched (a session allows only one). To use Graft, point it at .claude/helpers/graft-statusline.cjs.');
-
- if (!merged.subagentStatusLine) merged.subagentStatusLine = { type: 'command', command: SL_CMD };
- else if (merged.subagentStatusLine.command !== SL_CMD)
- warnings.push('Existing subagentStatusLine left untouched.');
+ applyStatusline(
+ merged, 'statusLine', warnings, wanted,
+ 'Existing statusLine left untouched (a session allows only one). To use Graft, point it at .claude/helpers/graft-statusline.cjs.',
+ );
+ applyStatusline(
+ merged, 'subagentStatusLine', warnings, wanted,
+ 'Existing subagentStatusLine left untouched.',
+ );
merged.hooks = { ...(merged.hooks ?? {}) };
for (const [event, blocks] of Object.entries(graftBlocks())) {
diff --git a/src/cli.ts b/src/cli.ts
index 969100a3..da6c6332 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -14,6 +14,7 @@ import type { ProviderKind } from "./ai/llm/factory.js";
import { formatCheckReport } from "./context/check.js";
import { formatGraphCheckReport } from "./graph/check.js";
import { buildGraphIfMissing, runInit } from "./claude/init.js";
+import { statuslineWanted } from "./claude/settings-merge.js";
import { runHostsInit } from "./hosts/init.js";
import { hostIds } from "./hosts/registry.js";
import { contextDirFor } from "./context/node-file.js";
@@ -898,10 +899,11 @@ program
.option("--list-agents", "list known agent ids and exit")
.option("--no-mcp", "skip MCP server registration for other agents")
.option("--no-hooks", "skip hook installation for other agents")
+ .option("--no-statusline", "skip writing Claude Code statusLine (keep a user-defined one)")
.option("--dry-run", "print every file init would touch, then exit without writing")
.option("-y, --yes", "skip the picker and wire every detected agent (the pre-0.8 default)")
.option("--no-global", "skip writes outside this repo (the ~/.codex/ config + hooks)")
- .action(async (dir: string, opts: { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean }) => {
+ .action(async (dir: string, opts: { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean }) => {
if (opts.listAgents) {
for (const id of [...hostIds(), "claude"]) console.log(id);
return;
@@ -1023,10 +1025,11 @@ function wireTarget(
cliPath: string;
plan: ReturnType<typeof planInit>;
wantClaude: boolean;
- opts: { build?: boolean; mcp?: boolean; hooks?: boolean; global?: boolean };
+ opts: { build?: boolean; mcp?: boolean; hooks?: boolean; global?: boolean; statusline?: boolean };
},
): void {
const { home, cliPath, plan, wantClaude, opts } = ctx;
+ const wantStatusline = statuslineWanted({ statusline: opts.statusline });
// Converge, don't just add. init writes the selected hosts; without this it
// never touches the rest, so a repo wired by an older version (or by the same
@@ -1040,7 +1043,7 @@ function wireTarget(
for (const r of retracted) console.error(`- removed ${r.path} (${r.what}) — agent not selected`);
if (wantClaude) {
- const res = runInit(repo, { build: opts.build, cliPath });
+ const res = runInit(repo, { build: opts.build, cliPath, statusline: wantStatusline });
console.error(`✓ wrote ${res.settingsPath}`);
for (const s of res.shims) console.error(`✓ wrote ${s}`);
console.error(`✓ wrote ${res.skill}`);
@@ -1051,6 +1054,7 @@ function wireTarget(
else
console.error(`✓ mcp claude: ${res.mcp.path} (${res.mcp.action}) — restart Claude Code to load the graft MCP server`);
console.error(res.built ? "✓ built the graph (graft build)" : "· skipped graph build");
+ if (!wantStatusline) console.error("· skipped Claude Code statusLine (--no-statusline)");
for (const w of res.warnings) console.error(`⚠ ${w}`);
}
@@ -1082,6 +1086,7 @@ function wireTarget(
global: opts.global !== false,
mcp: opts.mcp !== false,
hooks: opts.hooks !== false,
+ statusline: wantStatusline,
});
// Every host's wiring points at graft/, so the graph is built whatever was
diff --git a/src/upkeep-run.ts b/src/upkeep-run.ts
index 66c26c8c..775a8c67 100644
--- a/src/upkeep-run.ts
+++ b/src/upkeep-run.ts
@@ -39,7 +39,7 @@ export interface UpkeepResult {
* `opts.global`/`opts.hooks`, replayed from the stamp.
*/
function rewriteWiring(repo: string, hosts: string[], opts: WiringOpts): void {
- if (hosts.includes('claude')) runInit(repo, { build: false, cliPath: graftCliPath() });
+ if (hosts.includes('claude')) runInit(repo, { build: false, cliPath: graftCliPath(), statusline: opts.statusline });
const others = hosts.filter((h) => h !== 'claude');
if (others.length)
runHostsInit(repo, { agents: others, global: opts.global, mcp: opts.mcp, hooks: opts.hooks });
diff --git a/src/upkeep.ts b/src/upkeep.ts
index 7af0645f..b573b3e4 100644
--- a/src/upkeep.ts
+++ b/src/upkeep.ts
@@ -158,10 +158,11 @@ export function formatUpdateNudge(current: string, latest: string | null | undef
* The subset of `graft init`'s flags a refresh has to replay.
*
* Without these, an auto-refresh would install things the user explicitly
- * declined: someone who ran `graft init --no-global` (or `--no-hooks`) said "keep
- * out of `~/.codex`", and a later session silently writing there would be graft
- * overriding a decision rather than maintaining one. Absent from an older stamp →
- * all true, which is what plain `graft init` does.
+ * declined: someone who ran `graft init --no-global` (or `--no-hooks`, or
+ * `--no-statusline`) said "keep out of `~/.codex`" / "leave my statusline
+ * alone", and a later session silently writing there would be graft overriding a
+ * decision rather than maintaining one. Absent from an older stamp → all true,
+ * which is what plain `graft init` does.
*/
export interface WiringOpts {
/** false → never write outside the repo (`--no-global`). */
@@ -170,9 +171,11 @@ export interface WiringOpts {
mcp: boolean;
/** false → skip hook installation (`--no-hooks`). */
hooks: boolean;
+ /** false → skip Claude Code statusLine (`--no-statusline` / GRAFT_NO_STATUSLINE). */
+ statusline: boolean;
}
-export const DEFAULT_WIRING_OPTS: WiringOpts = { global: true, mcp: true, hooks: true };
+export const DEFAULT_WIRING_OPTS: WiringOpts = { global: true, mcp: true, hooks: true, statusline: true };
/** An older stamp has no `opts`; a plain `graft init` wired everything. */
export function wiringOpts(stamp: WiringStamp | null): WiringOpts {
diff --git a/test/claude-init.test.ts b/test/claude-init.test.ts
index 559f4c28..2babb32b 100644
--- a/test/claude-init.test.ts
+++ b/test/claude-init.test.ts
@@ -10,6 +10,7 @@ import { join } from 'node:path';
import { execFileSync, spawnSync } from 'node:child_process';
import { buildGraphIfMissing, runInit } from '../src/claude/init.js';
import { formatInitEpilogue } from '../src/cli-epilogue.js';
+import { readStamp } from '../src/upkeep.js';
function fresh(): string { return mkdtempSync(join(tmpdir(), 'graft-init-')); }
@@ -57,6 +58,43 @@ test('runInit preserves foreign settings and warns on foreign statusLine', () =>
assert.equal(r.warnings.length, 1);
});
+test('runInit updates a prior Graft statusLine whose command still names the helper', () => {
+ const d = fresh();
+ mkdirSync(join(d, '.claude'), { recursive: true });
+ writeFileSync(join(d, '.claude', 'settings.json'), JSON.stringify({
+ statusLine: { type: 'command', command: 'node .claude/helpers/graft-statusline.cjs' },
+ }));
+ runInit(d, { build: false });
+ const s = JSON.parse(readFileSync(join(d, '.claude', 'settings.json'), 'utf8'));
+ assert.ok(s.statusLine.command.includes('graft-statusline.cjs'));
+ assert.match(s.statusLine.command, /CLAUDE_PROJECT_DIR/);
+});
+
+test('runInit with statusline: false does not write a statusLine', () => {
+ const d = fresh();
+ runInit(d, { build: false, statusline: false });
+ const s = JSON.parse(readFileSync(join(d, '.claude', 'settings.json'), 'utf8'));
+ assert.equal(s.statusLine, undefined);
+ assert.equal(s.subagentStatusLine, undefined);
+ assert.ok(existsSync(join(d, '.claude', 'helpers', 'graft-statusline.cjs')), 'shim still installed');
+ assert.ok(s.hooks.Stop[0].hooks[0].command.includes('graft-hooks.cjs'));
+});
+
+test('CLI: --no-statusline leaves statusLine unset', () => {
+ const d = fresh();
+ const res = spawnSync(
+ process.execPath,
+ ['--import', 'tsx', 'src/cli.ts', 'init', d, '--no-build', '--no-agents', '--no-statusline'],
+ { encoding: 'utf8' },
+ );
+ assert.equal(res.status, 0, res.stderr);
+ assert.match(res.stderr, /skipped Claude Code statusLine/);
+ const s = JSON.parse(readFileSync(join(d, '.claude', 'settings.json'), 'utf8'));
+ assert.equal(s.statusLine, undefined);
+ assert.equal(s.subagentStatusLine, undefined);
+ assert.equal(readStamp(d)?.opts?.statusline, false);
+});
+
test('runInit is idempotent', () => {
const d = fresh();
runInit(d, { build: false });
diff --git a/test/claude-settings-merge.test.ts b/test/claude-settings-merge.test.ts
index fd794fd8..0e5cae4e 100644
--- a/test/claude-settings-merge.test.ts
+++ b/test/claude-settings-merge.test.ts
@@ -29,6 +29,54 @@ test('foreign statusLine is preserved with a warning; Graft not forced in', () =
assert.match(warnings[0], /statusLine/);
});
+test('a prior Graft statusLine (helper path, old command) is updated to the current command', () => {
+ const { merged, warnings } = mergeGraftSettings({
+ statusLine: { type: 'command', command: 'node .claude/helpers/graft-statusline.cjs' },
+ subagentStatusLine: { type: 'command', command: 'node .claude/helpers/graft-statusline.cjs' },
+ });
+ assert.equal(merged.statusLine.command, SL);
+ assert.equal(merged.subagentStatusLine.command, SL);
+ assert.deepEqual(warnings, []);
+});
+
+test('statusline: false does not install a statusLine on empty settings', () => {
+ const { merged } = mergeGraftSettings({}, { statusline: false });
+ assert.equal(merged.statusLine, undefined);
+ assert.equal(merged.subagentStatusLine, undefined);
+ assert.ok(Array.isArray(merged.hooks.Stop), 'hooks still wired');
+});
+
+test('statusline: false strips a prior Graft statusLine so a user-level one can show', () => {
+ const { merged } = mergeGraftSettings({
+ statusLine: { type: 'command', command: SL },
+ subagentStatusLine: { type: 'command', command: SL },
+ }, { statusline: false });
+ assert.equal(merged.statusLine, undefined);
+ assert.equal(merged.subagentStatusLine, undefined);
+});
+
+test('statusline: false still leaves a foreign statusLine alone', () => {
+ const { merged, warnings } = mergeGraftSettings(
+ { statusLine: { type: 'command', command: 'my-bar.sh' } },
+ { statusline: false },
+ );
+ assert.equal(merged.statusLine.command, 'my-bar.sh');
+ assert.match(warnings.join('\n'), /statusLine/);
+});
+
+test('GRAFT_NO_STATUSLINE=1 skips installing a statusLine', () => {
+ const prev = process.env.GRAFT_NO_STATUSLINE;
+ process.env.GRAFT_NO_STATUSLINE = '1';
+ try {
+ const { merged } = mergeGraftSettings({});
+ assert.equal(merged.statusLine, undefined);
+ assert.equal(merged.subagentStatusLine, undefined);
+ } finally {
+ if (prev === undefined) delete process.env.GRAFT_NO_STATUSLINE;
+ else process.env.GRAFT_NO_STATUSLINE = prev;
+ }
+});
+
test('existing foreign hooks are preserved; Graft appended', () => {
const existing = { hooks: { PostToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'mine.sh' }] }] } };
const { merged } = mergeGraftSettings(existing);
diff --git a/test/upkeep.test.ts b/test/upkeep.test.ts
index cf2f5d92..de6b655f 100644
--- a/test/upkeep.test.ts
+++ b/test/upkeep.test.ts
@@ -80,7 +80,7 @@ test('the stamp round-trips under graft/.cache/', () => {
assert.deepEqual(readStamp(repo), {
version: '1.2.3',
hosts: ['claude', 'cursor'], // sorted, so two inits in different picker order match
- opts: { global: true, mcp: true, hooks: true },
+ opts: { global: true, mcp: true, hooks: true, statusline: true },
at: '2026-01-01T00:00:00.000Z',
});
});
@@ -92,7 +92,7 @@ test('wiringOpts defaults an older stamp to what plain `graft init` does', () =>
// A partial record still fills the gaps.
assert.deepEqual(
wiringOpts({ version: '1.0.0', hosts: ['claude'], at: 'x', opts: { global: false } }),
- { global: false, mcp: true, hooks: true },
+ { global: false, mcp: true, hooks: true, statusline: true },
);
});
@@ -105,9 +105,21 @@ test('a refresh replays the flags init was given, including --no-global', () =>
rewrite: (_repo, _hosts, opts) => { seen = opts; },
});
// The user said "keep out of ~/.codex" — a later session must not overrule that.
- assert.deepEqual(seen, { global: false, mcp: true, hooks: false });
+ assert.deepEqual(seen, { global: false, mcp: true, hooks: false, statusline: true });
assert.equal(r?.global, false);
- assert.deepEqual(readStamp(repo)?.opts, { global: false, mcp: true, hooks: false }, 'and it stays recorded');
+ assert.deepEqual(readStamp(repo)?.opts, { global: false, mcp: true, hooks: false, statusline: true }, 'and it stays recorded');
+});
+
+test('a refresh replays --no-statusline so a later session cannot re-install the bar', () => {
+ const repo = tmpRepo('upkeep-statusline');
+ writeStamp(repo, '1.0.0', ['claude'], { statusline: false });
+ let seen: WiringOpts | null = null;
+ reconcileWiring(repo, '2.0.0', {
+ wired: () => ['claude'],
+ rewrite: (_repo, _hosts, opts) => { seen = opts; },
+ });
+ assert.deepEqual(seen, { global: true, mcp: true, hooks: true, statusline: false });
+ assert.deepEqual(readStamp(repo)?.opts, { global: true, mcp: true, hooks: true, statusline: false });
});
test('by default a refresh DOES reach ~/.codex — nothing else ever would', () => {