Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): Keep Claude banner off plain terminals (PRD-8004) (#3471)

serafin-garcia165b24155705
diff --git a/.changeset/terminal-no-claude-banner.md b/.changeset/terminal-no-claude-banner.md
new file mode 100644
index 000000000..fc5b25d0d
--- /dev/null
+++ b/.changeset/terminal-no-claude-banner.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Opening a plain terminal no longer shows the "Claude Code (claude) isn't installed" banner. The docked terminal probed Claude readiness on every session, so a bare tab opened with Cmd+J, the Terminal menu's "New Terminal", or the dock's + nagged about claude (or about connecting OpenKnowledge tools) even though the user never picked a CLI. Readiness feedback is now scoped to launches that actually target the Claude CLI: those still surface the install and connect-tools banners, while plain tabs, "run this command" tabs, and reload-adopted tabs stay banner-free.
diff --git a/packages/app/src/components/ClaudeReadinessBanner.tsx b/packages/app/src/components/ClaudeReadinessBanner.tsx
index 42491cc62..d8df07b7e 100644
--- a/packages/app/src/components/ClaudeReadinessBanner.tsx
+++ b/packages/app/src/components/ClaudeReadinessBanner.tsx
@@ -1,11 +1,16 @@
/**
- * Actionable readiness banner for the docked terminal. After the PTY is
- * running, the panel probes Claude Code readiness and renders this strip when
- * something blocks the `type claude and it works` flow:
+ * Actionable readiness banner for the docked terminal. Shown only for sessions
+ * whose launch actually targets the Claude CLI: the launch-time preflight
+ * (`resolveLaunchCommand`) produces the verdict, and this strip renders when
+ * something blocks that launch:
* - `claude` not on PATH → a help affordance (open the Claude Code docs).
* - `claude` present but the `open-knowledge` MCP server missing from
* `~/.claude.json` → a re-wire affordance (re-arms MCP consent).
*
+ * A launch-less session (bare tab, "run this command" tab, adopted reload
+ * survivor) never probes and never shows this strip — a plain terminal open
+ * must not nag about claude.
+ *
* Renders nothing when claude is present + wired, or when the probe verdict is
* `unknown` (a flaky probe must never surface a false "not installed"). The
* strip is `role="status"` so screen readers announce it when it appears, and
diff --git a/packages/app/src/components/TerminalPanel.dom.test.tsx b/packages/app/src/components/TerminalPanel.dom.test.tsx
index 972764612..784362e03 100644
--- a/packages/app/src/components/TerminalPanel.dom.test.tsx
+++ b/packages/app/src/components/TerminalPanel.dom.test.tsx
@@ -1071,12 +1071,16 @@ describe('TerminalPanel', () => {
expect(terminal.onData).not.toHaveBeenCalled();
});
- test('probes Claude readiness once the shell is live and shows a help affordance when claude is not on PATH', async () => {
+ // The readiness banner is launch-scoped: only a session whose launch targets
+ // claude carries a verdict (resolveLaunchCommand's preflight). These tests
+ // arrange it via a promptless claude launch; launch-less sessions are pinned
+ // banner-free further down.
+ test('a claude launch probes readiness and shows a help affordance when claude is not on PATH', async () => {
const { bridge, terminal, openExternal } = makeBridge(
{ ok: true, ptyId: 'pty-1' },
{ claude: 'not-found', mcp: 'needs-rewire' },
);
- render(<TerminalPanel bridge={bridge} />);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);
await waitFor(() => expect(terminal.claudePreflight).toHaveBeenCalledTimes(1));
expect(await screen.findByText(/isn't installed or on your PATH/)).toBeTruthy();
@@ -1087,12 +1091,12 @@ describe('TerminalPanel', () => {
expect(openExternal.mock.calls[0]?.[0]).toContain('claude-code');
});
- test('shows a re-wire affordance when claude is present but OK tools are not wired', async () => {
+ test('a claude launch shows a re-wire affordance when claude is present but OK tools are not wired', async () => {
const { bridge, rewireClaudeMcp } = makeBridge(
{ ok: true, ptyId: 'pty-1' },
{ claude: 'present', mcp: 'needs-rewire' },
);
- render(<TerminalPanel bridge={bridge} />);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);
expect(await screen.findByText(/aren't connected to it yet/)).toBeTruthy();
fireEvent.click(screen.getByRole('button', { name: 'Connect tools' }));
@@ -1101,9 +1105,9 @@ describe('TerminalPanel', () => {
await waitFor(() => expect(screen.queryByRole('status')).toBeNull());
});
- test('shows no readiness banner when claude is present and OK tools are wired', async () => {
+ test('a claude launch shows no readiness banner when claude is present and OK tools are wired', async () => {
const { bridge, terminal } = makeBridge({ ok: true, ptyId: 'pty-1' }, WIRED);
- render(<TerminalPanel bridge={bridge} />);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);
await waitFor(() => expect(terminal.claudePreflight).toHaveBeenCalledTimes(1));
await act(async () => {
@@ -1117,7 +1121,7 @@ describe('TerminalPanel', () => {
{ ok: true, ptyId: 'pty-1' },
{ claude: 'not-found', mcp: 'needs-rewire' },
);
- render(<TerminalPanel bridge={bridge} />);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);
await screen.findByText(/isn't installed or on your PATH/);
fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));
@@ -1204,7 +1208,7 @@ describe('TerminalPanel', () => {
{ ok: true, ptyId: 'pty-1' },
{ claude: 'not-found', mcp: 'needs-rewire' },
);
- render(<TerminalPanel bridge={bridge} />);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: null, cli: 'claude', nonce: 1 }} />);
// The readiness nudge appears while the shell is live...
await screen.findByText(/isn't installed or on your PATH/);
@@ -1216,6 +1220,120 @@ describe('TerminalPanel', () => {
expect(screen.getByRole('alert')).toBeTruthy();
});
+ // A plain tab is precisely the session that did NOT choose claude (the dock
+ // only launches a TUI on an explicit pick), so claude-readiness feedback on
+ // it reads as an unprompted nag. The readiness verdict belongs to launches
+ // that actually target claude (TerminalPanel.launch.dom.test.tsx covers
+ // those); a launch-less session must stay banner-free.
+ test('a plain tab (no launch intent) shows no claude-readiness banner even when claude is not on PATH', async () => {
+ const { bridge } = makeBridge(
+ { ok: true, ptyId: 'pty-1' },
+ { claude: 'not-found', mcp: 'needs-rewire' },
+ );
+ render(<TerminalPanel bridge={bridge} />);
+
+ await waitFor(() =>
+ expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
+ );
+ // Flush any pending readiness probe so a late-arriving banner cannot slip
+ // past the absence assertion below.
+ await act(async () => {
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+ expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
+ expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull();
+ });
+
+ test('a plain tab (no launch intent) shows no MCP-rewire nudge either', async () => {
+ const { bridge } = makeBridge(
+ { ok: true, ptyId: 'pty-1' },
+ { claude: 'present', mcp: 'needs-rewire' },
+ );
+ render(<TerminalPanel bridge={bridge} />);
+
+ await waitFor(() =>
+ expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
+ );
+ await act(async () => {
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+ expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
+ expect(screen.queryByText(/aren't connected to it yet/)).toBeNull();
+ });
+
+ test('a "run this command" tab shows no claude-readiness banner (no CLI is involved)', async () => {
+ const { bridge } = makeBridge(
+ { ok: true, ptyId: 'pty-1' },
+ { claude: 'not-found', mcp: 'needs-rewire' },
+ );
+ render(<TerminalPanel bridge={bridge} commandId="install-slidev" />);
+
+ await waitFor(() =>
+ expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
+ );
+ await act(async () => {
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+ expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
+ expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull();
+ });
+
+ test('an adopted tab (reload survivor) shows no claude-readiness banner', async () => {
+ // An adopted session cannot know whether it was a claude launch or a bare
+ // shell, so under the intent-scoped contract it gets no nudge either.
+ const { bridge } = makeBridge(
+ { ok: true, ptyId: 'pty-ignored' },
+ { claude: 'not-found', mcp: 'needs-rewire' },
+ );
+ render(<TerminalPanel bridge={bridge} adoptPtyId="surv-1" />);
+
+ await waitFor(() =>
+ expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
+ );
+ await act(async () => {
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+ expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
+ expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull();
+ });
+
+ test('an adopted tab that still carries a stale claude launch intent shows no readiness banner', async () => {
+ // The compound reload-survivor case: a claude-launch tab that survived a
+ // reload keeps its (now stale) launch intent, but adoption reconnects the
+ // already-running claude session, so resolveLaunchCommand never runs (the
+ // adoptPtyId guard) and attachSession must not probe. A probe re-added to
+ // attachSession gated only on `launch !== null` would re-nag this
+ // reconnected session — the launch-less adopted test above wouldn't catch
+ // it (launch is null there), and the launch suite's adopted test uses a
+ // WIRED preflight that hides the banner either way. This is the one axis
+ // where those two pins intersect.
+ const { bridge } = makeBridge(
+ { ok: true, ptyId: 'pty-ignored' },
+ { claude: 'not-found', mcp: 'needs-rewire' },
+ );
+ render(
+ <TerminalPanel
+ bridge={bridge}
+ adoptPtyId="surv-1"
+ launch={{ prompt: null, cli: 'claude', nonce: 1 }}
+ />,
+ );
+
+ await waitFor(() =>
+ expect(document.querySelector('[data-terminal-status="running"]')).toBeTruthy(),
+ );
+ await act(async () => {
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+ expect(screen.queryByTestId('terminal-readiness-banner')).toBeNull();
+ expect(screen.queryByText(/isn't installed or on your PATH/)).toBeNull();
+ });
+
test('constructs xterm with the palette for the resolved app theme', async () => {
mockResolvedTheme = 'light';
const { bridge } = makeBridge({ ok: true, ptyId: 'pty-1' });
diff --git a/packages/app/src/components/TerminalPanel.launch.dom.test.tsx b/packages/app/src/components/TerminalPanel.launch.dom.test.tsx
index 750f5915e..33dbc10a7 100644
--- a/packages/app/src/components/TerminalPanel.launch.dom.test.tsx
+++ b/packages/app/src/components/TerminalPanel.launch.dom.test.tsx
@@ -562,8 +562,7 @@ describe('TerminalPanel "Open in terminal" launch (baked into the PTY spawn)', (
await waitFor(() => expect(terminal.adopt).toHaveBeenCalledTimes(1));
await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));
// Fell through to a plain shell — no baked launch command, and nothing typed
- // into the shell. (The post-attach readiness probe still runs here, since this
- // is now just a plain tab — resolveLaunchCommand never owned readiness.)
+ // into the shell (a failed adopt must not silently replay the launch).
expect(bakedLaunch(terminal.create)).toBeUndefined();
expect(launchInputWrites(terminal.input)).toEqual([]);
});
diff --git a/packages/app/src/components/TerminalPanel.tsx b/packages/app/src/components/TerminalPanel.tsx
index e191e830b..34bca7e4d 100644
--- a/packages/app/src/components/TerminalPanel.tsx
+++ b/packages/app/src/components/TerminalPanel.tsx
@@ -602,9 +602,9 @@ function TerminalSession({
});
// Wire a now-live ptyId (freshly created OR adopted from a survivor) into
- // this session: route xterm I/O, exit, and resize through it, focus it, and
- // probe Claude readiness. The wiring is identical for both acquisition paths
- // — only how the id is obtained differs — so both branches below call this.
+ // this session: route xterm I/O, exit, and resize through it, and focus it.
+ // The wiring is identical for both acquisition paths — only how the id is
+ // obtained differs — so both branches below call this.
// A const arrow (not a hoisted `function`) so it observes the non-null
// `container` narrowed by the early return above.
const attachSession = (livePtyId: string) => {
@@ -658,28 +658,10 @@ function TerminalSession({
term.focus();
- // Surface Claude Code readiness once the shell is live. Best-effort UX —
- // a probe failure must never break the terminal, so swallow and show
- // nothing. Log first so a non-teardown failure isn't invisible.
- //
- // SKIP for a freshly-launched tab: `resolveLaunchCommand` already ran a
- // launch-time `claudePreflight` and owns the readiness verdict for that
- // session. Re-probing here would be a redundant IPC round-trip AND could
- // downgrade a launch-time `not-found` (banner shown) to a flaky `unknown`
- // (banner hides), making the missing-CLI banner flash then vanish with no
- // agent launched. Adopted sessions (adoptPtyId set) never call
- // `resolveLaunchCommand`, so they still need the probe.
- const launchOwnsReadiness = launch !== null && adoptPtyId === null;
- if (!launchOwnsReadiness) {
- bridge.terminal
- .claudePreflight()
- .then((readinessResult) => {
- if (!cancelled) setReadiness(readinessResult);
- })
- .catch((err) => {
- console.warn('[terminal] claude readiness preflight failed', err);
- });
- }
+ // No readiness probe here: attachSession runs for every session, including
+ // plain and adopted tabs. Readiness feedback is scoped to a fresh,
+ // product-initiated Claude launch, so only `resolveLaunchCommand` produces
+ // the verdict while resolving that launch.
};
// "Open in <Agent>" launch: resolve the command we BAKE into the shell spawn
@@ -692,9 +674,9 @@ function TerminalSession({
// The bake is gated on a CLI confirmed present on PATH — exactly today's
// guarantee that the terminal never shows a raw `command not found`. A not-
// present / unknown / IPC-failure verdict returns undefined (spawn a plain
- // shell) and surfaces a banner: this function OWNS the claude readiness
- // verdict for a launch session (setting it on every path so the post-attach
- // probe is skipped — see attachSession), and sets the missing-CLI banner for
+ // shell) and surfaces a banner: this function is the ONLY producer of the
+ // claude readiness verdict (launch-less sessions carry no claude intent and
+ // never probe — see attachSession), and sets the missing-CLI banner for
// codex/cursor/opencode. The claude probe here doubles as the launch-time MCP
// pre-approval check — as fresh as the on-disk `.mcp.json` gets, since it runs
// immediately before the spawn.
@@ -705,9 +687,9 @@ function TerminalSession({
try {
const fresh = await bridge.terminal.claudePreflight();
if (fresh.claude === 'present') {
- // Own the readiness verdict for this launch session (the post-attach
- // probe is skipped for launches): surfaces the rewire banner when OK
- // tools need rewiring, and stays silent when fully wired.
+ // Own the readiness verdict for this launch session: surfaces the
+ // rewire banner when OK tools need rewiring, and stays silent when
+ // fully wired.
if (!cancelled) setReadiness(fresh);
return buildCliLaunchArgString('claude', intent.prompt, {
mcpPreApprove: fresh.mcpPreApprovable === true,
diff --git a/packages/desktop/tests/smoke/terminal-dock.e2e.ts b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
index d938d638c..b3076af3b 100644
--- a/packages/desktop/tests/smoke/terminal-dock.e2e.ts
+++ b/packages/desktop/tests/smoke/terminal-dock.e2e.ts
@@ -869,8 +869,11 @@ test.describe('Docked terminal — live Electron', () => {
await expect.poll(() => readTerminalText(page), { timeout: 10_000 }).toContain('RESTARTED_OK');
});
- // Claude not on PATH surfaces the actionable not-found banner.
- test('QA-017 claude-not-found shows Get-Claude-Code banner', async ({ captureStderrFor }) => {
+ // A plain terminal never asks about Claude. An explicit Claude launch still
+ // surfaces the actionable not-found banner when the CLI is absent.
+ test('QA-017 plain terminal stays quiet; missing Claude launch shows Get-Claude-Code banner', async ({
+ captureStderrFor,
+ }) => {
// No fake claude, restricted PATH pinned past path_helper → probe resolves
// not-found even when the host machine has a real claude cask.
const s = seed('claude-missing', { consent: true, pinRestrictedPath: true });
@@ -881,6 +884,19 @@ test.describe('Docked terminal — live Electron', () => {
await openTerminal(app, page);
await waitForStatus(page, 'running', 25_000);
+ await expect(readinessBanner(page)).toHaveCount(0);
+
+ // Drive the same window-scoped launch request emitted by the product's
+ // Claude launchers. This creates a fresh Claude-targeting terminal tab and
+ // crosses renderer → preload → main before the banner verdict renders.
+ await page.evaluate(() => {
+ window.dispatchEvent(
+ new CustomEvent('open-knowledge:terminal-launch', {
+ detail: { prompt: '', cli: 'claude', stage: false },
+ }),
+ );
+ });
+
const banner = readinessBanner(page);
await expect(banner).toBeVisible({ timeout: 15_000 });
// Apostrophe-free substring — the rendered copy uses a straight quote that an
@@ -906,6 +922,16 @@ test.describe('Docked terminal — live Electron', () => {
await openTerminal(app, page);
await waitForStatus(page, 'running', 25_000);
+ await expect(readinessBanner(page)).toHaveCount(0);
+
+ await page.evaluate(() => {
+ window.dispatchEvent(
+ new CustomEvent('open-knowledge:terminal-launch', {
+ detail: { prompt: '', cli: 'claude', stage: false },
+ }),
+ );
+ });
+
const banner = readinessBanner(page);
await expect(banner).toBeVisible({ timeout: 15_000 });
// Apostrophe-free substring (same rationale as the not-found banner) — distinctive