Customizing Statusline
Use this skill to create or update the global Letta Code statusline mod:
~/.letta/mods/statusline.tsx
The statusline is a panel registered at order: 0 — the primary line just below the input. It overrides the built-in agent · model line. Host UI can still temporarily preempt it for safety confirmations and transient hints.
Statusline ownership model
safety preemption
else transient host hint
else order-0 statusline panel
else built-in default statusline
The order-0 panel owns the whole primary row. It renders text (not React) and owns its own layout via the row/columns helpers.
Workflow
- Check whether
~/.letta/mods/statusline.tsx exists.
- If it exists, read it before editing and preserve unrelated code.
- If it does not exist, synthesize a focused starter for the user's request.
- If the user asks to migrate, import a
.sh file, or match a shell prompt, read references/migration.md.
- If API details or concrete patterns are needed, read
references/api.md and references/examples.md.
- If the request combines statusline work with commands, tools, events, other panels, or stateful mod behavior, also use
creating-mods and its references/architecture.md.
- Guard panel work with
letta.capabilities.ui.panels when writing new files.
- Edit
~/.letta/mods/statusline.tsx.
- 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:
- start from a simple
agent · model statusline
- add project info like git branch, worktree, or PR
- migrate an existing legacy statusline
.sh file
- match shell prompt / PS1
- 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 mods.
- Keep the mod single-file for MVP.
- Do not assume extra npm packages are available.
- Do not use relative multi-file imports yet.
- Keep
render synchronous and side-effect-free. Do not shell, fetch, await, or read files inside render.
- Do async work in setup code, intervals, or subscriptions, store the result in a closure variable, then call
panel.update() to re-render.
- Register the statusline at
order: 0. Compose left/right with row(left, right, width); color with chalk.
- Guard panel work with
letta.capabilities.ui.panels in new files.
- Return a disposer that clears timers/subscriptions and calls
panel.close().
- Preserve existing mod code unless the user asks to reset.
Useful references
references/api.md - panel API, render context, lifecycle rules
references/examples.md - common statusline patterns
references/migration.md - legacy command .sh and PS1 migration
1---2name: customizing-statusline3description: Creates, edits, and migrates Letta Code statusline mods. Use when handling the /statusline command or continuing work started by /statusline.4metadata:5 source: https://skillmd.com/skills/letta-ai/customizing-statusline6---78# Customizing Statusline910Use this skill to create or update the global Letta Code statusline mod:1112```text13~/.letta/mods/statusline.tsx14```1516The statusline is a panel registered at `order: 0` — the primary line just below the input. It overrides the built-in `agent · model` line. Host UI can still temporarily preempt it for safety confirmations and transient hints.1718## Statusline ownership model1920```text21safety preemption22else transient host hint23else order-0 statusline panel24else built-in default statusline25```2627The order-0 panel owns the whole primary row. It renders text (not React) and owns its own layout via the `row`/`columns` helpers.2829## Workflow30311. Check whether `~/.letta/mods/statusline.tsx` exists.322. If it exists, read it before editing and preserve unrelated code.333. If it does not exist, synthesize a focused starter for the user's request.344. If the user asks to migrate, import a `.sh` file, or match a shell prompt, read `references/migration.md`.355. If API details or concrete patterns are needed, read `references/api.md` and `references/examples.md`.366. If the request combines statusline work with commands, tools, events, other panels, or stateful mod behavior, also use `creating-mods` and its `references/architecture.md`.377. Guard panel work with `letta.capabilities.ui.panels` when writing new files.388. Edit `~/.letta/mods/statusline.tsx`.399. Summarize the absolute file path changed and tell the user to run `/reload` unless the command can reload automatically.4041## Bare `/statusline` behavior4243If the user ran `/statusline` without a specific request:4445- If a custom statusline file exists, summarize what it appears to do and ask what they want to change.46- If no custom file exists, explain that Letta is using the built-in default statusline and offer focused next steps:47 1. start from a simple `agent · model` statusline48 2. add project info like git branch, worktree, or PR49 3. migrate an existing legacy statusline `.sh` file50 4. match shell prompt / PS151 5. describe a custom statusline in their own words5253Keep this conversational. Do not build a menu UI unless the product command explicitly asks for one.5455## Rules5657- Global-only for now. Do not create project mods.58- Keep the mod single-file for MVP.59- Do not assume extra npm packages are available.60- Do not use relative multi-file imports yet.61- Keep `render` synchronous and side-effect-free. Do not shell, fetch, await, or read files inside render.62- Do async work in setup code, intervals, or subscriptions, store the result in a closure variable, then call `panel.update()` to re-render.63- Register the statusline at `order: 0`. Compose left/right with `row(left, right, width)`; color with `chalk`.64- Guard panel work with `letta.capabilities.ui.panels` in new files.65- Return a disposer that clears timers/subscriptions and calls `panel.close()`.66- Preserve existing mod code unless the user asks to reset.6768## Useful references6970- `references/api.md` - panel API, render context, lifecycle rules71- `references/examples.md` - common statusline patterns72- `references/migration.md` - legacy command `.sh` and PS1 migration