@letta-ai/letta-code 0.26.1 → 0.26.2

package/skills/customizing-commands/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: customizing-commands
+description: Creates, edits, and enables Letta Code extension-provided slash commands. Use when the user asks to add a custom /command, slash command, command shortcut, SDK-backed command, or command-driven panel behavior.
+---
+
+# Customizing Commands
+
+Use this as the command-specific entrypoint for local extension slash commands. For broader extension work, recipes live in `../creating-extensions/references/commands.md`, `../creating-extensions/references/ui.md`, and `../creating-extensions/references/btw-command.md`.
+
+Extension files live in:
+
+```text
+~/.letta/extensions/
+```
+
+Use a focused file name, e.g. `~/.letta/extensions/review.ts` or `~/.letta/extensions/commands.ts`.
+
+## First decide whether a command is right
+
+| User wants | Build |
+| --- | --- |
+| `/foo` sends a prompt or shows local output | Extension command |
+| `/foo` starts a reusable agent workflow | Skill + thin extension command |
+| Agent/model should autonomously call the capability | Extension tool, not a command |
+| Command shows transient progress/results | Extension command + panel |
+
+If the command is a durable workflow like `/goal`, put the workflow instructions in a skill and keep the extension command as a small launcher/prompt.
+
+## Workflow
+
+1. Inspect `~/.letta/extensions/` for related command files.
+2. Preserve unrelated extension code; create a focused new file if merging is messy.
+3. Register with `letta.commands.register()` and guard with `letta.capabilities.commands`.
+4. Return the unregister function, or a disposer that calls it plus any timer/panel cleanup.
+5. Tell the user the exact file path changed and to run `/reload`.
+
+## Default prompt command
+
+```ts
+export default function activate(letta) {
+  if (!letta.capabilities.commands) return;
+
+  return letta.commands.register({
+    id: "review",
+    description: "Review current git changes",
+    args: "[focus]",
+    run(ctx) {
+      const focus = ctx.args.trim();
+      return {
+        type: "prompt",
+        content: focus
+          ? `Review current git changes. Focus on ${focus}.`
+          : "Review current git changes. Focus on correctness issues.",
+        systemReminder: true,
+      };
+    },
+  });
+}
+```
+
+## Command result types
+
+```ts
+type ExtensionCommandResult =
+  | { type: "prompt"; content: string; systemReminder?: boolean }
+  | { type: "output"; output: string; success?: boolean }
+  | { type: "handled" };
+```
+
+- `prompt`: sends content to the agent. Use for normal slash shortcuts.
+- `output`: prints local text and does not contact the agent.
+- `handled`: command handled its own side effects/UI; common for panel commands.
+
+## Rules
+
+- Command IDs omit the slash: `id: "review"`, not `"/review"`.
+- Use lowercase slugs with letters, numbers, and hyphens.
+- Do not register built-in command IDs.
+- `runWhenBusy: true` commands must not return `prompt` while the main agent is busy; use SDK calls/panels and return `handled`.
+- `showInTranscript: false` commands should usually return `handled`, not `prompt`.
+- Do not import Letta Code app internals.
+- Do not do surprising side effects on startup; extensions activate on app start and `/reload`.
+
+## More recipes
+
+- Simple output command, panel command, SDK command: `../creating-extensions/references/commands.md`
+- Panel/status UI patterns: `../creating-extensions/references/ui.md`
+- Complete `/btw` side-question recipe: `../creating-extensions/references/btw-command.md`

package/skills/customizing-statusline/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: customizing-statusline
+description: Creates, edits, and migrates Letta Code statusline extensions. Use when handling the /statusline command or continuing work started by /statusline.
+---
+
+# Customizing Statusline
+
+Use this skill to create or update the global Letta Code statusline extension:
+
+```text
+~/.letta/extensions/statusline.tsx
+```
+
+The statusline is a full-row idle renderer. Host UI can still temporarily preempt it for safety confirmations and transient hints.
+
+## Statusline ownership model
+
+```text
+safety preemption
+else transient host hint
+else custom statusline extension
+else built-in default statusline
+```
+
+A custom statusline owns the whole idle row. Do not preserve legacy left/right split semantics in the new API.
+
+## Workflow
+
+1. Check whether `~/.letta/extensions/statusline.tsx` exists.
+2. If it exists, read it before editing and preserve unrelated code.
+3. If it does not exist, start from the built-in default template or synthesize a focused starter for the user's request.
+4. If the user asks to migrate, import a `.sh` file, or match a shell prompt, read `references/migration.md`.
+5. If API details or concrete patterns are needed, read `references/api.md` and `references/examples.md`.
+6. Guard statusline-specific behavior with `letta.capabilities.ui.customStatuslineRenderer` when writing new files.
+7. Edit `~/.letta/extensions/statusline.tsx`.
+8. Summarize the absolute file path changed and tell the user to run `/reload` unless the command can reload automatically.
+
+## Bare `/statusline` behavior
+
+If the user ran `/statusline` without a specific request:
+
+- If a custom statusline file exists, summarize what it appears to do and ask what they want to change.
+- If no custom file exists, explain that Letta is using the built-in default statusline and offer focused next steps:
+  1. start from the default Letta statusline
+  2. add project info like git branch, worktree, or PR
+  3. migrate an existing legacy statusline `.sh` file
+  4. match shell prompt / PS1
+  5. describe a custom statusline in their own words
+
+Keep this conversational. Do not build a menu UI unless the product command explicitly asks for one.
+
+## Rules
+
+- Global-only for now. Do not create project extensions.
+- Keep the extension single-file for MVP.
+- Do not assume extra npm packages are available.
+- Do not use relative multi-file imports yet.
+- Keep renderers synchronous. Do not shell, fetch, or await inside render.
+- Do async work in setup code, intervals, subscriptions, or status providers.
+- Use `letta.ui.setStatus` for data and `setStatuslineRenderer` for drawing that data.
+- Guard optional APIs with `letta.capabilities.ui.statusValues` and `letta.capabilities.ui.customStatuslineRenderer` in new files.
+- Return a disposer that clears timers/subscriptions.
+- Preserve existing extension code unless the user asks to reset.
+- Do not delete legacy command statusline files or settings unless the user explicitly asks.
+
+## Useful references
+
+- `references/api.md` - extension API, render context, lifecycle rules
+- `references/examples.md` - common statusline patterns
+- `references/migration.md` - legacy command `.sh` and PS1 migration

package/skills/customizing-statusline/references/api.md

@@ -0,0 +1,168 @@
+# Statusline Extension API
+
+Use this reference when creating or editing `~/.letta/extensions/statusline.tsx`.
+
+## Location
+
+```text
+~/.letta/extensions/statusline.tsx
+```
+
+This is a trusted, user-owned global extension file. Project extensions are intentionally unsupported for now.
+
+## Activation
+
+Export a default function or named `activate` function:
+
+```tsx
+export default function activate(letta) {
+  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+
+  letta.ui.setStatuslineRenderer((context) => {
+    const { Text } = context.components;
+    return <Text>{context.agent.name} · {context.model.displayName}</Text>;
+  });
+}
+```
+
+## API
+
+```ts
+letta.getContext(): StatuslineRenderContext
+
+letta.capabilities.ui.statusValues: boolean
+letta.capabilities.ui.customStatuslineRenderer: boolean
+
+letta.ui.setStatus(key: string, value: string | null | undefined | ((context) => string | null)): void
+letta.ui.clearStatus(key: string): void
+letta.ui.setStatuslineRenderer(renderer: StatuslineRenderer | ((context) => ReactNode | null)): void
+```
+
+`setStatus` stores named string values. Renderers read evaluated values from `context.statuses`.
+
+```tsx
+letta.ui.setStatus("branch", "main");
+
+letta.ui.setStatuslineRenderer((context) => {
+  const { Text } = context.components;
+  return <Text>{context.statuses.branch}</Text>;
+});
+```
+
+## Renderer rules
+
+- Renderer owns the entire idle bottom row.
+- Renderer must be synchronous.
+- Do not run shell commands, network requests, file reads, or awaits inside render.
+- Do async work in setup code or intervals, store results with `setStatus`, then render `context.statuses`.
+- Return `null` only when intentionally rendering nothing.
+
+## Async state pattern
+
+Use Node/Bun APIs directly from the trusted extension file. Do not assume helper methods like `letta.shell` exist.
+
+```tsx
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export default function activate(letta) {
+  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+
+  const update = async () => {
+    try {
+      const context = letta.getContext();
+      const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
+        cwd: context.workspace.currentDir,
+      });
+      if (letta.capabilities.ui.statusValues) {
+        letta.ui.setStatus("branch", stdout.trim());
+      }
+    } catch {
+      if (letta.capabilities.ui.statusValues) {
+        letta.ui.clearStatus("branch");
+      }
+    }
+  };
+
+  letta.ui.setStatuslineRenderer((context) => {
+    const { Text } = context.components;
+    const branch = context.statuses.branch;
+    return <Text>{branch ? `branch ${branch}` : context.agent.name}</Text>;
+  });
+
+  void update();
+  const timer = setInterval(update, 30_000);
+
+  return () => {
+    clearInterval(timer);
+    if (letta.capabilities.ui.statusValues) {
+      letta.ui.clearStatus("branch");
+    }
+  };
+}
+```
+
+## Context fields
+
+The app statusline render context source types live near:
+
+```text
+src/cli/display/statusline/types.ts
+src/cli/display/statusline/context.ts
+```
+
+Common fields:
+
+```ts
+context.components      // Display components such as Text, Box, Spacer
+context.statuses        // evaluated extension status strings
+context.app.version
+context.workspace.cwd
+context.workspace.currentDir
+context.workspace.projectDir
+context.agent.name
+context.agent.id
+context.model.id
+context.model.displayName
+context.model.provider
+context.model.reasoningEffort
+context.permissionMode
+context.terminalWidth
+context.contextWindow.usedPercentage
+context.contextWindow.remainingPercentage
+context.cost.totalDurationMs
+context.cost.totalCostUsd
+context.reflection
+context.memfs
+context.backgroundAgents
+context.rawPayload      // compatibility payload for advanced cases
+```
+
+Prefer semantic fields over `rawPayload` unless migrating old command statuslines.
+
+## Full-row layout
+
+New statuslines do not have a host left/right API. To create left/right visual alignment, do it inside the renderer:
+
+```tsx
+return (
+  <Box flexDirection="row">
+    <Box flexGrow={1}>
+      <Text>left content</Text>
+    </Box>
+    <Text>right content</Text>
+  </Box>
+);
+```
+
+## Reload behavior
+
+After editing `~/.letta/extensions/statusline.tsx`, tell the user to run:
+
+```text
+/reload
+```
+
+The runtime tracks extension loading separately from “no custom statusline,” so a custom statusline should not flash back to the built-in default during reload.

package/skills/customizing-statusline/references/examples.md

@@ -0,0 +1,143 @@
+# Statusline Examples
+
+Use these as patterns, not mandatory templates. Keep the final extension focused on the user's request.
+
+## Agent and model
+
+```tsx
+export default function activate(letta) {
+  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+
+  letta.ui.setStatuslineRenderer((context) => {
+    const { Text } = context.components;
+    return <Text>{context.agent.name ?? "Letta"} · {context.model.displayName ?? "no model"}</Text>;
+  });
+}
+```
+
+## Git branch with fallback
+
+```tsx
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export default function activate(letta) {
+  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+
+  const update = async () => {
+    try {
+      const context = letta.getContext();
+      const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
+        cwd: context.workspace.currentDir,
+      });
+      letta.ui.setStatus("branch", stdout.trim());
+    } catch {
+      letta.ui.clearStatus("branch");
+    }
+  };
+
+  letta.ui.setStatuslineRenderer((context) => {
+    const { Text } = context.components;
+    const branch = context.statuses.branch;
+    return <Text>{branch ? `git ${branch}` : context.agent.name}</Text>;
+  });
+
+  void update();
+  const timer = setInterval(update, 30_000);
+  return () => clearInterval(timer);
+}
+```
+
+## Full row with internal right alignment
+
+```tsx
+export default function activate(letta) {
+  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+
+  letta.ui.setStatuslineRenderer((context) => {
+    const { Box, Text } = context.components;
+    const model = context.model.displayName ?? "no model";
+
+    return (
+      <Box flexDirection="row">
+        <Box flexGrow={1}>
+          <Text dimColor>Press / for commands</Text>
+        </Box>
+        <Text>{context.agent.name ?? "Letta"} · {model}</Text>
+      </Box>
+    );
+  });
+}
+```
+
+## GitHub PR number via `gh`
+
+```tsx
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export default function activate(letta) {
+  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+
+  const update = async () => {
+    try {
+      const context = letta.getContext();
+      const { stdout } = await execFileAsync(
+        "gh",
+        ["pr", "view", "--json", "number,title", "--jq", "\"#\\(.number) \\(.title)\""],
+        { cwd: context.workspace.currentDir },
+      );
+      const pr = stdout.trim();
+      pr ? letta.ui.setStatus("pr", pr) : letta.ui.clearStatus("pr");
+    } catch {
+      letta.ui.clearStatus("pr");
+    }
+  };
+
+  letta.ui.setStatuslineRenderer((context) => {
+    const { Text } = context.components;
+    return <Text>{context.statuses.pr ?? context.model.displayName}</Text>;
+  });
+
+  void update();
+  const timer = setInterval(update, 60_000);
+  return () => clearInterval(timer);
+}
+```
+
+## macOS currently playing track
+
+```tsx
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export default function activate(letta) {
+  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+
+  const update = async () => {
+    try {
+      const script = 'tell application "Music" to if it is running then artist of current track & " - " & name of current track';
+      const { stdout } = await execFileAsync("osascript", ["-e", script]);
+      const music = stdout.trim();
+      music ? letta.ui.setStatus("music", music) : letta.ui.clearStatus("music");
+    } catch {
+      letta.ui.clearStatus("music");
+    }
+  };
+
+  letta.ui.setStatuslineRenderer((context) => {
+    const { Text } = context.components;
+    return <Text>{context.statuses.music ?? context.agent.name}</Text>;
+  });
+
+  void update();
+  const timer = setInterval(update, 15_000);
+  return () => clearInterval(timer);
+}
+```

package/skills/customizing-statusline/references/migration.md

@@ -0,0 +1,131 @@
+# Statusline Migration
+
+Use this reference when migrating legacy command statuslines, standalone `.sh` statusline scripts, or shell PS1 prompts.
+
+## Legacy Letta command statusline
+
+Inspect these files for old config:
+
+```text
+~/.letta/settings.json
+<project>/.letta/settings.json
+<project>/.letta/settings.local.json
+```
+
+Look for either shape:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "..."
+  }
+}
+```
+
+```json
+{
+  "statusLine": {
+    "command": "...",
+    "refreshIntervalMs": 30000,
+    "timeout": 5000,
+    "debounceMs": 300,
+    "padding": 0,
+    "prompt": ">"
+  }
+}
+```
+
+When migrating:
+
+- Preserve old config and referenced files unless the user explicitly asks to delete them.
+- If `command` references a `.sh` file, read it before writing the new extension.
+- Translate polling (`refreshIntervalMs`) to `setInterval`.
+- Translate direct command output into cached status plus synchronous rendering.
+- If the command output used `\x1e` to split left/right output, convert it to internal full-row layout with `Box`; do not create a new left/right API.
+- Treat old prompt customization separately. The new statusline controls the bottom row, not necessarily the input prompt.
+
+Old model:
+
+```sh
+echo "$(git branch --show-current)"
+```
+
+New model:
+
+```tsx
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const update = async () => {
+  const context = letta.getContext();
+  const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
+    cwd: context.workspace.currentDir,
+  });
+  letta.ui.setStatus("branch", stdout.trim());
+};
+
+letta.ui.setStatuslineRenderer((context) => {
+  const { Text } = context.components;
+  return <Text>{context.statuses.branch ?? ""}</Text>;
+});
+```
+
+## Standalone `.sh` file migration
+
+If the user provides a `.sh` path:
+
+1. Read the script.
+2. Identify commands, expected stdin JSON, environment variables, and output shape.
+3. Port shell commands to async setup/update code.
+4. Store results with `letta.ui.setStatus(key, value)`.
+5. Render cached status synchronously.
+6. Preserve graceful fallbacks for missing tools, not-a-git-repo, no PR, etc.
+
+If a script depends heavily on stdin JSON, use `context.rawPayload` as a temporary migration aid, but prefer semantic context fields for new code.
+
+## Shell PS1 import
+
+If the user asks to match their shell prompt, inspect shell config files in this order:
+
+```text
+~/.zshrc
+~/.bashrc
+~/.bash_profile
+~/.profile
+```
+
+Extract PS1 with:
+
+```js
+/(?:^|\n)\s*(?:export\s+)?PS1\s*=\s*["']([^"']+)["']/m
+```
+
+Map common escapes:
+
+```text
+\u -> username
+\h -> short hostname
+\H -> hostname
+\w -> current working directory
+\W -> basename(current working directory)
+\$ -> prompt character, usually remove if trailing
+\n -> newline
+\t -> HH:MM:SS
+\d -> date like Tue May 23
+\@ -> 12-hour time
+\# -> command number, usually omit unless requested
+\! -> history number, usually omit unless requested
+```
+
+If the imported prompt ends with `$`, `>`, or similar prompt chars, remove that trailing prompt marker. The statusline is not the input prompt.
+
+If no PS1 is found and the user did not provide other instructions, ask for one of:
+
+1. the output of `echo $PS1`
+2. a description of what their prompt shows
+3. the current prompt output as it appears in their terminal
+
+Preserve colors where practical using display components. If the PS1 is too dynamic to port exactly, ask whether to approximate it or port specific commands.