Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 23 additions & 4 deletions apps/tui/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,12 @@ $PAGER /artifact <n> [file] · /skills /skill <name> (read-only)
client /refresh the thread list · /quit
```

Type `/` in the composer to browse commands, or keep typing to filter them. Use ↑/↓ to
choose and Enter to insert; the next Enter runs a complete command. Commands with arguments
leave a space for you to keep typing. Escape dismisses suggestions without clearing the draft.
Tab still opens threads. Suggestions hide while a blocking prompt or another overlay owns
the keyboard, and on terminals too short to fit the menu above the editor.

## The shape of the screen

Three things worth knowing before moving anything.
Expand Down Expand Up @@ -143,10 +149,23 @@ on the prompt that asks before a write, which is the moment it counts.

## Colour

`src/theme.ts` holds what the colours *mean* — waiting, danger, failed, running, ready, faint —
and the five hues come from `@felix/design`, which owns this repo's palette. It had only a
neutral scale before this: right for surfaces, useless for status, because "waiting on you" and
"this failed" cannot be told apart in greys.
`src/theme.ts` holds what the colours mean. State hues come from `@felix/design`:
green for success, amber for a decision, red for failures, and blue for work in progress.
The terminal adds cyan for tools and navigation, violet for the agent, and blue for your
prompts. The ready composer, connected host, successful tools, and completed plan steps
use green. Replies have a violet side rail; code frames and selected navigation use cyan.
The status line colours the agent, connection, directory, permission mode, and active phase
separately while keeping its single-row width budget.

The composer says **Ask Felix** when idle and **Steer the agent** during a run. Its placeholder
suggests a coding task or pasted error, then a correction or next step while the agent works.
These hints occupy the existing editor and border rather than taking transcript rows.

Tool cards show search scope, rename destinations, and shell working directories when supplied.
Their names, arguments, and activity labels share a width budget so long local calls stay on
one row. Successful shell previews show the final two nonempty output lines, where build and
test summaries usually appear; a leading ellipsis marks omitted output. Artifact handles stay
cyan and reserve their space beside the preview. `/artifact <n>` opens the full spilled result.

**When the palette applies is the interesting part.** A named colour is not a request for the
terminal's palette: `parseColor` resolves `"magenta"` to the literal `#FF00FF`, so the sixteen
Expand Down
12 changes: 10 additions & 2 deletions apps/tui/src/app.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -708,10 +708,18 @@ export function App({
// paragraph, and a shell does not filter its history either.
history.add(text);
setRecent(history.entries());
if (text.startsWith('/')) command(text);
const selection = text.trim();
if (
turns.length === 0 &&
!streaming &&
/^[1-9]\d*$/.test(selection) &&
entry?.starters?.[Number(selection) - 1]
) {
command(`/start ${selection}`);
} else if (text.startsWith('/')) command(text);
else send(text);
},
[command, engine, history, send],
[command, engine, entry, history, send, streaming, turns.length],
);

// The first message from argv, once the engine exists — and once the lease has
Expand Down
33 changes: 33 additions & 0 deletions apps/tui/src/command-hints.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
/** Common commands for discovery; /help remains the full command reference. */
export const COMMAND_HINTS = [
{ name: '/help', description: 'Show commands and keyboard shortcuts', args: false },
{ name: '/plan', description: 'Toggle plan mode', args: false },
{ name: '/think', description: 'Set thinking level: off to max', args: true },
{ name: '/manifest', description: 'List or switch agents', args: true },
{ name: '/start', description: 'Choose a numbered starter prompt', args: true },
{ name: '/artifact', description: 'Open full tool output by number', args: true },
{ name: '/search', description: 'Search conversation history', args: true },
{ name: '/new', description: 'Start a new thread', args: false },
{ name: '/continue', description: 'Continue the current run', args: false },
{ name: '/skills', description: 'Browse available skills', args: false },
{ name: '/skill', description: 'Read a skill by name', args: true },
{ name: '/style', description: 'List or select an output style', args: true },
{ name: '/ask', description: 'Ask a side question', args: true },
{ name: '/rename', description: 'Rename the current thread', args: true },
{ name: '/fork', description: 'Branch the current conversation', args: false },
{ name: '/compact', description: 'Compact conversation context', args: false },
{ name: '/export', description: 'Export the conversation', args: true },
{ name: '/rewind', description: 'Rewind conversation history', args: true },
{ name: '/version', description: 'Switch a prompt version', args: true },
{ name: '/open', description: 'Open a thread or search result', args: true },
{ name: '/refresh', description: 'Refresh the thread list', args: false },
{ name: '/clear', description: 'Clear the current thread history', args: false },
{ name: '/quit', description: 'Exit the terminal client', args: false },
] as const;

export function commandHints(draft: string) {
if (!/^\/[a-z]*$/.test(draft)) return [];
// A complete command is ready to run. Never intercept its Enter key.
if (COMMAND_HINTS.some((hint) => hint.name === draft)) return [];
return COMMAND_HINTS.filter((hint) => hint.name.startsWith(draft));
}
19 changes: 16 additions & 3 deletions apps/tui/src/theme.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@
* every role falls back to an ANSI **index**, which is a reference into the
* user's own sixteen and is themed by them rather than by us.
*
* The five hues come from `@felix/design`, which owns this repo's palette and
* until now had only a neutral scale — right for surfaces, useless for status,
* because "waiting on you" and "this failed" cannot be told apart in greys.
* State hues come from `@felix/design`. Three additional terminal roles
* distinguish navigation and tools (cyan), agent identity (violet), and the
* operator's input (blue), with separate light and dark variants.
*/

import {
Expand Down Expand Up @@ -55,6 +55,12 @@ export const DIM_ITALIC = createTextAttributes({ dim: true, italic: true });
* rather than spread across the components.
*/
export interface Theme {
/** Navigation, commands, and tool names. */
accent: ColorInput;
/** Agent identity, separate from the state of a run. */
agent: ColorInput;
/** Your prompts in the transcript. The ready editor uses green. */
input: ColorInput;
/**
* A transient message in the status area: a confirmation, a listing, `/help`.
* The terminal's own foreground, never `blocked` — amber means a person is
Expand Down Expand Up @@ -114,6 +120,9 @@ export interface Theme {
* respecting a solarized terminal and painting over it.
*/
const INDEXED: Theme = {
accent: RGBA.fromIndex(6),
agent: RGBA.fromIndex(5),
input: RGBA.fromIndex(4),
notice: RGBA.defaultForeground(),
blocked: RGBA.fromIndex(3),
danger: RGBA.fromIndex(9),
Expand Down Expand Up @@ -148,7 +157,11 @@ function tint(state: string, base: string, amount: number): RGBA {
}

function fromPalette(state: StatePalette, neutral: ThemePalette): Theme {
const light = neutral === LIGHT;
return {
accent: RGBA.fromHex(light ? '#0e7490' : '#67d4e8'),
agent: RGBA.fromHex(light ? '#7e22ce' : '#c4a5f5'),
input: RGBA.fromHex(light ? '#1d4ed8' : '#93b4ff'),
notice: RGBA.defaultForeground(),
blocked: RGBA.fromHex(state.blocked),
danger: RGBA.fromHex(state.danger),
Expand Down
141 changes: 110 additions & 31 deletions apps/tui/src/ui/composer.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,10 @@
*/

import type { KeyBinding, KeyEvent, TextareaRenderable } from '@opentui/core';
import { useKeyboard, usePaste } from '@opentui/react';
import { useKeyboard, usePaste, useTerminalDimensions } from '@opentui/react';
import { useEffect, useRef, useState } from 'react';
import { commandHints } from '../command-hints.js';
import { oneLine } from '../text.js';
import type { Theme } from '../theme.js';

/** Any newline, and any run of them, however the source spelled it. */
Expand Down Expand Up @@ -97,11 +99,25 @@ export function Composer({
const ref = useRef<TextareaRenderable>(null);
/** The editor owns the terminal while this is true; nothing else may. */
const [editing, setEditing] = useState(false);
const [draftText, setDraftText] = useState('');
const [completionIndex, setCompletionIndex] = useState(0);
const [completionDismissed, setCompletionDismissed] = useState(false);
const { width, height } = useTerminalDimensions();
/** Index into `history`, or null while editing the draft. */
const recalled = useRef<number | null>(null);
const draft = useRef('');

const active = !disabled && !editing;
const completions = active && height >= 10 && !completionDismissed ? commandHints(draftText) : [];
const selectedCompletion = Math.min(completionIndex, Math.max(0, completions.length - 1));
const completionRows = Math.max(1, Math.min(3, height - 10));
const completionStart = Math.max(
0,
Math.min(
selectedCompletion - Math.floor(completionRows / 2),
completions.length - completionRows,
),
);
const read = () => ref.current?.plainText ?? '';
/**
* Replace the field and leave the cursor at the end, the way a shell leaves a
Expand All @@ -114,6 +130,7 @@ export function Composer({
const write = (text: string) => {
ref.current?.setText(text);
ref.current?.gotoBufferEnd();
setDraftText(text);
};

// Keyed on `n` alone: the text is read when it changes, and re-filling on an
Expand Down Expand Up @@ -146,6 +163,30 @@ export function Composer({
*/
useKeyboard((key: KeyEvent) => {
if (!active) return;
if (completions.length && !key.ctrl && !key.meta && !key.shift) {
if (key.name === 'escape') {
key.preventDefault();
// This Escape belongs to the menu. Stop the parent's global handler
// too, so dismissing suggestions during a run does not abort it.
key.stopPropagation();
setCompletionDismissed(true);
return;
}
if (key.name === 'up' || key.name === 'down') {
key.preventDefault();
setCompletionIndex(
(selectedCompletion + (key.name === 'up' ? -1 : 1) + completions.length) %
completions.length,
);
return;
}
if (key.name === 'return' || key.name === 'kpenter') {
key.preventDefault();
const choice = completions[selectedCompletion];
if (choice) write(`${choice.name}${choice.args ? ' ' : ''}`);
return;
}
}
if (key.ctrl && key.name === 'e') {
key.preventDefault();
if (!onEdit) return;
Expand Down Expand Up @@ -197,36 +238,74 @@ export function Composer({
});

return (
// Framed, because an unframed prompt does not read as somewhere you type —
// it reads as the last line of the transcript. The border also gives the
// hint somewhere to live that is not a row of its own: `bottomTitle` costs
// nothing vertically, where the old inline hint cost a line the
// conversation could have had.
<box
flexDirection="row"
// Never give ground to the transcript. The transcript grows to fill, and
// with a conversation longer than the screen it will take these rows too:
// the input line vanishes and the marker is squashed into the bottom
// border, leaving a box you cannot type in and no sign of why.
flexShrink={0}
border
borderStyle="rounded"
borderColor={active ? theme.ready : theme.rule}
bottomTitle={hint ?? ''}
bottomTitleAlignment="left"
paddingLeft={1}
paddingRight={1}
>
<text fg={streaming ? theme.running : theme.ready}>{streaming ? '⇥ ' : '> '}</text>
<textarea
ref={ref}
focused={active}
flexGrow={1}
height={2}
wrapMode="word"
keyBindings={CHAT_BINDINGS}
onSubmit={submit}
/>
<box flexDirection="column" flexShrink={0}>
{completions.length ? (
<box flexDirection="column" paddingLeft={2} marginBottom={1}>
<text fg={theme.faint}>
{oneLine(
width < 72
? `${selectedCompletion + 1}/${completions.length} · ↑↓ · enter insert · esc close`
: `Commands · ${selectedCompletion + 1}/${completions.length} · ↑↓ choose · enter insert · esc close`,
Math.max(0, width - 6),
)}
</text>
{completions
.slice(completionStart, completionStart + completionRows)
.map((choice, index) => (
<text key={choice.name}>
<span
fg={completionStart + index === selectedCompletion ? theme.ready : theme.accent}
>
{`${completionStart + index === selectedCompletion ? '›' : ' '} ${choice.name}`}
</span>
<span
fg={theme.faint}
>{` ${oneLine(choice.description, Math.max(0, width - choice.name.length - 10))}`}</span>
</text>
))}
</box>
) : null}
{/* The frame and its hint use the existing editor rows. */}
<box
flexDirection="row"
// Never give ground to the transcript. The transcript grows to fill, and
// with a conversation longer than the screen it will take these rows too:
// the input line vanishes and the marker is squashed into the bottom
// border, leaving a box you cannot type in and no sign of why.
flexShrink={0}
border
borderStyle="rounded"
borderColor={active ? (streaming ? theme.running : theme.ready) : theme.rule}
title={active ? (streaming ? ' Steer the agent ' : ' Ask Felix ') : undefined}
bottomTitle={hint ?? ''}
bottomTitleAlignment="left"
paddingLeft={1}
paddingRight={1}
>
<text fg={streaming ? theme.running : theme.ready}>{streaming ? '⇥ ' : '> '}</text>
<textarea
ref={ref}
focused={active}
flexGrow={1}
height={2}
wrapMode="word"
placeholder={
active
? streaming
? 'Add a correction or next step…'
: 'Describe a task, paste an error, or /help'
: ''
}
placeholderColor={theme.faint}
onContentChange={() => {
setDraftText(read());
setCompletionIndex(0);
setCompletionDismissed(false);
}}
keyBindings={CHAT_BINDINGS}
onSubmit={submit}
/>
</box>
</box>
);
}
17 changes: 11 additions & 6 deletions apps/tui/src/ui/greeting.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,18 @@ export function Greeting({
return (
<box flexDirection="column" marginBottom={1}>
<text>
<span fg={theme.ready}>FELIX</span>
<span attributes={DIM}> · {manifest}</span>
<span fg={theme.ready} attributes={BOLD}>
FELIX
</span>
<span attributes={DIM}> · </span>
<span fg={theme.accent}>{manifest}</span>
</text>
<text attributes={DIM}> </text>
{greeting ? (
<>
<text attributes={BOLD}>{greeting.headline}</text>
<text fg={theme.agent} attributes={BOLD}>
{greeting.headline}
</text>
{greeting.subtitle ? <text attributes={DIM}>{greeting.subtitle}</text> : null}
<text attributes={DIM}> </text>
</>
Expand All @@ -77,14 +82,14 @@ export function Greeting({
<text attributes={DIM}> </text>
{starters.map((s, i) => (
<text key={s.title}>
<span fg={theme.ready}>{` ${i + 1} `}</span>
<span fg={theme.ready} attributes={BOLD}>{` ${i + 1} `}</span>
<span>{s.title}</span>
</text>
))}
<text attributes={DIM}> </text>
<text attributes={DIM}>
/start {starters.length === 1 ? '1' : `1–${starters.length}`} puts one in the composer,
or ask anything. /help for more.
Enter a number or /start {starters.length === 1 ? '1' : `1–${starters.length}`} to put
one in the composer, or ask anything. /help for more.
</text>
</>
) : (
Expand Down
4 changes: 2 additions & 2 deletions apps/tui/src/ui/inspector.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ export function Inspector({
backgroundColor={theme.surface}
border
borderStyle="rounded"
borderColor={theme.ready}
borderColor={theme.accent}
title="inspector"
bottomTitle={oneLine(section.description, 60)}
paddingLeft={1}
Expand All @@ -104,7 +104,7 @@ export function Inspector({
selectedBackgroundColor={theme.surface}
textColor={theme.faint}
focusedTextColor={theme.faint}
selectedTextColor={theme.ready}
selectedTextColor={theme.accent}
selectedDescriptionColor={theme.faint}
ref={stripRef}
/>
Expand Down
Loading
Loading