Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): launch Codex and Cursor CLIs from the docked terminal (#2063)

serafin-garcia141bb1318c8c
diff --git a/.changeset/terminal-codex-cursor-cli-launch.md b/.changeset/terminal-codex-cursor-cli-launch.md
new file mode 100644
index 000000000..957a4dc6b
--- /dev/null
+++ b/.changeset/terminal-codex-cursor-cli-launch.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+Launch Codex and Cursor CLIs from the docked terminal, alongside Claude. The "Open with AI" surfaces (header popover, file and empty-space right-click menus, and the empty-state create composer) now offer a Codex (`codex`) and Cursor (`cursor-agent`) row in the Terminal section, each starting an interactive session with the same scope-specific prompt the Claude CLI launch uses. As with Claude, a CLI that isn't on your PATH suppresses the launch and shows an actionable "not installed" banner instead of a broken command.
diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx
index 0694db9bd..106c3ce08 100644
--- a/packages/app/src/App.tsx
+++ b/packages/app/src/App.tsx
@@ -325,8 +325,8 @@ function AppBody() {
const terminalLaunch: TerminalLaunchContextValue | null = desktopBridge
? {
- launchInTerminal: (input) => {
- requestTerminalLaunch(composeTerminalLaunchPrompt(input));
+ launchInTerminal: (input, cli) => {
+ requestTerminalLaunch(composeTerminalLaunchPrompt(input, cli), cli);
},
}
: null;
diff --git a/packages/app/src/components/EditorPane.dom.test.tsx b/packages/app/src/components/EditorPane.dom.test.tsx
index b44d29cbd..eda519575 100644
--- a/packages/app/src/components/EditorPane.dom.test.tsx
+++ b/packages/app/src/components/EditorPane.dom.test.tsx
@@ -301,7 +301,7 @@ describe('EditorPane terminal dock wiring', () => {
const dock = () => screen.getByTestId('terminal-dock');
expect(dock().getAttribute('data-launch-nonce')).toBe('none');
- act(() => requestTerminalLaunch('work on docs/notes'));
+ act(() => requestTerminalLaunch('work on docs/notes', 'claude'));
expect(dock().getAttribute('data-visible')).toBe('true');
expect(dock().getAttribute('data-launch-nonce')).toBe('1');
@@ -322,13 +322,13 @@ describe('EditorPane terminal dock wiring', () => {
const dock = () => screen.getByTestId('terminal-dock');
- act(() => requestTerminalLaunch('first'));
+ act(() => requestTerminalLaunch('first', 'claude'));
expect(dock().getAttribute('data-launch-nonce')).toBe('1');
act(() => desk.dispatchMenuAction('toggle-terminal'));
expect(dock().getAttribute('data-launch-nonce')).toBe('none');
- act(() => requestTerminalLaunch('second'));
+ act(() => requestTerminalLaunch('second', 'codex'));
expect(dock().getAttribute('data-launch-nonce')).toBe('2');
});
diff --git a/packages/app/src/components/EditorPane.tsx b/packages/app/src/components/EditorPane.tsx
index acd592b50..f20a0ea63 100644
--- a/packages/app/src/components/EditorPane.tsx
+++ b/packages/app/src/components/EditorPane.tsx
@@ -1,3 +1,4 @@
+import type { TerminalCli } from '@inkeep/open-knowledge-core';
import { useLingui } from '@lingui/react/macro';
import { useEffect, useRef, useState } from 'react';
import { toast } from 'sonner';
@@ -27,6 +28,7 @@ import {
export interface TerminalLaunchIntent {
readonly prompt: string;
+ readonly cli: TerminalCli;
readonly nonce: number;
}
@@ -107,10 +109,10 @@ export function EditorPane({ onOpenSearch }: EditorPaneProps = {}) {
}, []);
useEffect(() => {
- return subscribeToTerminalLaunchRequests((prompt) => {
+ return subscribeToTerminalLaunchRequests((prompt, cli) => {
setTerminalVisible(true);
launchNonceRef.current += 1;
- setTerminalLaunch({ prompt, nonce: launchNonceRef.current });
+ setTerminalLaunch({ prompt, cli, nonce: launchNonceRef.current });
});
}, []);
diff --git a/packages/app/src/components/TerminalCliMissingBanner.dom.test.tsx b/packages/app/src/components/TerminalCliMissingBanner.dom.test.tsx
new file mode 100644
index 000000000..1417b840c
--- /dev/null
+++ b/packages/app/src/components/TerminalCliMissingBanner.dom.test.tsx
@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { TERMINAL_CLIS } from '@inkeep/open-knowledge-core';
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { ReactNode } from 'react';
+import type { OkDesktopBridge } from '@/lib/desktop-bridge-types';
+
+mock.module('@lingui/react/macro', () => ({
+ Trans: ({ children }: { children: ReactNode }) => <>{children}</>,
+ useLingui: () => ({
+ t: (strings: TemplateStringsArray, ...values: unknown[]) =>
+ strings.reduce((acc, part, index) => `${acc}${part}${values[index] ?? ''}`, ''),
+ }),
+}));
+
+const { TerminalCliMissingBanner } = await import('./TerminalCliMissingBanner');
+
+function makeBridge() {
+ const openExternal = mock(async (_url: string) => {});
+ return {
+ bridge: { shell: { openExternal } } as unknown as OkDesktopBridge,
+ openExternal,
+ };
+}
+
+describe('TerminalCliMissingBanner', () => {
+ afterEach(() => {
+ cleanup();
+ });
+
+ test('"Get Codex" opens the Codex CLI docs URL', async () => {
+ const { bridge, openExternal } = makeBridge();
+ render(<TerminalCliMissingBanner cli="codex" bridge={bridge} onDismiss={() => {}} />);
+
+ expect(screen.getByText(/Codex \(codex\) isn't installed/)).toBeTruthy();
+
+ await userEvent.click(screen.getByRole('button', { name: 'Get Codex' }));
+ expect(openExternal).toHaveBeenCalledTimes(1);
+ expect(openExternal).toHaveBeenCalledWith(TERMINAL_CLIS.codex.docsUrl);
+ });
+
+ test('"Get Cursor" opens the Cursor CLI docs URL (binary is cursor-agent)', async () => {
+ const { bridge, openExternal } = makeBridge();
+ render(<TerminalCliMissingBanner cli="cursor" bridge={bridge} onDismiss={() => {}} />);
+
+ expect(screen.getByText(/Cursor \(cursor-agent\) isn't installed/)).toBeTruthy();
+ await userEvent.click(screen.getByRole('button', { name: 'Get Cursor' }));
+ expect(openExternal).toHaveBeenCalledWith(TERMINAL_CLIS.cursor.docsUrl);
+ });
+
+ test('the dismiss control fires onDismiss without opening docs', async () => {
+ const { bridge, openExternal } = makeBridge();
+ const onDismiss = mock(() => {});
+ render(<TerminalCliMissingBanner cli="codex" bridge={bridge} onDismiss={onDismiss} />);
+
+ await userEvent.click(screen.getByRole('button', { name: 'Dismiss' }));
+ expect(onDismiss).toHaveBeenCalledTimes(1);
+ expect(openExternal).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/app/src/components/TerminalCliMissingBanner.tsx b/packages/app/src/components/TerminalCliMissingBanner.tsx
new file mode 100644
index 000000000..f146a9654
--- /dev/null
+++ b/packages/app/src/components/TerminalCliMissingBanner.tsx
@@ -0,0 +1,48 @@
+import { TERMINAL_CLIS, type TerminalCli } from '@inkeep/open-knowledge-core';
+import { useLingui } from '@lingui/react/macro';
+import { X } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import type { OkDesktopBridge } from '@/lib/desktop-bridge-types';
+
+interface TerminalCliMissingBannerProps {
+ readonly cli: TerminalCli;
+ readonly bridge: OkDesktopBridge;
+ readonly onDismiss: () => void;
+}
+
+export function TerminalCliMissingBanner({
+ cli,
+ bridge,
+ onDismiss,
+}: TerminalCliMissingBannerProps) {
+ const { t } = useLingui();
+ const { bin, displayName, docsUrl } = TERMINAL_CLIS[cli];
+
+ return (
+ <div
+ role="status"
+ className="flex shrink-0 items-center gap-3 border-border border-b bg-muted px-3 py-2 text-foreground text-xs"
+ >
+ <p className="min-w-0 flex-1">
+ {t`${displayName} (${bin}) isn't installed or on your PATH.`}
+ </p>
+ <Button
+ size="sm"
+ variant="secondary"
+ className="shrink-0"
+ onClick={() => void bridge.shell.openExternal(docsUrl)}
+ >
+ {t`Get ${displayName}`}
+ </Button>
+ <Button
+ size="icon"
+ variant="ghost"
+ aria-label={t`Dismiss`}
+ className="size-6 shrink-0"
+ onClick={onDismiss}
+ >
+ <X aria-hidden="true" className="size-4" />
+ </Button>
+ </div>
+ );
+}
diff --git a/packages/app/src/components/TerminalPanel.dom.test.tsx b/packages/app/src/components/TerminalPanel.dom.test.tsx
index 7655b16da..a21706b31 100644
--- a/packages/app/src/components/TerminalPanel.dom.test.tsx
+++ b/packages/app/src/components/TerminalPanel.dom.test.tsx
@@ -101,6 +101,7 @@ function makeBridge(createResult: CreateResult, preflight: ClaudeReadiness = WIR
return unsubExit;
}),
claudePreflight: mock(async () => preflight),
+ cliPreflight: mock(async () => ({ onPath: 'present' as const })),
rewireClaudeMcp,
};
return {
@@ -443,6 +444,7 @@ describe('TerminalPanel', () => {
onData: mock(() => mock(() => {})),
onExit: mock(() => mock(() => {})),
claudePreflight: mock(async () => WIRED),
+ cliPreflight: mock(async () => ({ onPath: 'present' as const })),
rewireClaudeMcp: mock(async () => WIRED),
};
const bridge = {
diff --git a/packages/app/src/components/TerminalPanel.launch.dom.test.tsx b/packages/app/src/components/TerminalPanel.launch.dom.test.tsx
index a361bafb4..59086a9c5 100644
--- a/packages/app/src/components/TerminalPanel.launch.dom.test.tsx
+++ b/packages/app/src/components/TerminalPanel.launch.dom.test.tsx
@@ -1,6 +1,12 @@
import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
-import { act, cleanup, render, waitFor } from '@testing-library/react';
-import type { ClaudeReadiness, OkDesktopBridge, OkPtyData } from '@/lib/desktop-bridge-types';
+import type { TerminalCli } from '@inkeep/open-knowledge-core';
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react';
+import type {
+ ClaudeReadiness,
+ CliReadiness,
+ OkDesktopBridge,
+ OkPtyData,
+} from '@/lib/desktop-bridge-types';
class MockFitAddon {
fit = mock(() => {});
@@ -49,8 +55,9 @@ mock.module('@xterm/addon-unicode11', () => ({ Unicode11Addon: MockUnicode11Addo
mock.module('@xterm/xterm/css/xterm.css', () => ({}));
const WIRED: ClaudeReadiness = { claude: 'present', mcp: 'wired' };
+const ON_PATH: CliReadiness = { onPath: 'present' };
-function makeBridge(preflight: ClaudeReadiness = WIRED) {
+function makeBridge(preflight: ClaudeReadiness = WIRED, cliReadiness: CliReadiness = ON_PATH) {
const dataSubs: Array<(m: OkPtyData) => void> = [];
const terminal = {
create: mock(async () => ({ ok: true as const, ptyId: 'pty-1' })),
@@ -64,6 +71,7 @@ function makeBridge(preflight: ClaudeReadiness = WIRED) {
}),
onExit: mock(() => mock(() => {})),
claudePreflight: mock(async () => preflight),
+ cliPreflight: mock(async (_cli: TerminalCli) => cliReadiness),
rewireClaudeMcp: mock(async () => preflight),
};
return {
@@ -81,11 +89,12 @@ function makeBridge(preflight: ClaudeReadiness = WIRED) {
const { TerminalPanel } = await import('./TerminalPanel');
/** Inputs the user typed are forwarded verbatim; the launch is the only call
- * that goes through `buildClaudeLaunchCommand`. Filter to the launch shape. */
-function launchWrites(inputMock: ReturnType<typeof mock>): string[] {
+ * that goes through `buildCliLaunchCommand`. Filter to the launch shape for a
+ * given binary prefix. */
+function launchWrites(inputMock: ReturnType<typeof mock>, bin = 'claude'): string[] {
return inputMock.mock.calls
.map((c) => c[1] as string)
- .filter((d) => typeof d === 'string' && d.startsWith('claude '));
+ .filter((d) => typeof d === 'string' && d.startsWith(`${bin} `));
}
describe('TerminalPanel "Open in terminal" launch', () => {
@@ -99,7 +108,9 @@ describe('TerminalPanel "Open in terminal" launch', () => {
test("writes `claude '<escaped prompt>'` exactly once on running, after first output", async () => {
const { bridge, terminal, pushData } = makeBridge(WIRED);
const prompt = "Let's work on `foo.md` using Open Knowledge.";
- const { rerender } = render(<TerminalPanel bridge={bridge} launch={{ prompt, nonce: 1 }} />);
+ const { rerender } = render(
+ <TerminalPanel bridge={bridge} launch={{ prompt, cli: 'claude', nonce: 1 }} />,
+ );
await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
@@ -110,7 +121,7 @@ describe('TerminalPanel "Open in terminal" launch', () => {
"claude 'Let'\\''s work on `foo.md` using Open Knowledge.'\r",
);
- rerender(<TerminalPanel bridge={bridge} launch={{ prompt, nonce: 1 }} />);
+ rerender(<TerminalPanel bridge={bridge} launch={{ prompt, cli: 'claude', nonce: 1 }} />);
await act(async () => {
await Promise.resolve();
});
@@ -127,6 +138,7 @@ describe('TerminalPanel "Open in terminal" launch', () => {
onData: mock(() => mock(() => {})),
onExit: mock(() => mock(() => {})),
claudePreflight: mock(async () => WIRED),
+ cliPreflight: mock(async () => ON_PATH),
rewireClaudeMcp: mock(async () => WIRED),
};
const bridge = {
@@ -134,7 +146,7 @@ describe('TerminalPanel "Open in terminal" launch', () => {
shell: { openExternal: mock(async () => {}) },
} as unknown as OkDesktopBridge;
- render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', nonce: 1 }} />);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', cli: 'claude', nonce: 1 }} />);
await waitFor(() => expect(terminal.create).toHaveBeenCalledTimes(1));
await act(async () => {
await Promise.resolve();
@@ -147,7 +159,7 @@ describe('TerminalPanel "Open in terminal" launch', () => {
claude: 'not-found',
mcp: 'needs-rewire',
});
- render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', nonce: 1 }} />);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', cli: 'claude', nonce: 1 }} />);
await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
@@ -164,7 +176,7 @@ describe('TerminalPanel "Open in terminal" launch', () => {
claude: 'present',
mcp: 'needs-rewire',
});
- render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', nonce: 1 }} />);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', cli: 'claude', nonce: 1 }} />);
await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
@@ -177,15 +189,77 @@ describe('TerminalPanel "Open in terminal" launch', () => {
test('a new nonce fires a second launch (repeat "Open in terminal" while running)', async () => {
const { bridge, terminal, pushData } = makeBridge(WIRED);
const { rerender } = render(
- <TerminalPanel bridge={bridge} launch={{ prompt: 'first', nonce: 1 }} />,
+ <TerminalPanel bridge={bridge} launch={{ prompt: 'first', cli: 'claude', nonce: 1 }} />,
);
await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
await waitFor(() => expect(launchWrites(terminal.input).length).toBe(1));
- rerender(<TerminalPanel bridge={bridge} launch={{ prompt: 'second', nonce: 2 }} />);
+ rerender(
+ <TerminalPanel bridge={bridge} launch={{ prompt: 'second', cli: 'claude', nonce: 2 }} />,
+ );
await waitFor(() => expect(launchWrites(terminal.input).length).toBe(2));
expect(launchWrites(terminal.input)[1]).toBe("claude 'second'\r");
});
+
+ test('codex launch probes cliPreflight and writes the codex command', async () => {
+ const { bridge, terminal, pushData } = makeBridge(WIRED, ON_PATH);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', cli: 'codex', nonce: 1 }} />);
+
+ await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
+ act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
+ await waitFor(() => expect(terminal.cliPreflight).toHaveBeenCalledTimes(1));
+ expect(terminal.cliPreflight.mock.calls[0]?.[0]).toBe('codex');
+
+ await waitFor(() => expect(launchWrites(terminal.input, 'codex').length).toBe(1));
+ expect(launchWrites(terminal.input, 'codex')[0]).toBe("codex 'hi'\r");
+ });
+
+ test('cursor launch writes the cursor-agent command (the agent CLI, not the editor)', async () => {
+ const { bridge, terminal, pushData } = makeBridge(WIRED, ON_PATH);
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', cli: 'cursor', nonce: 1 }} />);
+
+ await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
+ act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
+ await waitFor(() => expect(terminal.cliPreflight).toHaveBeenCalledTimes(1));
+
+ await waitFor(() => expect(launchWrites(terminal.input, 'cursor-agent').length).toBe(1));
+ expect(launchWrites(terminal.input, 'cursor-agent')[0]).toBe("cursor-agent 'hi'\r");
+ });
+
+ test('codex not on PATH: suppresses the write and surfaces the missing-CLI banner', async () => {
+ const { bridge, terminal, pushData } = makeBridge(WIRED, { onPath: 'not-found' });
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', cli: 'codex', nonce: 1 }} />);
+
+ await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
+ act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
+ await waitFor(() => expect(terminal.cliPreflight).toHaveBeenCalledTimes(1));
+
+ await screen.findByText(/Codex \(codex\) isn't installed/);
+ expect(launchWrites(terminal.input, 'codex').length).toBe(0);
+ });
+
+ test('cursor probe UNKNOWN does not block the launch (parity with claude unknown)', async () => {
+ const { bridge, terminal, pushData } = makeBridge(WIRED, { onPath: 'unknown' });
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', cli: 'cursor', nonce: 1 }} />);
+
+ await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
+ act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
+ await waitFor(() => expect(launchWrites(terminal.input, 'cursor-agent').length).toBe(1));
+ });
+
+ test('cliPreflight IPC rejection fail-opens: the launch is still written (the .catch path)', async () => {
+ const { bridge, terminal, pushData } = makeBridge(WIRED);
+ terminal.cliPreflight = mock(async () => {
+ throw new Error('ipc channel closed');
+ });
+ render(<TerminalPanel bridge={bridge} launch={{ prompt: 'hi', cli: 'codex', nonce: 1 }} />);
+
+ await waitFor(() => expect(terminal.onData).toHaveBeenCalledTimes(1));
+ act(() => pushData({ ptyId: 'pty-1', data: '$ ' }));
+ await waitFor(() => expect(terminal.cliPreflight).toHaveBeenCalledTimes(1));
+ await waitFor(() => expect(launchWrites(terminal.input, 'codex').length).toBe(1));
+ expect(launchWrites(terminal.input, 'codex')[0]).toBe("codex 'hi'\r");
+ });
});
diff --git a/packages/app/src/components/TerminalPanel.tsx b/packages/app/src/components/TerminalPanel.tsx
index ac8196c03..d98d822ab 100644
--- a/packages/app/src/components/TerminalPanel.tsx
+++ b/packages/app/src/components/TerminalPanel.tsx
@@ -1,6 +1,6 @@
import '@xterm/xterm/css/xterm.css';
-import { buildClaudeLaunchCommand } from '@inkeep/open-knowledge-core';
+import { buildCliLaunchCommand, type TerminalCli } from '@inkeep/open-knowledge-core';
import { useLingui } from '@lingui/react/macro';
import { FitAddon } from '@xterm/addon-fit';
import { Unicode11Addon } from '@xterm/addon-unicode11';
@@ -13,6 +13,7 @@ import type { ClaudeReadiness, OkDesktopBridge } from '@/lib/desktop-bridge-type
import { cn } from '@/lib/utils';
import { ClaudeReadinessBanner } from './ClaudeReadinessBanner';
import type { TerminalLaunchIntent } from './EditorPane';
+import { TerminalCliMissingBanner } from './TerminalCliMissingBanner';
import { type TerminalExitInfo, TerminalExitNotice } from './TerminalExitNotice';
import { TerminalRefusalNotice } from './TerminalRefusalNotice';
import { xtermThemeForMode } from './terminal-theme';
@@ -88,6 +89,7 @@ function TerminalSession({
const ptyIdRef = useRef<string | null>(null);
const [firstOutputSeen, setFirstOutputSeen] = useState(false);
const lastLaunchedNonceRef = useRef<number | null>(null);
+ const [missingCli, setMissingCli] = useState<TerminalCli | null>(null);
useEffect(() => {
onExitRef.current = onExit;
@@ -248,16 +250,45 @@ function TerminalSession({
if (launch === null) return;
if (status !== 'running') return;
if (!firstOutputSeen) return;
- if (!preflightDone) return;
if (lastLaunchedNonceRef.current === launch.nonce) return;
const ptyId = ptyIdRef.current;
if (ptyId === null) return;
- if (readiness?.claude === 'not-found') {
+
+ if (launch.cli === 'claude') {
+ if (!preflightDone) return;
lastLaunchedNonceRef.current = launch.nonce;
+ setMissingCli(null);
+ if (readiness?.claude === 'not-found') return; // banner handles remediation
+ bridge.terminal.input(ptyId, buildCliLaunchCommand('claude', launch.prompt));
return;
}
+
lastLaunchedNonceRef.current = launch.nonce;
- bridge.terminal.input(ptyId, buildClaudeLaunchCommand(launch.prompt));
+ setMissingCli(null);
+ const { cli, prompt } = launch;
+ let cancelled = false;
+ const writeLaunch = () => {
+ const livePtyId = ptyIdRef.current;
+ if (livePtyId !== null) bridge.terminal.input(livePtyId, buildCliLaunchCommand(cli, prompt));
+ };
+ void bridge.terminal
+ .cliPreflight(cli)
+ .then((res) => {
+ if (cancelled) return;
+ if (res.onPath === 'not-found') {
+ setMissingCli(cli);
+ return;
+ }
+ writeLaunch();
+ })
+ .catch((err) => {
+ if (cancelled) return;
+ console.warn('[terminal] cliPreflight failed', { cli, err });
+ writeLaunch();
+ });
+ return () => {
+ cancelled = true;
+ };
}, [bridge, launch, status, firstOutputSeen, preflightDone, readiness]);
return (
@@ -269,6 +300,13 @@ function TerminalSession({
onDismiss={() => setReadiness(null)}
/>
) : null}
+ {status === 'running' && missingCli ? (
+ <TerminalCliMissingBanner
+ cli={missingCli}
+ bridge={bridge}
+ onDismiss={() => setMissingCli(null)}
+ />
+ ) : null}
<div ref={containerRef} data-terminal-status={status} className="min-h-0 flex-1 px-1.5" />
{status === 'exited' && exitInfo ? (
<TerminalExitNotice info={exitInfo} onRestart={onRestart} />
diff --git a/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx b/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx
index 9ce18d285..c9d75a356 100644
--- a/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx
+++ b/packages/app/src/components/empty-state/CreatePromptComposer.dom.test.tsx
@@ -99,7 +99,7 @@ describe('CreatePromptComposer Desktop / Terminal sections', () => {
expect(screen.getByText('Desktop')).toBeTruthy();
expect(screen.getByText('Terminal')).toBeTruthy();
- expect(screen.getByTestId('create-with-claude-cli')).toBeTruthy();
+ expect(screen.getByTestId('create-with-cli-claude')).toBeTruthy();
expect(screen.queryByTestId('menu-separator')).not.toBeNull();
});
@@ -110,7 +110,7 @@ describe('CreatePromptComposer Desktop / Terminal sections', () => {
expect(screen.getByText('Desktop')).toBeTruthy();
expect(screen.queryByText('Terminal')).toBeNull();
- expect(screen.queryByTestId('create-with-claude-cli')).toBeNull();
+ expect(screen.queryByTestId('create-with-cli-claude')).toBeNull();
expect(screen.queryByTestId('menu-separator')).toBeNull();
});
@@ -123,7 +123,7 @@ describe('CreatePromptComposer Desktop / Terminal sections', () => {
target: { value: 'Build a competitor wiki' },
});
- fireEvent.click(screen.getByTestId('create-with-claude-cli'));
+ fireEvent.click(screen.getByTestId('create-with-cli-claude'));
await waitFor(() => {
expect(screen.getByTestId('create-with-agent').textContent).toContain(
'Create with Claude CLI',
@@ -148,7 +148,7 @@ describe('CreatePromptComposer Desktop / Terminal sections', () => {
workspaceValue = null; // buildCreateHandoffInput returns null until the workspace resolves.
await renderComposer({ withTerminal: true });
- fireEvent.click(screen.getByTestId('create-with-claude-cli'));
+ fireEvent.click(screen.getByTestId('create-with-cli-claude'));
await waitFor(() => {
expect(screen.getByTestId('create-with-agent').textContent).toContain(
'Create with Claude CLI',
@@ -176,7 +176,7 @@ describe('CreatePromptComposer Desktop / Terminal sections', () => {
workspaceValue = { contentDir: '/tmp/project', pathSeparator: '/' };
await renderComposer({ withTerminal: true });
- const row = screen.getByTestId('create-with-claude-cli');
+ const row = screen.getByTestId('create-with-cli-claude');
expect(row.textContent).toBe('Claude');
expect(row.getAttribute('aria-label')).toBe('Claude CLI');
});
@@ -188,7 +188,7 @@ describe('CreatePromptComposer Desktop / Terminal sections', () => {
const textarea = screen.getByLabelText('Describe the project you want to create');
fireEvent.change(textarea, { target: { value: 'Build a wiki' } });
- fireEvent.click(screen.getByTestId('create-with-claude-cli')); // enter CLI mode
+ fireEvent.click(screen.getByTestId('create-with-cli-claude')); // enter CLI mode
await waitFor(() => {
expect(screen.getByTestId('create-with-agent').textContent).toContain(
'Create with Claude CLI',
@@ -212,7 +212,7 @@ describe('CreatePromptComposer Desktop / Terminal sections', () => {
workspaceValue = { contentDir: '/tmp/project', pathSeparator: '/' };
await renderComposer({ withTerminal: true });
- fireEvent.click(screen.getByTestId('create-with-claude-cli')); // enter CLI mode
+ fireEvent.click(screen.getByTestId('create-with-cli-claude')); // enter CLI mode
await waitFor(() => {
expect(screen.getByTestId('create-with-agent').textContent).toContain(
'Create with Claude CLI',
diff --git a/packages/app/src/components/empty-state/CreatePromptComposer.tsx b/packages/app/src/components/empty-state/CreatePromptComposer.tsx
index 1085c97b7..66e618b86 100644
--- a/packages/app/src/components/empty-state/CreatePromptComposer.tsx
+++ b/packages/app/src/components/empty-state/CreatePromptComposer.tsx
@@ -1,6 +1,6 @@
-import type { HandoffTarget } from '@inkeep/open-knowledge-core';
+import { type HandoffTarget, TERMINAL_CLIS, type TerminalCli } from '@inkeep/open-knowledge-core';
import { Trans, useLingui } from '@lingui/react/macro';
-import { ArrowUpRight, Check, ChevronDown, Sparkles, SquareTerminal } from 'lucide-react';
+import { ArrowUpRight, Check, ChevronDown, Sparkles } from 'lucide-react';
import { useEffect, useRef, useState } from 'react';
import {
type CreateScenario,
@@ -8,6 +8,7 @@ import {
} from '@/components/empty-state/use-create-suggestions';
import { TargetIcon } from '@/components/handoff/OpenInAgentMenuItem';
import { useTerminalLaunch } from '@/components/handoff/TerminalLaunchContext';
+import { cliIconTargetId, VISIBLE_CLIS } from '@/components/handoff/terminal-cli-display';
import {
buildCreateHandoffInput,
getDisplayNameDefault,
@@ -53,8 +54,8 @@ export function CreatePromptComposer({ scenario, className }: CreatePromptCompos
readPreferredAgent(),
);
const userPickedRef = useRef(false);
- const [cliMode, setCliMode] = useState(false);
- const cliSelected = cliMode && terminalLaunch !== null;
+ const [selectedCli, setSelectedCli] = useState<TerminalCli | null>(null);
+ const cliSelected = selectedCli !== null && terminalLaunch !== null;
const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -74,21 +75,21 @@ export function CreatePromptComposer({ scenario, className }: CreatePromptCompos
function chooseAgent(targetId: HandoffTarget) {
userPickedRef.current = true;
- setCliMode(false);
+ setSelectedCli(null);
setSelectedAgentId(targetId);
writePreferredAgent(targetId);
}
- function chooseCli() {
+ function chooseCli(cli: TerminalCli) {
userPickedRef.current = true;
- setCliMode(true);
+ setSelectedCli(cli);
}
function launchCli() {
- if (terminalLaunch === null) return;
+ if (terminalLaunch === null || selectedCli === null) return;
const input = buildCreateHandoffInput({ workspace, description: description.trim(), scenario });
if (input === null) return; // Workspace not resolved yet — disabled-trigger contract.
- terminalLaunch.launchInTerminal(input);
+ terminalLaunch.launchInTerminal(input, selectedCli);
}
function handleCreate(targetId: HandoffTarget) {
@@ -191,10 +192,14 @@ export function CreatePromptComposer({ scenario, className }: CreatePromptCompos
className="gap-1.5"
data-testid="create-with-agent"
>
- {cliSelected ? (
+ {cliSelected && selectedCli !== null ? (
<>
- <SquareTerminal aria-hidden="true" className="size-3.5" />
- <Trans>Create with Claude CLI</Trans>
+ <TargetIcon
+ id={cliIconTargetId(selectedCli)}
+ aria-hidden="true"
+ className="size-3.5"
+ />
+ <Trans>Create with {TERMINAL_CLIS[selectedCli].displayName} CLI</Trans>
</>
) : (
<>
@@ -247,24 +252,35 @@ export function CreatePromptComposer({ scenario, className }: CreatePromptCompos
<DropdownMenuLabel>
<Trans>Terminal</Trans>
</DropdownMenuLabel>
- {/* Selects the docked-terminal Claude CLI as the create target
- (the Create button performs the launch). Visible text is
- "Claude" while the accessible name stays "Claude CLI" so AT
- users can tell it apart from the Desktop "Claude" (WCAG
+ {/* Selects a docked-terminal CLI as the create target (the
+ Create button performs the launch). Visible text is the
+ brand name while the accessible name is "<Brand> CLI" so AT
+ users can tell it apart from the matching Desktop row (WCAG
2.5.3 — the name contains the visible label). */}
- <DropdownMenuItem
- onSelect={() => chooseCli()}
- data-testid="create-with-claude-cli"
- aria-label={t`Claude CLI`}
- >
- <SquareTerminal className="size-4" aria-hidden="true" />
- <span className="flex-1">
- <Trans>Claude</Trans>
- </span>
- {cliSelected ? (
- <Check aria-hidden="true" className="size-4 text-muted-foreground" />
- ) : null}
- </DropdownMenuItem>
+ {VISIBLE_CLIS.map((cli) => {
+ const { displayName } = TERMINAL_CLIS[cli];
+ return (
+ <DropdownMenuItem
+ key={cli}
+ onSelect={() => chooseCli(cli)}
+ data-testid={`create-with-cli-${cli}`}
+ aria-label={t`${displayName} CLI`}
+ >
+ <TargetIcon
+ id={cliIconTargetId(cli)}
+ aria-hidden="true"
+ className="size-4"
+ />
+ <span className="flex-1">{displayName}</span>
+ {selectedCli === cli ? (
+ <Check
+ aria-hidden="true"
+ className="size-4 text-muted-foreground"
+ />
+ ) : null}
+ </DropdownMenuItem>
+ );
+ })}
</DropdownMenuGroup>
</>
) : null}
diff --git a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx
index 28a5f10a3..2aee8bd3b 100644
--- a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.dom.test.tsx
@@ -46,7 +46,7 @@ const readyInput: HandoffDispatchInput = {
projectDir: '/project',
};
-const launchCalls: HandoffDispatchInput[] = [];
+const launchCalls: Array<{ input: HandoffDispatchInput; cli: string }> = [];
function installStates(
overrides: Partial<Record<HandoffTarget, InstallState>> = {},
@@ -91,7 +91,9 @@ async function renderSubmenu({
render(
withTerminal ? (
- <TerminalLaunchProvider value={{ launchInTerminal: (i) => launchCalls.push(i) }}>
+ <TerminalLaunchProvider
+ value={{ launchInTerminal: (i, cli) => launchCalls.push({ input: i, cli }) }}
+ >
{submenu}
</TerminalLaunchProvider>
) : (
@@ -184,25 +186,31 @@ describe('OpenInAgentContextSubmenu runtime behavior', () => {
expect(screen.getByText('Terminal')).toBeTruthy();
expect(document.querySelector('[data-slot="dropdown-menu-separator"]')).toBeTruthy();
- const terminalRow = screen.getByTestId('file-tree-open-in-terminal');
+ const terminalRow = screen.getByTestId('file-tree-open-in-terminal-claude');
expect(terminalRow.textContent).toContain('Claude');
expect(terminalRow.textContent).not.toContain('CLI');
expect(terminalRow.getAttribute('aria-label')).toBe('Claude CLI');
+ expect(screen.getByTestId('file-tree-open-in-terminal-codex').getAttribute('aria-label')).toBe(
+ 'Codex CLI',
+ );
+ expect(screen.getByTestId('file-tree-open-in-terminal-cursor').getAttribute('aria-label')).toBe(
+ 'Cursor CLI',
+ );
});
test('terminal row launches via the terminal launcher and does not app-dispatch', async () => {
const { dispatch } = await renderSubmenu({ withTerminal: true });
- await userEvent.click(screen.getByTestId('file-tree-open-in-terminal'));
+ await userEvent.click(screen.getByTestId('file-tree-open-in-terminal-codex'));
- expect(launchCalls).toEqual([readyInput]);
+ expect(launchCalls).toEqual([{ input: readyInput, cli: 'codex' }]);
expect(dispatch).not.toHaveBeenCalled();
});
test('terminal row appends the No workspace hint to its accessible name and stays inert while input is missing', async () => {
await renderSubmenu({ input: null, withTerminal: true });
- const terminalRow = screen.getByTestId('file-tree-open-in-terminal');
+ const terminalRow = screen.getByTestId('file-tree-open-in-terminal-claude');
expect(terminalRow.getAttribute('aria-label')).toBe('Claude CLI, No workspace');
expect(terminalRow.getAttribute('data-disabled')).toBe('');
@@ -215,7 +223,7 @@ describe('OpenInAgentContextSubmenu runtime behavior', () => {
expect(screen.getByText('Desktop')).toBeTruthy();
expect(screen.queryByText('Terminal')).toBeNull();
- expect(screen.queryByTestId('file-tree-open-in-terminal')).toBeNull();
+ expect(screen.queryByTestId('file-tree-open-in-terminal-claude')).toBeNull();
});
test('renders only the Terminal section (no Desktop label, no separator) when no agents are installed', async () => {
@@ -231,7 +239,7 @@ describe('OpenInAgentContextSubmenu runtime behavior', () => {
expect(screen.getByText('Terminal')).toBeTruthy();
expect(screen.queryByText('Desktop')).toBeNull();
- expect(screen.getByTestId('file-tree-open-in-terminal')).toBeTruthy();
+ expect(screen.getByTestId('file-tree-open-in-terminal-claude')).toBeTruthy();
expect(document.querySelector('[data-slot="dropdown-menu-separator"]')).toBeNull();
});
});
diff --git a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx
index 2e67d578e..a1edc7203 100644
--- a/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentContextSubmenu.tsx
@@ -1,7 +1,12 @@
-import type { HandoffOutcome, HandoffTarget, InstallState } from '@inkeep/open-knowledge-core';
+import {
+ type HandoffOutcome,
+ type HandoffTarget,
+ type InstallState,
+ TERMINAL_CLIS,
+} from '@inkeep/open-knowledge-core';
import { t } from '@lingui/core/macro';
import { Trans, useLingui } from '@lingui/react/macro';
-import { Sparkles, SquareTerminal } from 'lucide-react';
+import { Sparkles } from 'lucide-react';
import type { ReactNode } from 'react';
import {
DropdownMenuGroup,
@@ -16,6 +21,7 @@ import { useIsEmbedded } from '@/hooks/use-is-embedded';
import { VISIBLE_TARGETS } from '@/lib/handoff/targets';
import { TargetIcon } from './OpenInAgentMenuItem';
import { useTerminalLaunch } from './TerminalLaunchContext';
+import { cliIconTargetId, VISIBLE_CLIS } from './terminal-cli-display';
import type { HandoffDispatchInput } from './useHandoffDispatch';
export function contextRowHint(inputMissing: boolean): string | null {
@@ -120,31 +126,35 @@ export function OpenInAgentContextSubmenu(props: OpenInAgentContextSubmenuProps)
<DropdownMenuLabel>
<Trans>Terminal</Trans>
</DropdownMenuLabel>
- {/* Launches `claude` in the docked terminal with the right-clicked
- node's scope prompt. Visible text is "Claude"; the accessible
- name is "Claude CLI" (plus the "No workspace" hint when input is
- missing), so it contains the visible label and AT users can tell
- it apart from a Desktop "Claude" row (WCAG 2.5.3 — name contains
- visible label). */}
- <DropdownMenuItem
- onSelect={() => {
- if (input === null) return;
- terminalLaunch.launchInTerminal(input);
- }}
- disabled={inputMissing}
- data-testid="file-tree-open-in-terminal"
- aria-label={hint ? t`Claude CLI, ${hint}` : t`Claude CLI`}
- >
- <SquareTerminal className="size-4" aria-hidden="true" />
- <span className="flex-1">
- <Trans>Claude</Trans>
- </span>
- {hint ? (
- <span aria-hidden="true" className="ml-2 text-muted-foreground text-xs">
- {hint}
- </span>
- ) : null}
- </DropdownMenuItem>
+ {/* Launches `claude` / `codex` / `cursor-agent` in the docked
+ terminal with the right-clicked node's scope prompt. Visible
+ text is the brand name; the accessible name is "<Brand> CLI"
+ (plus the "No workspace" hint when input is missing), so it
+ contains the visible label and AT users can tell it apart from a
+ Desktop row (WCAG 2.5.3 — name contains visible label). */}
+ {VISIBLE_CLIS.map((cli) => {
+ const { displayName } = TERMINAL_CLIS[cli];
+ return (
+ <DropdownMenuItem
+ key={cli}
+ onSelect={() => {
+ if (input === null) return;
+ terminalLaunch.launchInTerminal(input, cli);
+ }}
+ disabled={inputMissing}
+ data-testid={`file-tree-open-in-terminal-${cli}`}
+ aria-label={hint ? t`${displayName} CLI, ${hint}` : t`${displayName} CLI`}
+ >
+ <TargetIcon id={cliIconTargetId(cli)} aria-hidden="true" />
+ <span className="flex-1">{displayName}</span>
+ {hint ? (
+ <span aria-hidden="true" className="ml-2 text-muted-foreground text-xs">
+ {hint}
+ </span>
+ ) : null}
+ </DropdownMenuItem>
+ );
+ })}
</DropdownMenuGroup>
</>
) : null}
diff --git a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx
index d02127b8c..9a295ecbf 100644
--- a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.dom.test.tsx
@@ -45,7 +45,7 @@ const readyInput: HandoffDispatchInput = {
projectDir: '/project',
};
-const launchCalls: HandoffDispatchInput[] = [];
+const launchCalls: Array<{ input: HandoffDispatchInput; cli: string }> = [];
function installStates(
overrides: Partial<Record<HandoffTarget, InstallState>> = {},
@@ -88,7 +88,9 @@ async function renderSubmenu({
render(
withTerminal ? (
- <TerminalLaunchProvider value={{ launchInTerminal: (i) => launchCalls.push(i) }}>
+ <TerminalLaunchProvider
+ value={{ launchInTerminal: (i, cli) => launchCalls.push({ input: i, cli }) }}
+ >
{menu}
</TerminalLaunchProvider>
) : (
@@ -168,19 +170,25 @@ describe('OpenInAgentEmptySpaceSubmenu runtime behavior', () => {
expect(screen.getByText('Terminal')).toBeTruthy();
expect(document.querySelector('[data-slot="context-menu-separator"]')).toBeTruthy();
- const terminalRow = screen.getByTestId('empty-space-open-in-terminal');
+ const terminalRow = screen.getByTestId('empty-space-open-in-terminal-claude');
expect(terminalRow.textContent).toContain('Claude');
expect(terminalRow.textContent).not.toContain('CLI');
expect(terminalRow.getAttribute('aria-label')).toBe('Claude CLI');
+ expect(
+ screen.getByTestId('empty-space-open-in-terminal-codex').getAttribute('aria-label'),
+ ).toBe('Codex CLI');
+ expect(
+ screen.getByTestId('empty-space-open-in-terminal-cursor').getAttribute('aria-label'),
+ ).toBe('Cursor CLI');
});
test('terminal row launches via the terminal launcher and does not app-dispatch', async () => {
const { dispatch } = await renderSubmenu({ withTerminal: true });
await openEmptySpaceSubmenu();
- await userEvent.click(screen.getByTestId('empty-space-open-in-terminal'));
+ await userEvent.click(screen.getByTestId('empty-space-open-in-terminal-cursor'));
- expect(launchCalls).toEqual([readyInput]);
+ expect(launchCalls).toEqual([{ input: readyInput, cli: 'cursor' }]);
expect(dispatch).not.toHaveBeenCalled();
});
@@ -188,7 +196,7 @@ describe('OpenInAgentEmptySpaceSubmenu runtime behavior', () => {
await renderSubmenu({ input: null, withTerminal: true });
await openEmptySpaceSubmenu();
- const terminalRow = screen.getByTestId('empty-space-open-in-terminal');
+ const terminalRow = screen.getByTestId('empty-space-open-in-terminal-claude');
expect(terminalRow.getAttribute('aria-label')).toBe('Claude CLI, No workspace');
expect(terminalRow.getAttribute('data-disabled')).toBe('');
@@ -202,7 +210,7 @@ describe('OpenInAgentEmptySpaceSubmenu runtime behavior', () => {
expect(screen.getByText('Desktop')).toBeTruthy();
expect(screen.queryByText('Terminal')).toBeNull();
- expect(screen.queryByTestId('empty-space-open-in-terminal')).toBeNull();
+ expect(screen.queryByTestId('empty-space-open-in-terminal-claude')).toBeNull();
});
test('renders only the Terminal section (no Desktop label, no separator) when no agents are installed', async () => {
@@ -219,7 +227,7 @@ describe('OpenInAgentEmptySpaceSubmenu runtime behavior', () => {
expect(screen.getByText('Terminal')).toBeTruthy();
expect(screen.queryByText('Desktop')).toBeNull();
- expect(screen.getByTestId('empty-space-open-in-terminal')).toBeTruthy();
+ expect(screen.getByTestId('empty-space-open-in-terminal-claude')).toBeTruthy();
expect(document.querySelector('[data-slot="context-menu-separator"]')).toBeNull();
});
});
diff --git a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
index 3d793e0fc..2fbb5c7b6 100644
--- a/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
@@ -1,7 +1,12 @@
-import type { HandoffOutcome, HandoffTarget, InstallState } from '@inkeep/open-knowledge-core';
+import {
+ type HandoffOutcome,
+ type HandoffTarget,
+ type InstallState,
+ TERMINAL_CLIS,
+} from '@inkeep/open-knowledge-core';
import { t } from '@lingui/core/macro';
import { Trans, useLingui } from '@lingui/react/macro';
-import { Sparkles, SquareTerminal } from 'lucide-react';
+import { Sparkles } from 'lucide-react';
import type { ReactNode } from 'react';
import {
ContextMenuGroup,
@@ -16,6 +21,7 @@ import { useIsEmbedded } from '@/hooks/use-is-embedded';
import { VISIBLE_TARGETS } from '@/lib/handoff/targets';
import { TargetIcon } from './OpenInAgentMenuItem';
import { useTerminalLaunch } from './TerminalLaunchContext';
+import { cliIconTargetId, VISIBLE_CLIS } from './terminal-cli-display';
import type { HandoffDispatchInput } from './useHandoffDispatch';
/** Status hint shown alongside per-target rows when the input is not ready
@@ -110,31 +116,35 @@ export function OpenInAgentEmptySpaceSubmenu(props: OpenInAgentEmptySpaceSubmenu
<ContextMenuLabel>
<Trans>Terminal</Trans>
</ContextMenuLabel>
- {/* Launches `claude` in the docked terminal with the project-scope
- prompt. Visible text is "Claude"; the accessible name is
- "Claude CLI" (plus the "No workspace" hint when input is
- missing), so it contains the visible label and AT users can tell
- it apart from a Desktop "Claude" row (WCAG 2.5.3 — name contains
- visible label). */}
- <ContextMenuItem
- onSelect={() => {
- if (input === null) return;
- terminalLaunch.launchInTerminal(input);
- }}
- disabled={inputMissing}
- data-testid="empty-space-open-in-terminal"
- aria-label={hint ? t`Claude CLI, ${hint}` : t`Claude CLI`}
- >
- <SquareTerminal className="size-4" aria-hidden="true" />
- <span className="flex-1">
- <Trans>Claude</Trans>
- </span>
- {hint ? (
- <span aria-hidden="true" className="ml-2 text-muted-foreground text-xs">
- {hint}
- </span>
- ) : null}
- </ContextMenuItem>
+ {/* Launches `claude` / `codex` / `cursor-agent` in the docked
+ terminal with the project-scope prompt. Visible text is the
+ brand name; the accessible name is "<Brand> CLI" (plus the "No
+ workspace" hint when input is missing), so it contains the
+ visible label and AT users can tell it apart from a Desktop row
+ (WCAG 2.5.3 — name contains visible label). */}
+ {VISIBLE_CLIS.map((cli) => {
+ const { displayName } = TERMINAL_CLIS[cli];
+ return (
+ <ContextMenuItem
+ key={cli}
+ onSelect={() => {
+ if (input === null) return;
+ terminalLaunch.launchInTerminal(input, cli);
+ }}
+ disabled={inputMissing}
+ data-testid={`empty-space-open-in-terminal-${cli}`}
+ aria-label={hint ? t`${displayName} CLI, ${hint}` : t`${displayName} CLI`}
+ >
+ <TargetIcon id={cliIconTargetId(cli)} aria-hidden="true" />
+ <span className="flex-1">{displayName}</span>
+ {hint ? (
+ <span aria-hidden="true" className="ml-2 text-muted-foreground text-xs">
+ {hint}
+ </span>
+ ) : null}
+ </ContextMenuItem>
+ );
+ })}
</ContextMenuGroup>
</>
) : null}
diff --git a/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx
index cf2e25b0b..20d2d623c 100644
--- a/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentMenu.dom.test.tsx
@@ -16,7 +16,7 @@ mock.module('@lingui/react/macro', () => ({
const refreshCalls: string[] = [];
const dispatchCalls: Array<{ target: string; input: HandoffDispatchInput }> = [];
-const launchCalls: HandoffDispatchInput[] = [];
+const launchCalls: Array<{ input: HandoffDispatchInput; cli: string }> = [];
let states: Record<string, { installed: boolean | null; lastChecked?: number }> = {};
mock.module('./useInstalledAgents', () => ({
@@ -71,7 +71,9 @@ async function renderMenuWithTerminal(menuInput: HandoffDispatchInput | null = i
const { OpenInAgentMenu } = await import('./OpenInAgentMenu');
render(
<TooltipProvider>
- <TerminalLaunchProvider value={{ launchInTerminal: (i) => launchCalls.push(i) }}>
+ <TerminalLaunchProvider
+ value={{ launchInTerminal: (i, cli) => launchCalls.push({ input: i, cli }) }}
+ >
<OpenInAgentMenu input={menuInput} />
</TerminalLaunchProvider>
</TooltipProvider>,
@@ -230,7 +232,9 @@ describe('OpenInAgentMenu runtime behavior', () => {
expect(screen.getByText('Desktop')).toBeTruthy();
expect(screen.getByText('Terminal')).toBeTruthy();
- expect(screen.getByTestId('open-in-agent-terminal')).toBeTruthy();
+ expect(screen.getByTestId('open-in-agent-terminal-claude')).toBeTruthy();
+ expect(screen.getByTestId('open-in-agent-terminal-codex')).toBeTruthy();
+ expect(screen.getByTestId('open-in-agent-terminal-cursor')).toBeTruthy();
expect(screen.getByRole('group', { name: 'Desktop' })).toBeTruthy();
expect(screen.getByRole('group', { name: 'Terminal' })).toBeTruthy();
});
@@ -240,8 +244,8 @@ describe('OpenInAgentMenu runtime behavior', () => {
await renderMenuWithTerminal();
await openMenu();
- await userEvent.click(screen.getByTestId('open-in-agent-terminal'));
- expect(launchCalls).toEqual([input]);
+ await userEvent.click(screen.getByTestId('open-in-agent-terminal-claude'));
+ expect(launchCalls).toEqual([{ input, cli: 'claude' }]);
expect(dispatchCalls).toEqual([]);
});
@@ -252,6 +256,6 @@ describe('OpenInAgentMenu runtime behavior', () => {
expect(screen.getByText('Desktop')).toBeTruthy();
expect(screen.queryByText('Terminal')).toBeNull();
- expect(screen.queryByTestId('open-in-agent-terminal')).toBeNull();
+ expect(screen.queryByTestId('open-in-agent-terminal-claude')).toBeNull();
});
});
diff --git a/packages/app/src/components/handoff/OpenInAgentMenu.tsx b/packages/app/src/components/handoff/OpenInAgentMenu.tsx
index 4f23addac..ab8c34e84 100644
--- a/packages/app/src/components/handoff/OpenInAgentMenu.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentMenu.tsx
@@ -1,6 +1,12 @@
-import type { HandoffTarget, InstallState, TargetData } from '@inkeep/open-knowledge-core';
+import {
+ type HandoffTarget,
+ type InstallState,
+ type TargetData,
+ TERMINAL_CLIS,
+ type TerminalCli,
+} from '@inkeep/open-knowledge-core';
import { Trans, useLingui } from '@lingui/react/macro';
-import { Sparkles, SquareTerminal } from 'lucide-react';
+import { Sparkles } from 'lucide-react';
import { type ReactNode, useEffect, useEffectEvent, useRef, useState } from 'react';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
@@ -10,6 +16,7 @@ import { useIsEmbedded } from '@/hooks/use-is-embedded';
import { VISIBLE_TARGETS } from '@/lib/handoff/targets';
import { TargetIcon } from './OpenInAgentMenuItem';
import { type TerminalLaunchContextValue, useTerminalLaunch } from './TerminalLaunchContext';
+import { cliIconTargetId, VISIBLE_CLIS } from './terminal-cli-display';
import { type HandoffDispatchInput, useHandoffDispatch } from './useHandoffDispatch';
import { useInstalledAgents } from './useInstalledAgents';
@@ -31,7 +38,7 @@ interface OpenWithAiPanelProps {
/** Fired when the user picks an agent; carries the typed instruction — the
* empty string when the user dispatched without typing one. */
readonly onPick: (target: TargetData, instruction: string) => void;
- readonly onLaunchTerminal: (instruction: string) => void;
+ readonly onLaunchTerminal: (cli: TerminalCli, instruction: string) => void;
}
function OpenWithAiPanel({
@@ -106,20 +113,24 @@ function OpenWithAiPanel({
>
<Trans>Terminal</Trans>
</legend>
- <Button
- type="button"
- variant="ghost"
- className="h-auto w-full justify-start gap-1.5 rounded-md px-1.5 py-1 font-normal text-foreground"
- disabled={disabled}
- data-testid="open-in-agent-terminal"
- aria-label={t`Claude CLI`}
- onClick={() => onLaunchTerminal(instruction)}
- >
- <SquareTerminal className="size-4" aria-hidden="true" />
- <span>
- <Trans>Claude</Trans>
- </span>
- </Button>
+ {VISIBLE_CLIS.map((cli) => {
+ const { displayName } = TERMINAL_CLIS[cli];
+ return (
+ <Button
+ key={cli}
+ type="button"
+ variant="ghost"
+ className="h-auto w-full justify-start gap-1.5 rounded-md px-1.5 py-1 font-normal text-foreground"
+ disabled={disabled}
+ data-testid={`open-in-agent-terminal-${cli}`}
+ aria-label={t`${displayName} CLI`}
+ onClick={() => onLaunchTerminal(cli, instruction)}
+ >
+ <TargetIcon id={cliIconTargetId(cli)} aria-hidden="true" />
+ <span>{displayName}</span>
+ </Button>
+ );
+ })}
</fieldset>
</>
) : null}
@@ -183,10 +194,10 @@ export function OpenInAgentMenu({ input, open, onOpenChange }: OpenInAgentMenuPr
handleOpenChange(false);
};
- const handleLaunchTerminal = (instruction: string): void => {
+ const handleLaunchTerminal = (cli: TerminalCli, instruction: string): void => {
const next = inputWith(instruction);
if (next === null || terminalLaunch === null) return;
- terminalLaunch.launchInTerminal(next);
+ terminalLaunch.launchInTerminal(next, cli);
handleOpenChange(false);
};
diff --git a/packages/app/src/components/handoff/OpenInAgentTerminalRow.dom.test.tsx b/packages/app/src/components/handoff/OpenInAgentTerminalRow.dom.test.tsx
index 4118772cc..e3b0a72d9 100644
--- a/packages/app/src/components/handoff/OpenInAgentTerminalRow.dom.test.tsx
+++ b/packages/app/src/components/handoff/OpenInAgentTerminalRow.dom.test.tsx
@@ -1,4 +1,5 @@
import { afterEach, describe, expect, mock, test } from 'bun:test';
+import type { TerminalCli } from '@inkeep/open-knowledge-core';
import { cleanup, render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import type { ReactNode } from 'react';
@@ -44,8 +45,10 @@ mock.module('./OpenInAgentMenuItem', () => ({ TargetIcon: () => null }));
const { OpenInAgentMenu } = await import('./OpenInAgentMenu');
const { TerminalLaunchProvider } = await import('./TerminalLaunchContext');
+type LaunchCall = { input: HandoffDispatchInput; cli: TerminalCli };
+
async function renderMenu(opts: {
- launcher: ((input: HandoffDispatchInput) => void) | null;
+ launcher: ((input: HandoffDispatchInput, cli: TerminalCli) => void) | null;
menuInput?: HandoffDispatchInput | null;
}) {
const menuInput = 'menuInput' in opts ? opts.menuInput : input;
@@ -63,38 +66,43 @@ async function openMenu() {
});
}
-describe('Open-with-AI "Claude CLI" row', () => {
+describe('Open-with-AI Terminal CLI rows', () => {
afterEach(() => {
cleanup();
});
- test('renders the terminal row when the launcher is available (desktop)', async () => {
+ test('renders a row per CLI when the launcher is available (desktop)', async () => {
await renderMenu({ launcher: () => {} });
await openMenu();
- expect(screen.getByTestId('open-in-agent-terminal')).toBeTruthy();
+ expect(screen.getByTestId('open-in-agent-terminal-claude')).toBeTruthy();
+ expect(screen.getByTestId('open-in-agent-terminal-codex')).toBeTruthy();
+ expect(screen.getByTestId('open-in-agent-terminal-cursor')).toBeTruthy();
});
- test('hides the terminal row when no launcher is available (web host)', async () => {
+ test('hides the terminal section when no launcher is available (web host)', async () => {
await renderMenu({ launcher: null });
await openMenu();
- expect(screen.queryByTestId('open-in-agent-terminal')).toBeNull();
+ expect(screen.queryByTestId('open-in-agent-terminal-claude')).toBeNull();
+ expect(screen.queryByTestId('open-in-agent-terminal-codex')).toBeNull();
});
- test('clicking the row hands the bare handoff input to the launcher', async () => {
- const calls: HandoffDispatchInput[] = [];
- await renderMenu({ launcher: (i) => calls.push(i) });
+ test('clicking a row hands the bare handoff input + chosen CLI to the launcher', async () => {
+ const calls: LaunchCall[] = [];
+ await renderMenu({ launcher: (i, cli) => calls.push({ input: i, cli }) });
await openMenu();
- await userEvent.click(screen.getByTestId('open-in-agent-terminal'));
- expect(calls).toStrictEqual([input]);
+ await userEvent.click(screen.getByTestId('open-in-agent-terminal-codex'));
+ expect(calls).toStrictEqual([{ input, cli: 'codex' }]);
});
test('typing an instruction threads it onto the launched input', async () => {
- const calls: HandoffDispatchInput[] = [];
- await renderMenu({ launcher: (i) => calls.push(i) });
+ const calls: LaunchCall[] = [];
+ await renderMenu({ launcher: (i, cli) => calls.push({ input: i, cli }) });
await openMenu();
await userEvent.type(screen.getByTestId('open-in-agent-instruction'), 'Add error handling');
- await userEvent.click(screen.getByTestId('open-in-agent-terminal'));
- expect(calls).toStrictEqual([{ ...input, instruction: 'Add error handling' }]);
+ await userEvent.click(screen.getByTestId('open-in-agent-terminal-cursor'));
+ expect(calls).toStrictEqual([
+ { input: { ...input, instruction: 'Add error handling' }, cli: 'cursor' },
+ ]);
});
test('the trigger is disabled when there is no handoff input', async () => {
diff --git a/packages/app/src/components/handoff/TerminalLaunchContext.tsx b/packages/app/src/components/handoff/TerminalLaunchContext.tsx
index 8ee5dfcc9..b4521cab0 100644
--- a/packages/app/src/components/handoff/TerminalLaunchContext.tsx
+++ b/packages/app/src/components/handoff/TerminalLaunchContext.tsx
@@ -1,8 +1,9 @@
+import type { TerminalCli } from '@inkeep/open-knowledge-core';
import { createContext, type ReactNode, use } from 'react';
import type { HandoffDispatchInput } from './useHandoffDispatch';
export interface TerminalLaunchContextValue {
- readonly launchInTerminal: (input: HandoffDispatchInput) => void;
+ readonly launchInTerminal: (input: HandoffDispatchInput, cli: TerminalCli) => void;
}
const TerminalLaunchContext = createContext<TerminalLaunchContextValue | null>(null);
diff --git a/packages/app/src/components/handoff/terminal-cli-display.ts b/packages/app/src/components/handoff/terminal-cli-display.ts
new file mode 100644
index 000000000..46a4df3ea
--- /dev/null
+++ b/packages/app/src/components/handoff/terminal-cli-display.ts
@@ -0,0 +1,15 @@
+import {
+ type HandoffTarget,
+ TERMINAL_CLI_IDS,
+ TERMINAL_CLIS,
+ type TerminalCli,
+} from '@inkeep/open-knowledge-core';
+
+export const VISIBLE_CLIS: readonly TerminalCli[] = TERMINAL_CLI_IDS;
+
+/** CLI id → the handoff target id whose brand icon `TargetIcon` renders. Reads
+ * the single source of truth on the registry (shared with prompt composition)
+ * rather than a parallel local map. */
+export function cliIconTargetId(cli: TerminalCli): HandoffTarget {
+ return TERMINAL_CLIS[cli].handoffTarget;
+}
diff --git a/packages/app/src/components/handoff/terminal-launch-events.test.ts b/packages/app/src/components/handoff/terminal-launch-events.test.ts
index 6c7ec8597..5815a31b7 100644
--- a/packages/app/src/components/handoff/terminal-launch-events.test.ts
+++ b/packages/app/src/components/handoff/terminal-launch-events.test.ts
@@ -1,17 +1,23 @@
import { describe, expect, test } from 'bun:test';
+import type { TerminalCli } from '@inkeep/open-knowledge-core';
import { requestTerminalLaunch, subscribeToTerminalLaunchRequests } from './terminal-launch-events';
describe('terminal-launch-events', () => {
- test('delivers the composed prompt from request to subscriber', () => {
+ test('delivers the composed prompt + chosen CLI from request to subscriber', () => {
const target = new EventTarget();
- const received: string[] = [];
- const unsub = subscribeToTerminalLaunchRequests((p) => received.push(p), target);
+ const received: Array<{ prompt: string; cli: TerminalCli }> = [];
+ const unsub = subscribeToTerminalLaunchRequests(
+ (prompt, cli) => received.push({ prompt, cli }),
+ target,
+ );
- requestTerminalLaunch("Let's work on `foo.md` using Open Knowledge.", target);
- expect(received).toEqual(["Let's work on `foo.md` using Open Knowledge."]);
+ requestTerminalLaunch("Let's work on `foo.md` using Open Knowledge.", 'codex', target);
+ expect(received).toEqual([
+ { prompt: "Let's work on `foo.md` using Open Knowledge.", cli: 'codex' },
+ ]);
unsub();
- requestTerminalLaunch('after unsubscribe', target);
+ requestTerminalLaunch('after unsubscribe', 'cursor', target);
expect(received).toHaveLength(1);
});
});
diff --git a/packages/app/src/components/handoff/terminal-launch-events.ts b/packages/app/src/components/handoff/terminal-launch-events.ts
index f55eca3ec..48f1cdf19 100644
--- a/packages/app/src/components/handoff/terminal-launch-events.ts
+++ b/packages/app/src/components/handoff/terminal-launch-events.ts
@@ -1,33 +1,37 @@
+import type { TerminalCli } from '@inkeep/open-knowledge-core';
+
const TERMINAL_LAUNCH_EVENT = 'open-knowledge:terminal-launch';
interface TerminalLaunchDetail {
readonly prompt: string;
+ readonly cli: TerminalCli;
}
export function requestTerminalLaunch(
prompt: string,
+ cli: TerminalCli,
target: Pick<Window, 'dispatchEvent'> | EventTarget = typeof window === 'undefined'
? new EventTarget()
: window,
): void {
target.dispatchEvent(
- new CustomEvent<TerminalLaunchDetail>(TERMINAL_LAUNCH_EVENT, { detail: { prompt } }),
+ new CustomEvent<TerminalLaunchDetail>(TERMINAL_LAUNCH_EVENT, { detail: { prompt, cli } }),
);
}
export function subscribeToTerminalLaunchRequests(
- onRequest: (prompt: string) => void,
+ onRequest: (prompt: string, cli: TerminalCli) => void,
target: Pick<Window, 'addEventListener' | 'removeEventListener'> | EventTarget = typeof window ===
'undefined'
? new EventTarget()
: window,
): () => void {
const listener = (event: Event) => {
- const prompt =
+ const detail =
event instanceof CustomEvent
- ? (event as CustomEvent<TerminalLaunchDetail>).detail?.prompt
+ ? (event as CustomEvent<TerminalLaunchDetail>).detail
: undefined;
- if (typeof prompt === 'string') onRequest(prompt);
+ if (detail && typeof detail.prompt === 'string') onRequest(detail.prompt, detail.cli);
};
target.addEventListener(TERMINAL_LAUNCH_EVENT, listener as EventListener);
return () => target.removeEventListener(TERMINAL_LAUNCH_EVENT, listener as EventListener);
diff --git a/packages/app/src/components/handoff/useHandoffDispatch.test.ts b/packages/app/src/components/handoff/useHandoffDispatch.test.ts
index 42edf4eb6..b62b27208 100644
--- a/packages/app/src/components/handoff/useHandoffDispatch.test.ts
+++ b/packages/app/src/components/handoff/useHandoffDispatch.test.ts
@@ -1364,23 +1364,29 @@ describe('runHandoffDispatch — selection scope', () => {
describe('composeTerminalLaunchPrompt — docked-terminal launcher always suppresses the trailer', () => {
test('file scope omits the "Open the OK editor in web view." trailer', async () => {
const { composeTerminalLaunchPrompt } = await import('./useHandoffDispatch');
- const out = composeTerminalLaunchPrompt({
- docContext: { relativePath: 'notes/today.md' },
- projectDir: '/proj',
- docPath: '/proj/notes/today.md',
- });
+ const out = composeTerminalLaunchPrompt(
+ {
+ docContext: { relativePath: 'notes/today.md' },
+ projectDir: '/proj',
+ docPath: '/proj/notes/today.md',
+ },
+ 'claude',
+ );
expect(out).toBe(withSkillPointer("Let's work on `notes/today.md` using Open Knowledge."));
expect(out).not.toContain('Open the OK editor');
});
test('folder scope omits the trailer', async () => {
const { composeTerminalLaunchPrompt } = await import('./useHandoffDispatch');
- const out = composeTerminalLaunchPrompt({
- docContext: null,
- folderRelativePath: 'specs/foo',
- projectDir: '/proj',
- docPath: '',
- });
+ const out = composeTerminalLaunchPrompt(
+ {
+ docContext: null,
+ folderRelativePath: 'specs/foo',
+ projectDir: '/proj',
+ docPath: '',
+ },
+ 'claude',
+ );
expect(out).toBe(
withSkillPointer("Let's work on the `specs/foo` folder using Open Knowledge."),
);
@@ -1389,15 +1395,30 @@ describe('composeTerminalLaunchPrompt — docked-terminal launcher always suppre
test('project / empty-space scope omits the trailer', async () => {
const { composeTerminalLaunchPrompt } = await import('./useHandoffDispatch');
- const out = composeTerminalLaunchPrompt({
- docContext: null,
- projectDir: '/proj',
- docPath: '',
- });
+ const out = composeTerminalLaunchPrompt(
+ {
+ docContext: null,
+ projectDir: '/proj',
+ docPath: '',
+ },
+ 'claude',
+ );
expect(out).toBe(withSkillPointer("Let's work on this project using Open Knowledge."));
expect(out).not.toContain('Open the OK editor');
});
+ test('codex / cursor compose the same directive prompt as claude (target only varies for selection scope)', async () => {
+ const { composeTerminalLaunchPrompt } = await import('./useHandoffDispatch');
+ const input = {
+ docContext: { relativePath: 'notes/today.md' },
+ projectDir: '/proj',
+ docPath: '/proj/notes/today.md',
+ };
+ const claudeOut = composeTerminalLaunchPrompt(input, 'claude');
+ expect(composeTerminalLaunchPrompt(input, 'codex')).toBe(claudeOut);
+ expect(composeTerminalLaunchPrompt(input, 'cursor')).toBe(claudeOut);
+ });
+
test('terminal launch drops the trailer while the web deep-link handoff retains it for the same input', async () => {
const { composeTerminalLaunchPrompt, selectScopedPrompt } = await import(
'./useHandoffDispatch'
@@ -1407,7 +1428,7 @@ describe('composeTerminalLaunchPrompt — docked-terminal launcher always suppre
projectDir: '/proj',
docPath: '/proj/notes/today.md',
};
- const terminalPrompt = composeTerminalLaunchPrompt(input);
+ const terminalPrompt = composeTerminalLaunchPrompt(input, 'claude');
const webHandoffPrompt = selectScopedPrompt(input, 'claude-code', true);
expect(terminalPrompt).not.toContain('Open the OK editor');
diff --git a/packages/app/src/components/handoff/useHandoffDispatch.ts b/packages/app/src/components/handoff/useHandoffDispatch.ts
index d1a8271fd..b1d8c9a40 100644
--- a/packages/app/src/components/handoff/useHandoffDispatch.ts
+++ b/packages/app/src/components/handoff/useHandoffDispatch.ts
@@ -11,6 +11,8 @@ import {
type HandoffScope,
type HandoffTarget,
type TargetData,
+ TERMINAL_CLIS,
+ type TerminalCli,
withSkillPointer,
} from '@inkeep/open-knowledge-core';
import { toast as sonnerToast } from 'sonner';
@@ -240,8 +242,8 @@ export function selectScopedPrompt(
return withSkillPointer(directive);
}
-export function composeTerminalLaunchPrompt(input: HandoffDispatchInput): string {
- return selectScopedPrompt(input, 'claude-code', false);
+export function composeTerminalLaunchPrompt(input: HandoffDispatchInput, cli: TerminalCli): string {
+ return selectScopedPrompt(input, TERMINAL_CLIS[cli].handoffTarget, false);
}
export async function runHandoffDispatch(
diff --git a/packages/app/src/lib/desktop-bridge-types.ts b/packages/app/src/lib/desktop-bridge-types.ts
index f3dbc50ba..940e2ac5c 100644
--- a/packages/app/src/lib/desktop-bridge-types.ts
+++ b/packages/app/src/lib/desktop-bridge-types.ts
@@ -6,6 +6,7 @@ import type {
LocalOpOkInitResponse,
OkFolderState,
RecentProjectEntry,
+ TerminalCli,
} from '@inkeep/open-knowledge-core';
export type { OkFolderState, RecentProjectEntry };
@@ -454,6 +455,13 @@ export interface ClaudeReadiness {
readonly rewireError?: string;
}
+/** On-PATH readiness for a non-Claude agent CLI (codex / cursor-agent) in the
+ * docked terminal. Canonical shape in `desktop/src/shared/bridge-contract.ts`;
+ * mirrored verbatim here (drift-tested). */
+export interface CliReadiness {
+ readonly onPath: 'present' | 'not-found' | 'unknown';
+}
+
export interface OkDesktopBridge {
readonly config: OkDesktopConfig;
onProjectSwitched(cb: (next: OkDesktopConfig) => void): OkUnsubscribe;
@@ -712,6 +720,7 @@ export interface OkDesktopBridge {
onData(cb: (msg: OkPtyData) => void): OkUnsubscribe;
onExit(cb: (msg: OkPtyExit) => void): OkUnsubscribe;
claudePreflight(): Promise<ClaudeReadiness>;
+ cliPreflight(cli: TerminalCli): Promise<CliReadiness>;
rewireClaudeMcp(): Promise<ClaudeReadiness>;
};
diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.json
index 257f99092..19c0c2913 100644
--- a/packages/app/src/locales/en/messages.json
+++ b/packages/app/src/locales/en/messages.json
@@ -171,6 +171,7 @@
"4jDd0j": ["Anyone can see"],
"4niEzY": ["Sandboxed HTML embed — write HTML, see the rendered preview live."],
"4nj6n8": ["/api/config returned HTTP ", ["code"]],
+ "4rjwLG": ["Create with ", ["0"], " CLI"],
"4sKwf6": ["File already exists"],
"4uNLmk": ["Pulling"],
"4v2Yyz": ["Select every visible file-tree row when focus is in the Files sidebar."],
@@ -386,6 +387,7 @@
],
"AB4qw9": ["New terminal"],
"AE7BY3": ["The terminal session ended."],
+ "AIn2Yv": [["displayName"], " CLI, ", ["hint"]],
"ALhMYW": ["Terminal"],
"AMyJts": [
"This path is on an external volume (/Volumes/...). Open Knowledge will lose track of files when the drive ejects."
@@ -399,7 +401,6 @@
],
"AVW-K9": ["Failed to load orphan pages"],
"AWOSPo": ["Zoom in"],
- "AcK_r0": ["Claude CLI"],
"AdcGcG": ["Applying your change"],
"AddR83": ["Could not create project. Try again or pick a different location."],
"AeHuzT": ["# One pattern per line.\n# Examples:\n# drafts/\n# *.draft.md\n# !keep.md"],
@@ -533,6 +534,7 @@
"Evq3lu": ["Orphan mode"],
"ExPiRQ": ["Move to the next CodeMirror lint diagnostic."],
"F-NRCj": ["Add property"],
+ "F0OA00": ["Get ", ["displayName"]],
"F4IYWe": ["Share doc"],
"F4vEsL": ["Sync status: ", ["syncStateLabel"]],
"F6pfE9": ["Active"],
@@ -724,7 +726,6 @@
"LpB85N": ["Plain"],
"LtI9AS": ["Owner"],
"LtSYdi": ["Reveal in Finder"],
- "LtVw4J": ["Claude CLI, ", ["hint"]],
"LuoJWu": [
[
"truncatedShownCount",
@@ -871,6 +872,7 @@
"QQghPu": ["Install in Claude Desktop"],
"QR5SP1": ["created template"],
"QWks14": ["A short line shown under the name in the template list."],
+ "QYfQdv": [["displayName"], " CLI"],
"QcpeeE": ["Navigate to ", ["docName"]],
"QlxHAH": ["Showing results for \"", ["semanticResultsLabel"], "\""],
"QqBQu1": ["Label <0>(visible link text)</0>"],
@@ -1321,7 +1323,6 @@
"fYjgXu": ["Unordered list of items."],
"fbdLmk": ["Toggle bold formatting."],
"fbsiBw": ["Something went wrong starting the terminal."],
- "fcgvCA": ["Claude"],
"fiMNLl": ["Sync settings not yet loaded — try again in a moment"],
"fqSfXY": ["Replace"],
"fwhX-N": ["Indent or outdent source"],
@@ -1389,7 +1390,6 @@
"haHgQj": ["Copied relative path"],
"he3ygx": ["Copy"],
"hjO0Mq": ["Add tab"],
- "hozzkE": ["Create with Claude CLI"],
"hpDtUm": ["External wiki link"],
"hwFOFD": ["Settings failed to load"],
"hxBHxQ": ["A line with a footnote<0><1>[1]</1></0> and a definition shown below."],
@@ -1699,6 +1699,7 @@
"rNifQd": ["Remove property"],
"rQAQus": ["Couldn't save template: ", ["error"]],
"rQRrkB": ["yesterday"],
+ "rSoi6g": [["displayName"], " (", ["bin"], ") isn't installed or on your PATH."],
"rVgSRB": ["Collapse ", ["docName"]],
"rVxu1k": ["No pages link here yet."],
"rXz97P": ["Numbered list of items."],
diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.po
index 61b11204a..10847a9a0 100644
--- a/packages/app/src/locales/en/messages.po
+++ b/packages/app/src/locales/en/messages.po
@@ -228,6 +228,22 @@ msgstr "{diffHrs}h ago"
msgid "{diffMin}m ago"
msgstr "{diffMin}m ago"
+#: src/components/TerminalCliMissingBanner.tsx
+msgid "{displayName} ({bin}) isn't installed or on your PATH."
+msgstr "{displayName} ({bin}) isn't installed or on your PATH."
+
+#: src/components/empty-state/CreatePromptComposer.tsx
+#: src/components/handoff/OpenInAgentContextSubmenu.tsx
+#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
+#: src/components/handoff/OpenInAgentMenu.tsx
+msgid "{displayName} CLI"
+msgstr "{displayName} CLI"
+
+#: src/components/handoff/OpenInAgentContextSubmenu.tsx
+#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
+msgid "{displayName} CLI, {hint}"
+msgstr "{displayName} CLI, {hint}"
+
#. placeholder {0}: formatFileSize(size)
#. placeholder {1}: formatFileSize(limit)
#: src/components/LargeFileEditorState.tsx
@@ -956,25 +972,6 @@ msgstr "Choose agent"
msgid "Choose whether this project's Open Knowledge setup, including its AI-tool connections, is saved with the project so teammates get it too, or kept only on your computer."
msgstr "Choose whether this project's Open Knowledge setup, including its AI-tool connections, is saved with the project so teammates get it too, or kept only on your computer."
-#: src/components/empty-state/CreatePromptComposer.tsx
-#: src/components/handoff/OpenInAgentContextSubmenu.tsx
-#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
-#: src/components/handoff/OpenInAgentMenu.tsx
-msgid "Claude"
-msgstr "Claude"
-
-#: src/components/empty-state/CreatePromptComposer.tsx
-#: src/components/handoff/OpenInAgentContextSubmenu.tsx
-#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
-#: src/components/handoff/OpenInAgentMenu.tsx
-msgid "Claude CLI"
-msgstr "Claude CLI"
-
-#: src/components/handoff/OpenInAgentContextSubmenu.tsx
-#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
-msgid "Claude CLI, {hint}"
-msgstr "Claude CLI, {hint}"
-
#: src/components/ClaudeReadinessBanner.tsx
msgid "Claude Code (claude) isn't installed or on your PATH."
msgstr "Claude Code (claude) isn't installed or on your PATH."
@@ -1693,9 +1690,10 @@ msgstr "Create template"
msgid "Create with {0}"
msgstr "Create with {0}"
+#. placeholder {0}: TERMINAL_CLIS[selectedCli].displayName
#: src/components/empty-state/CreatePromptComposer.tsx
-msgid "Create with Claude CLI"
-msgstr "Create with Claude CLI"
+msgid "Create with {0} CLI"
+msgstr "Create with {0} CLI"
#: src/components/FileTree.tsx
msgid "Create your first file"
@@ -1890,6 +1888,7 @@ msgstr "Disconnecting"
#: src/components/ClaudeReadinessBanner.tsx
#: src/components/NavigatorApp.tsx
#: src/components/settings/SharingSection.tsx
+#: src/components/TerminalCliMissingBanner.tsx
msgid "Dismiss"
msgstr "Dismiss"
@@ -2641,6 +2640,10 @@ msgstr "Full path"
msgid "General"
msgstr "General"
+#: src/components/TerminalCliMissingBanner.tsx
+msgid "Get {displayName}"
+msgstr "Get {displayName}"
+
#: src/components/ClaudeReadinessBanner.tsx
msgid "Get Claude Code"
msgstr "Get Claude Code"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index be439342e..bfd6eed24 100644
--- a/packages/app/src/locales/pseudo/messages.json
+++ b/packages/app/src/locales/pseudo/messages.json
@@ -171,6 +171,7 @@
"4jDd0j": ["Àńŷōńē ćàń śēē"],
"4niEzY": ["Śàńďƀōxēď ĤŢḾĹ ēḿƀēď — ŵŕĩţē ĤŢḾĹ, śēē ţĥē ŕēńďēŕēď ƥŕēvĩēŵ ĺĩvē."],
"4nj6n8": ["/àƥĩ/ćōńƒĩĝ ŕēţũŕńēď ĤŢŢƤ ", ["code"]],
+ "4rjwLG": ["Ćŕēàţē ŵĩţĥ ", ["0"], " ĆĹĨ"],
"4sKwf6": ["Ƒĩĺē àĺŕēàďŷ ēxĩśţś"],
"4uNLmk": ["Ƥũĺĺĩńĝ"],
"4v2Yyz": ["Śēĺēćţ ēvēŕŷ vĩśĩƀĺē ƒĩĺē-ţŕēē ŕōŵ ŵĥēń ƒōćũś ĩś ĩń ţĥē Ƒĩĺēś śĩďēƀàŕ."],
@@ -386,6 +387,7 @@
],
"AB4qw9": ["Ńēŵ ţēŕḿĩńàĺ"],
"AE7BY3": ["Ţĥē ţēŕḿĩńàĺ śēśśĩōń ēńďēď."],
+ "AIn2Yv": [["displayName"], " ĆĹĨ, ", ["hint"]],
"ALhMYW": ["Ţēŕḿĩńàĺ"],
"AMyJts": [
"Ţĥĩś ƥàţĥ ĩś ōń àń ēxţēŕńàĺ vōĺũḿē (/Vōĺũḿēś/...). Ōƥēń Ķńōŵĺēďĝē ŵĩĺĺ ĺōśē ţŕàćķ ōƒ ƒĩĺēś ŵĥēń ţĥē ďŕĩvē ēĴēćţś."
@@ -399,7 +401,6 @@
],
"AVW-K9": ["Ƒàĩĺēď ţō ĺōàď ōŕƥĥàń ƥàĝēś"],
"AWOSPo": ["Źōōḿ ĩń"],
- "AcK_r0": ["Ćĺàũďē ĆĹĨ"],
"AdcGcG": ["Àƥƥĺŷĩńĝ ŷōũŕ ćĥàńĝē"],
"AddR83": ["Ćōũĺď ńōţ ćŕēàţē ƥŕōĴēćţ. Ţŕŷ àĝàĩń ōŕ ƥĩćķ à ďĩƒƒēŕēńţ ĺōćàţĩōń."],
"AeHuzT": ["# Ōńē ƥàţţēŕń ƥēŕ ĺĩńē.\n# Ēxàḿƥĺēś:\n# ďŕàƒţś/\n# *.ďŕàƒţ.ḿď\n# !ķēēƥ.ḿď"],
@@ -533,6 +534,7 @@
"Evq3lu": ["Ōŕƥĥàń ḿōďē"],
"ExPiRQ": ["Ḿōvē ţō ţĥē ńēxţ ĆōďēḾĩŕŕōŕ ĺĩńţ ďĩàĝńōśţĩć."],
"F-NRCj": ["Àďď ƥŕōƥēŕţŷ"],
+ "F0OA00": ["Ĝēţ ", ["displayName"]],
"F4IYWe": ["Śĥàŕē ďōć"],
"F4vEsL": ["Śŷńć śţàţũś: ", ["syncStateLabel"]],
"F6pfE9": ["Àćţĩvē"],
@@ -724,7 +726,6 @@
"LpB85N": ["Ƥĺàĩń"],
"LtI9AS": ["Ōŵńēŕ"],
"LtSYdi": ["Ŕēvēàĺ ĩń Ƒĩńďēŕ"],
- "LtVw4J": ["Ćĺàũďē ĆĹĨ, ", ["hint"]],
"LuoJWu": [
[
"truncatedShownCount",
@@ -871,6 +872,7 @@
"QQghPu": ["Ĩńśţàĺĺ ĩń Ćĺàũďē Ďēśķţōƥ"],
"QR5SP1": ["ćŕēàţēď ţēḿƥĺàţē"],
"QWks14": ["À śĥōŕţ ĺĩńē śĥōŵń ũńďēŕ ţĥē ńàḿē ĩń ţĥē ţēḿƥĺàţē ĺĩśţ."],
+ "QYfQdv": [["displayName"], " ĆĹĨ"],
"QcpeeE": ["Ńàvĩĝàţē ţō ", ["docName"]],
"QlxHAH": ["Śĥōŵĩńĝ ŕēśũĺţś ƒōŕ \"", ["semanticResultsLabel"], "\""],
"QqBQu1": ["Ĺàƀēĺ <0>(vĩśĩƀĺē ĺĩńķ ţēxţ)</0>"],
@@ -1321,7 +1323,6 @@
"fYjgXu": ["Ũńōŕďēŕēď ĺĩśţ ōƒ ĩţēḿś."],
"fbdLmk": ["Ţōĝĝĺē ƀōĺď ƒōŕḿàţţĩńĝ."],
"fbsiBw": ["Śōḿēţĥĩńĝ ŵēńţ ŵŕōńĝ śţàŕţĩńĝ ţĥē ţēŕḿĩńàĺ."],
- "fcgvCA": ["Ćĺàũďē"],
"fiMNLl": ["Śŷńć śēţţĩńĝś ńōţ ŷēţ ĺōàďēď — ţŕŷ àĝàĩń ĩń à ḿōḿēńţ"],
"fqSfXY": ["Ŕēƥĺàćē"],
"fwhX-N": ["Ĩńďēńţ ōŕ ōũţďēńţ śōũŕćē"],
@@ -1389,7 +1390,6 @@
"haHgQj": ["Ćōƥĩēď ŕēĺàţĩvē ƥàţĥ"],
"he3ygx": ["Ćōƥŷ"],
"hjO0Mq": ["Àďď ţàƀ"],
- "hozzkE": ["Ćŕēàţē ŵĩţĥ Ćĺàũďē ĆĹĨ"],
"hpDtUm": ["Ēxţēŕńàĺ ŵĩķĩ ĺĩńķ"],
"hwFOFD": ["Śēţţĩńĝś ƒàĩĺēď ţō ĺōàď"],
"hxBHxQ": ["À ĺĩńē ŵĩţĥ à ƒōōţńōţē<0><1>[1]</1></0> àńď à ďēƒĩńĩţĩōń śĥōŵń ƀēĺōŵ."],
@@ -1699,6 +1699,7 @@
"rNifQd": ["Ŕēḿōvē ƥŕōƥēŕţŷ"],
"rQAQus": ["Ćōũĺďń'ţ śàvē ţēḿƥĺàţē: ", ["error"]],
"rQRrkB": ["ŷēśţēŕďàŷ"],
+ "rSoi6g": [["displayName"], " (", ["bin"], ") ĩśń'ţ ĩńśţàĺĺēď ōŕ ōń ŷōũŕ ƤÀŢĤ."],
"rVgSRB": ["Ćōĺĺàƥśē ", ["docName"]],
"rVxu1k": ["Ńō ƥàĝēś ĺĩńķ ĥēŕē ŷēţ."],
"rXz97P": ["Ńũḿƀēŕēď ĺĩśţ ōƒ ĩţēḿś."],
diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.po
index bae0d5dfe..848d4d0a5 100644
--- a/packages/app/src/locales/pseudo/messages.po
+++ b/packages/app/src/locales/pseudo/messages.po
@@ -228,6 +228,22 @@ msgstr ""
msgid "{diffMin}m ago"
msgstr ""
+#: src/components/TerminalCliMissingBanner.tsx
+msgid "{displayName} ({bin}) isn't installed or on your PATH."
+msgstr ""
+
+#: src/components/empty-state/CreatePromptComposer.tsx
+#: src/components/handoff/OpenInAgentContextSubmenu.tsx
+#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
+#: src/components/handoff/OpenInAgentMenu.tsx
+msgid "{displayName} CLI"
+msgstr ""
+
+#: src/components/handoff/OpenInAgentContextSubmenu.tsx
+#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
+msgid "{displayName} CLI, {hint}"
+msgstr ""
+
#. placeholder {0}: formatFileSize(size)
#. placeholder {1}: formatFileSize(limit)
#: src/components/LargeFileEditorState.tsx
@@ -951,25 +967,6 @@ msgstr ""
msgid "Choose whether this project's Open Knowledge setup, including its AI-tool connections, is saved with the project so teammates get it too, or kept only on your computer."
msgstr ""
-#: src/components/empty-state/CreatePromptComposer.tsx
-#: src/components/handoff/OpenInAgentContextSubmenu.tsx
-#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
-#: src/components/handoff/OpenInAgentMenu.tsx
-msgid "Claude"
-msgstr ""
-
-#: src/components/empty-state/CreatePromptComposer.tsx
-#: src/components/handoff/OpenInAgentContextSubmenu.tsx
-#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
-#: src/components/handoff/OpenInAgentMenu.tsx
-msgid "Claude CLI"
-msgstr ""
-
-#: src/components/handoff/OpenInAgentContextSubmenu.tsx
-#: src/components/handoff/OpenInAgentEmptySpaceSubmenu.tsx
-msgid "Claude CLI, {hint}"
-msgstr ""
-
#: src/components/ClaudeReadinessBanner.tsx
msgid "Claude Code (claude) isn't installed or on your PATH."
msgstr ""
@@ -1688,8 +1685,9 @@ msgstr ""
msgid "Create with {0}"
msgstr ""
+#. placeholder {0}: TERMINAL_CLIS[selectedCli].displayName
#: src/components/empty-state/CreatePromptComposer.tsx
-msgid "Create with Claude CLI"
+msgid "Create with {0} CLI"
msgstr ""
#: src/components/FileTree.tsx
@@ -1885,6 +1883,7 @@ msgstr ""
#: src/components/ClaudeReadinessBanner.tsx
#: src/components/NavigatorApp.tsx
#: src/components/settings/SharingSection.tsx
+#: src/components/TerminalCliMissingBanner.tsx
msgid "Dismiss"
msgstr ""
@@ -2636,6 +2635,10 @@ msgstr ""
msgid "General"
msgstr ""
+#: src/components/TerminalCliMissingBanner.tsx
+msgid "Get {displayName}"
+msgstr ""
+
#: src/components/ClaudeReadinessBanner.tsx
msgid "Get Claude Code"
msgstr ""
diff --git a/packages/app/tests/stress/fixtures/handoff-mocks.ts b/packages/app/tests/stress/fixtures/handoff-mocks.ts
index 5abba65dd..23b13c955 100644
--- a/packages/app/tests/stress/fixtures/handoff-mocks.ts
+++ b/packages/app/tests/stress/fixtures/handoff-mocks.ts
@@ -360,6 +360,7 @@ export async function installHandoffMocks(page: Page, cfg: HandoffMockConfig): P
onData: () => () => {},
onExit: () => () => {},
claudePreflight: async () => ({ claude: 'present' as const, mcp: 'wired' as const }),
+ cliPreflight: async () => ({ onPath: 'present' as const }),
rewireClaudeMcp: async () => ({ claude: 'present' as const, mcp: 'wired' as const }),
},
platform: 'darwin' as const,
diff --git a/packages/core/src/desktop-bridge.ts b/packages/core/src/desktop-bridge.ts
index 241cea2ef..59d030786 100644
--- a/packages/core/src/desktop-bridge.ts
+++ b/packages/core/src/desktop-bridge.ts
@@ -1,6 +1,7 @@
import type { CreateNewBannerKind } from './constants/create-new-banner.ts';
import type { EditorId } from './constants/editors.ts';
import type { OkFolderState } from './constants/folder-state.ts';
+import type { TerminalCli } from './handoff/terminal-launch.ts';
import type { LocalOpOkInitResponse } from './schemas/api/local-op.ts';
import type { BranchInfoResponse, CheckoutResponse } from './schemas/api/share.ts';
import type { RecentProjectEntry } from './sharing/index.ts';
@@ -446,6 +447,13 @@ export interface ClaudeReadiness {
readonly rewireError?: string;
}
+/** On-PATH readiness for a non-Claude agent CLI (codex / cursor-agent) launched
+ * in the docked terminal. Mirror of the same interface in the desktop bridge
+ * contract + the app renderer copy (drift-tested). */
+export interface CliReadiness {
+ readonly onPath: 'present' | 'not-found' | 'unknown';
+}
+
export interface OkDesktopBridge {
readonly config: OkDesktopConfig;
@@ -705,6 +713,7 @@ export interface OkDesktopBridge {
onData(cb: (msg: OkPtyData) => void): OkUnsubscribe;
onExit(cb: (msg: OkPtyExit) => void): OkUnsubscribe;
claudePreflight(): Promise<ClaudeReadiness>;
+ cliPreflight(cli: TerminalCli): Promise<CliReadiness>;
rewireClaudeMcp(): Promise<ClaudeReadiness>;
};
diff --git a/packages/core/src/handoff/index.ts b/packages/core/src/handoff/index.ts
index 131e56b6e..35270090b 100644
--- a/packages/core/src/handoff/index.ts
+++ b/packages/core/src/handoff/index.ts
@@ -11,7 +11,15 @@ export {
OK_PROJECT_SKILL_POINTER,
withSkillPointer,
} from './prompt-composer.ts';
-export { buildClaudeLaunchCommand, shellSingleQuote } from './terminal-launch.ts';
+export {
+ buildClaudeLaunchCommand,
+ buildCliLaunchCommand,
+ shellSingleQuote,
+ TERMINAL_CLI_IDS,
+ TERMINAL_CLIS,
+ type TerminalCli,
+ type TerminalCliInfo,
+} from './terminal-launch.ts';
export type {
DocContext,
HandoffFailureReason,
diff --git a/packages/core/src/handoff/terminal-launch.test.ts b/packages/core/src/handoff/terminal-launch.test.ts
index 81d88e961..386750797 100644
--- a/packages/core/src/handoff/terminal-launch.test.ts
+++ b/packages/core/src/handoff/terminal-launch.test.ts
@@ -1,5 +1,11 @@
import { describe, expect, it } from 'bun:test';
-import { buildClaudeLaunchCommand, shellSingleQuote } from './terminal-launch.ts';
+import {
+ buildClaudeLaunchCommand,
+ buildCliLaunchCommand,
+ shellSingleQuote,
+ TERMINAL_CLI_IDS,
+ TERMINAL_CLIS,
+} from './terminal-launch.ts';
describe('shellSingleQuote', () => {
it('wraps a plain string in single quotes', () => {
@@ -53,3 +59,23 @@ describe('buildClaudeLaunchCommand', () => {
expect(cmd.endsWith('\r')).toBe(true);
});
});
+
+describe('buildCliLaunchCommand', () => {
+ it('uses the registry binary per CLI, with a positional single-quoted prompt', () => {
+ expect(buildCliLaunchCommand('claude', 'hi')).toBe("claude 'hi'\r");
+ expect(buildCliLaunchCommand('codex', 'hi')).toBe("codex 'hi'\r");
+ expect(buildCliLaunchCommand('cursor', 'hi')).toBe("cursor-agent 'hi'\r");
+ });
+
+ it('escapes injection payloads identically for every CLI', () => {
+ for (const cli of TERMINAL_CLI_IDS) {
+ const cmd = buildCliLaunchCommand(cli, "'; rm -rf / #");
+ expect(cmd).toBe(`${TERMINAL_CLIS[cli].bin} ''\\''; rm -rf / #'\r`);
+ expect(cmd.endsWith('\r')).toBe(true);
+ }
+ });
+
+ it('buildClaudeLaunchCommand is the claude specialization', () => {
+ expect(buildClaudeLaunchCommand('hi')).toBe(buildCliLaunchCommand('claude', 'hi'));
+ });
+});
diff --git a/packages/core/src/handoff/terminal-launch.ts b/packages/core/src/handoff/terminal-launch.ts
index eaffe9158..24f3ae9a5 100644
--- a/packages/core/src/handoff/terminal-launch.ts
+++ b/packages/core/src/handoff/terminal-launch.ts
@@ -1,7 +1,54 @@
+import type { HandoffTarget } from './types.ts';
+
export function shellSingleQuote(s: string): string {
return `'${s.replace(/'/g, "'\\''")}'`;
}
+export type TerminalCli = 'claude' | 'codex' | 'cursor';
+
+export interface TerminalCliInfo {
+ /** PATH binary launched in the PTY. The ONLY value interpolated into the
+ * fixed `<bin> '<prompt>'` shape — a fixed registry value, never user input. */
+ readonly bin: string;
+ readonly displayName: string;
+ readonly docsUrl: string;
+ /** The handoff target this CLI maps to for prompt composition (shared with
+ * the deep-link path) and brand-icon rendering. Single source of truth so
+ * the renderer doesn't re-declare a parallel `cli → HandoffTarget` map. */
+ readonly handoffTarget: HandoffTarget;
+}
+
+export const TERMINAL_CLIS = {
+ claude: {
+ bin: 'claude',
+ displayName: 'Claude',
+ docsUrl: 'https://docs.claude.com/en/docs/claude-code',
+ handoffTarget: 'claude-code',
+ },
+ codex: {
+ bin: 'codex',
+ displayName: 'Codex',
+ docsUrl: 'https://developers.openai.com/codex/cli',
+ handoffTarget: 'codex',
+ },
+ cursor: {
+ bin: 'cursor-agent',
+ displayName: 'Cursor',
+ docsUrl: 'https://cursor.com/docs/cli/overview',
+ handoffTarget: 'cursor',
+ },
+} as const satisfies Record<TerminalCli, TerminalCliInfo>;
+
+export const TERMINAL_CLI_IDS = [
+ 'claude',
+ 'codex',
+ 'cursor',
+] as const satisfies readonly TerminalCli[];
+
+export function buildCliLaunchCommand(cli: TerminalCli, prompt: string): string {
+ return `${TERMINAL_CLIS[cli].bin} ${shellSingleQuote(prompt)}\r`;
+}
+
export function buildClaudeLaunchCommand(prompt: string): string {
- return `claude ${shellSingleQuote(prompt)}\r`;
+ return buildCliLaunchCommand('claude', prompt);
}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 0b0ee9897..ecd3ed712 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -351,6 +351,7 @@ export {
assertNeverUrnIpcLookup,
buildClaudeLaunchCommand,
buildClaudeUrl,
+ buildCliLaunchCommand,
buildCodexUrl,
buildCursorUrl,
type CreateScenario,
@@ -372,6 +373,10 @@ export {
OK_PROJECT_SKILL_POINTER,
shellSingleQuote,
type TargetData,
+ TERMINAL_CLI_IDS,
+ TERMINAL_CLIS,
+ type TerminalCli,
+ type TerminalCliInfo,
URN_HTTP_ONLY,
URN_IPC_REGISTRY,
type UrnIpcLookup,
diff --git a/packages/desktop/src/main/claude-readiness.ts b/packages/desktop/src/main/claude-readiness.ts
index 132e702e1..ddc9e2355 100644
--- a/packages/desktop/src/main/claude-readiness.ts
+++ b/packages/desktop/src/main/claude-readiness.ts
@@ -1,10 +1,16 @@
-import type { ClaudeReadiness } from '../shared/bridge-contract.ts';
+import type { ClaudeReadiness, CliReadiness } from '../shared/bridge-contract.ts';
import { getLogger } from './desktop-logger.ts';
export type ClaudeOnPath = ClaudeReadiness['claude'];
export type McpWiringStatus = ClaudeReadiness['mcp'];
-export const CLAUDE_PROBE_ARGS: readonly string[] = ['-l', '-i', '-c', 'command -v claude'];
+export function cliProbeArgs(bin: string): readonly string[] {
+ return ['-l', '-i', '-c', `command -v ${bin}`];
+}
+
+/** The `claude` probe argv — `cliProbeArgs('claude')`, named for the legacy
+ * readiness path + its unit tests. */
+export const CLAUDE_PROBE_ARGS: readonly string[] = cliProbeArgs('claude');
const PROBE_TIMEOUT_MS = 5000;
@@ -30,11 +36,12 @@ export function runLoginShellProbe(
shell: string,
timers: ProbeTimers,
timeoutMs: number = PROBE_TIMEOUT_MS,
+ args: readonly string[] = CLAUDE_PROBE_ARGS,
): Promise<number | null> {
return new Promise<number | null>((resolve) => {
let child: ProbeChild;
try {
- child = spawn(shell, CLAUDE_PROBE_ARGS);
+ child = spawn(shell, args);
} catch {
resolve(null);
return;
@@ -93,3 +100,20 @@ export async function resolveClaudeReadiness(
}
return { claude: interpretClaudeProbe(code), mcp: mcpStatusFromClassification(kind) };
}
+
+export interface ResolveCliOnPathDeps {
+ /** Runs the login-shell PATH probe for the CLI's binary; resolves the exit
+ * code or `null` (probe failed → UNKNOWN). */
+ probe(): Promise<number | null>;
+}
+
+export async function resolveCliOnPath(deps: ResolveCliOnPathDeps): Promise<CliReadiness> {
+ const code = await deps.probe().catch((err) => {
+ getLogger('cli-readiness').warn(
+ { err: err instanceof Error ? err.message : String(err) },
+ 'cli PATH probe rejected; treating cli presence as unknown',
+ );
+ return null;
+ });
+ return { onPath: interpretClaudeProbe(code) };
+}
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index a540aa223..403acf299 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -35,6 +35,8 @@ import {
CLIENT_VERSION_HEADER,
PROTOCOL_VERSION,
SPAWN_ERROR_LOG,
+ TERMINAL_CLIS,
+ type TerminalCli,
} from '@inkeep/open-knowledge-core';
import {
assertGitAvailable,
@@ -74,7 +76,7 @@ import {
shell,
utilityProcess,
} from 'electron';
-import type { ClaudeReadiness, OkMenuAction } from '../shared/bridge-contract.ts';
+import type { ClaudeReadiness, CliReadiness, OkMenuAction } from '../shared/bridge-contract.ts';
import { type EntryPoint, isEntryPoint } from '../shared/entry-point.ts';
import type {
EditorActiveTargetSnapshot,
@@ -111,7 +113,12 @@ import {
} from './bundle-replace-detector.ts';
import { cascadePosition } from './cascade-position.ts';
import { checkTargetExists as checkTargetExistsImpl } from './check-target-exists.ts';
-import { resolveClaudeReadiness, runLoginShellProbe } from './claude-readiness.ts';
+import {
+ cliProbeArgs,
+ resolveClaudeReadiness,
+ resolveCliOnPath,
+ runLoginShellProbe,
+} from './claude-readiness.ts';
import { requestUserConsent, walkExceedsCap } from './consent-dialog.ts';
import {
CreateNewProjectError,
@@ -1353,35 +1360,46 @@ function formatUnknownError(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
-function resolveTerminalClaudeReadiness(): Promise<ClaudeReadiness> {
- return resolveClaudeReadiness({
- probeClaude: () =>
- runLoginShellProbe(
- (file, args) => {
- const child = spawn(file, [...args], { stdio: 'ignore', shell: false });
- return {
- onExit: (cb) => {
- child.on('exit', (code) => cb(code));
- },
- onError: (cb) => {
- child.on('error', (err) => cb(err));
- },
- kill: () => {
- child.kill('SIGKILL');
- },
- };
+function probeLoginShellOnPath(args?: readonly string[]): Promise<number | null> {
+ return runLoginShellProbe(
+ (file, spawnArgs) => {
+ const child = spawn(file, [...spawnArgs], { stdio: 'ignore', shell: false });
+ return {
+ onExit: (cb) => {
+ child.on('exit', (code) => cb(code));
},
- resolveShell(process.env),
- {
- setTimer: (cb, ms) => setTimeout(cb, ms),
- clearTimer: (token) => clearTimeout(token as ReturnType<typeof setTimeout>),
+ onError: (cb) => {
+ child.on('error', (err) => cb(err));
},
- ),
+ kill: () => {
+ child.kill('SIGKILL');
+ },
+ };
+ },
+ resolveShell(process.env),
+ {
+ setTimer: (cb, ms) => setTimeout(cb, ms),
+ clearTimer: (token) => clearTimeout(token as ReturnType<typeof setTimeout>),
+ },
+ undefined,
+ args,
+ );
+}
+
+function resolveTerminalClaudeReadiness(): Promise<ClaudeReadiness> {
+ return resolveClaudeReadiness({
+ probeClaude: () => probeLoginShellOnPath(),
classifyMcpEntry: () =>
createMcpWiringCliSurface().classifyExistingMcpEntry('claude', osHomedir()).kind,
});
}
+function resolveTerminalCliOnPath(cli: TerminalCli): Promise<CliReadiness> {
+ return resolveCliOnPath({
+ probe: () => probeLoginShellOnPath(cliProbeArgs(TERMINAL_CLIS[cli].bin)),
+ });
+}
+
function pickLoadedRendererForMcpDialog(): McpWiringDispatchTarget | undefined {
const isUsable = (win: BrowserWindow): boolean =>
!win.isDestroyed() && !win.webContents.isLoading();
@@ -1576,6 +1594,14 @@ function registerIpcHandlers() {
return rewireError === undefined ? readiness : { ...readiness, rewireError };
});
+ handle('ok:terminal:cli-preflight', async (_event, req): Promise<CliReadiness> => {
+ if (!(req.cli in TERMINAL_CLIS)) {
+ getLogger('terminal').warn({ cli: req.cli }, 'cli-preflight: unknown cli discriminant');
+ return { onPath: 'unknown' };
+ }
+ return resolveTerminalCliOnPath(req.cli);
+ });
+
handle('ok:dialog:open-folder', async (_event, opts) => {
return promptForExistingFolder(dialog, opts);
});
diff --git a/packages/desktop/src/preload/index.ts b/packages/desktop/src/preload/index.ts
index 8d6a89bea..0dfe992b6 100644
--- a/packages/desktop/src/preload/index.ts
+++ b/packages/desktop/src/preload/index.ts
@@ -520,6 +520,7 @@ const bridge: OkDesktopBridge = {
return () => ipcRenderer.removeListener('ok:pty:exit', listener);
},
claudePreflight: () => invoke('ok:terminal:claude-assist', { action: 'preflight' }),
+ cliPreflight: (cli) => invoke('ok:terminal:cli-preflight', { cli }),
rewireClaudeMcp: () => invoke('ok:terminal:claude-assist', { action: 'rewire' }),
},
diff --git a/packages/desktop/src/shared/bridge-contract.ts b/packages/desktop/src/shared/bridge-contract.ts
index 3a270ba51..26ddfd308 100644
--- a/packages/desktop/src/shared/bridge-contract.ts
+++ b/packages/desktop/src/shared/bridge-contract.ts
@@ -6,6 +6,7 @@ import type {
EditorId,
LocalOpOkInitResponse,
OkFolderState,
+ TerminalCli,
} from '@inkeep/open-knowledge-core';
export type { BridgeWorktreeEntry };
@@ -429,6 +430,10 @@ export interface ClaudeReadiness {
readonly rewireError?: string;
}
+export interface CliReadiness {
+ readonly onPath: 'present' | 'not-found' | 'unknown';
+}
+
export interface OkDesktopBridge {
readonly config: OkDesktopConfig;
@@ -716,6 +721,7 @@ export interface OkDesktopBridge {
onData(cb: (msg: OkPtyData) => void): OkUnsubscribe;
onExit(cb: (msg: OkPtyExit) => void): OkUnsubscribe;
claudePreflight(): Promise<ClaudeReadiness>;
+ cliPreflight(cli: TerminalCli): Promise<CliReadiness>;
rewireClaudeMcp(): Promise<ClaudeReadiness>;
};
diff --git a/packages/desktop/src/shared/ipc-channels.ts b/packages/desktop/src/shared/ipc-channels.ts
index 3d8f9126a..defc760bb 100644
--- a/packages/desktop/src/shared/ipc-channels.ts
+++ b/packages/desktop/src/shared/ipc-channels.ts
@@ -5,6 +5,7 @@ import type {
EditorId,
LocalOpOkInitResponse,
OkFolderState,
+ TerminalCli,
} from '@inkeep/open-knowledge-core';
import type {
FindEnclosingGitRootResult,
@@ -17,6 +18,7 @@ import type { KeyringSmokeResult } from '../utility/keyring-smoke.ts';
import type {
CheckTargetExistsResult,
ClaudeReadiness,
+ CliReadiness,
HeadBranchInfo,
OkDesktopConfig,
OkLocalOpAuthReposResponse,
@@ -495,4 +497,8 @@ export interface RequestChannels {
args: [req: { action: 'preflight' | 'rewire' }];
result: ClaudeReadiness;
};
+ 'ok:terminal:cli-preflight': {
+ args: [req: { cli: TerminalCli }];
+ result: CliReadiness;
+ };
}
diff --git a/packages/desktop/tests/main/claude-readiness.test.ts b/packages/desktop/tests/main/claude-readiness.test.ts
index 5f76e03ba..657e5d74d 100644
--- a/packages/desktop/tests/main/claude-readiness.test.ts
+++ b/packages/desktop/tests/main/claude-readiness.test.ts
@@ -1,11 +1,13 @@
import { describe, expect, test } from 'bun:test';
import {
CLAUDE_PROBE_ARGS,
+ cliProbeArgs,
interpretClaudeProbe,
mcpStatusFromClassification,
type ProbeChild,
type ProbeTimers,
resolveClaudeReadiness,
+ resolveCliOnPath,
runLoginShellProbe,
} from '../../src/main/claude-readiness.ts';
@@ -71,6 +73,14 @@ describe('mcpStatusFromClassification', () => {
});
});
+describe('cliProbeArgs', () => {
+ test('builds the login-interactive `command -v <bin>` argv for any binary', () => {
+ expect(cliProbeArgs('codex')).toEqual(['-l', '-i', '-c', 'command -v codex']);
+ expect(cliProbeArgs('cursor-agent')).toEqual(['-l', '-i', '-c', 'command -v cursor-agent']);
+ expect(CLAUDE_PROBE_ARGS).toEqual(cliProbeArgs('claude'));
+ });
+});
+
describe('runLoginShellProbe', () => {
test('spawns the supplied shell with the login-interactive command -v argv', async () => {
const { child, emitExit } = makeFakeChild();
@@ -92,6 +102,25 @@ describe('runLoginShellProbe', () => {
expect(spawnedArgs).toEqual(CLAUDE_PROBE_ARGS);
});
+ test('honors a custom probe argv (per-CLI binary)', async () => {
+ const { child, emitExit } = makeFakeChild();
+ const { timers } = makeFakeTimers();
+ let spawnedArgs: readonly string[] = [];
+ const p = runLoginShellProbe(
+ (_file, args) => {
+ spawnedArgs = args;
+ return child;
+ },
+ 'zsh',
+ timers,
+ undefined,
+ cliProbeArgs('cursor-agent'),
+ );
+ emitExit(0);
+ await p;
+ expect(spawnedArgs).toEqual(['-l', '-i', '-c', 'command -v cursor-agent']);
+ });
+
test('resolves the child exit code and clears the timeout', async () => {
const { child, emitExit } = makeFakeChild();
const { timers, wasCleared } = makeFakeTimers();
@@ -192,3 +221,29 @@ describe('resolveClaudeReadiness', () => {
expect(r).toEqual({ claude: 'present', mcp: 'needs-rewire' });
});
});
+
+describe('resolveCliOnPath', () => {
+ test('exit 0 → on-PATH present', async () => {
+ expect(await resolveCliOnPath({ probe: () => Promise.resolve(0) })).toEqual({
+ onPath: 'present',
+ });
+ });
+
+ test('non-zero exit → not-found', async () => {
+ expect(await resolveCliOnPath({ probe: () => Promise.resolve(127) })).toEqual({
+ onPath: 'not-found',
+ });
+ });
+
+ test('probe-null → unknown (flaky probe is not a definitive not-found)', async () => {
+ expect(await resolveCliOnPath({ probe: () => Promise.resolve(null) })).toEqual({
+ onPath: 'unknown',
+ });
+ });
+
+ test('a rejected probe degrades to unknown, never crashes', async () => {
+ expect(await resolveCliOnPath({ probe: () => Promise.reject(new Error('boom')) })).toEqual({
+ onPath: 'unknown',
+ });
+ });
+});