Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsxindex 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, anddiff --git a/packages/app/src/components/TerminalPanel.dom.test.tsx b/packages/app/src/components/TerminalPanel.dom.test.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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