Agent-Skills.md

Agent Skills: Customizing Statusline

Creates, edits, and migrates Letta Code statusline mods. Use when handling the /statusline command or continuing work started by /statusline.

UncategorizedID: letta-ai/letta-code/customizing-statusline

Repository

letta-ai/letta-code
letta-aiLicense: Apache-2.0
2,814322

Install this agent skill to your local

pnpm dlx add-skill https://github.com/letta-ai/letta-code/tree/HEAD/src/skills/builtin/customizing-statusline

Skill Files

Browse the full folder contents for customizing-statusline.

Download Skill

Loading file tree…

src/skills/builtin/customizing-statusline/SKILL.md

Skill Metadata

Name
customizing-statusline
Description
Creates, edits, and migrates Letta Code statusline mods. 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 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

  1. Check whether ~/.letta/mods/statusline.tsx exists.
  2. If it exists, read it before editing and preserve unrelated code.
  3. If it does not exist, 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. 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.
  7. Guard panel work with letta.capabilities.ui.panels when writing new files.
  8. Edit ~/.letta/mods/statusline.tsx.
  9. 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 a simple agent · model 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 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