While Starship is a versatile shell, sometimes you need to do more than edit `starship.toml` to get it to do certain things. This page details some of the more advanced configuration techniques used in starship.
It is possible to replace the previous-printed prompt with a custom string. This is useful in cases where all the prompt information is not always needed. To enable this, run `Enable-TransientPrompt` in the shell session. To make it permanent, put this statement in your `$PROFILE`. Transience can be disabled on-the-fly with `Disable-TransientPrompt`.
By default, the left side of input gets replaced with `>`. To customize this, define a new function called `Invoke-Starship-TransientFunction`. For example, to display Starship's `character` module here, you would do
```powershell
functionInvoke-Starship-TransientFunction{
&starshipmodulecharacter
}
Invoke-Expression(&starshipinitpowershell)
Enable-TransientPrompt
```
## TransientPrompt and TransientRightPrompt in Cmd
Clink allows you to replace the previous-printed prompt with custom strings. This is useful in cases where all the prompt information is not always needed. To enable this, run `clink set prompt.transient <value>` where \<value\> can be one of:
-`always`: always replace the previous prompt
-`same_dir`: replace the previous prompt only if the working directory is same
-`off`: do not replace the prompt (i.e. turn off transience)
You need to do this only once. Make the following changes to your `starship.lua` to customize what gets displayed on the left and on the right:
- By default, the left side of input gets replaced with `>`. To customize this, define a new function called `starship_transient_prompt_func`. This function receives the current prompt as a string that you can utilize. For example, to display Starship's `character` module here, you would do
```lua
functionstarship_transient_prompt_func(prompt)
returnio.popen("starship module character"
.." --keymap="..rl.getvariable('keymap')
):read("*a")
end
load(io.popen('starship init cmd'):read("*a"))()
```
- By default, the right side of input is empty. To customize this, define a new function called `starship_transient_rprompt_func`. This function receives the current prompt as a string that you can utilize. For example, to display the time at which the last command was started here, you would do
## TransientPrompt and TransientRightPrompt in Fish
It is possible to replace the previous-printed prompt with a custom string. This is useful in cases where all the prompt information is not always needed. To enable this, run `enable_transience` in the shell session. To make it permanent, put this statement in your `~/.config/fish/config.fish`. Transience can be disabled on-the-fly with `disable_transience`.
Note that in case of Fish, the transient prompt is only printed if the commandline is non-empty, and syntactically correct.
- By default, the left side of input gets replaced with a bold-green `❯`. To customize this, define a new function called `starship_transient_prompt_func`. For example, to display Starship's `character` module here, you would do
```fish
functionstarship_transient_prompt_func
starship module character
end
starship init fish|source
enable_transience
```
- By default, the right side of input is empty. To customize this, define a new function called `starship_transient_rprompt_func`. For example, to display the time at which the last command was started here, you would do
The [Ble.sh](https://github.com/akinomyoga/ble.sh) framework at v0.4 or higher allows you to replace the previous-printed prompt with custom strings. This is useful in cases where all the prompt information is not always needed. To enable this, put this in `~/.bashrc``bleopt prompt_ps1_transient=<value>`:
The \<value\> here is a colon-separated list of `always`, `same-dir` and `trim`.
When `prompt_ps1_final` is empty and the option `prompt_ps1_transient` has a non-empty \<value\>, the prompt specified by `PS1` is erased on leaving the current command line.
If \<value\> contains a field `trim`, only the last line of multiline `PS1` is preserved and the other lines are erased. Otherwise, the command line will be redrawn as if `PS1=` is specified. When a field `same-dir` is contained in \<value\> and the current working directory is different from the final directory of the previous command line, this option `prompt_ps1_transient` is ignored.
- To customize what the left side of input gets replaced with, configure the `prompt_ps1_final` Ble.sh option. For example, to display Starship's `character` module here, you would do
- To customize what the right side of input gets replaced with, configure the `prompt_rps1_final` Ble.sh option. For example, to display the time at which the last command was started here, you would do
## Custom pre-prompt and pre-execution Commands in Cmd
Clink provides extremely flexible APIs to run pre-prompt and pre-exec commands in Cmd shell. It is fairly simple to use with Starship. Make the following changes to your `starship.lua` file as per your requirements:
- To run a custom function right before the prompt is drawn, define a new function called `starship_preprompt_user_func`. This function receives the current prompt as a string that you can utilize. For example, to draw a rocket before the prompt, you would do
```lua
functionstarship_preprompt_user_func(prompt)
print("🚀")
end
load(io.popen('starship init cmd'):read("*a"))()
```
- To run a custom function right before a command is executed, define a new function called `starship_precmd_user_func`. This function receives the current commandline as a string that you can utilize. For example, to print the command that's about to be executed, you would do
- To run a custom function right before the prompt is drawn, define a new function and then assign its name to `starship_precmd_user_func`. For example, to draw a rocket before the prompt, you would do
- To run a custom function right before a command runs, you can use the [`DEBUG` trap mechanism](https://jichu4n.com/posts/debug-trap-and-prompt_command-in-bash/).
However, you **must** trap the DEBUG signal _before_ initializing Starship!
Starship can preserve the value of the DEBUG trap, but if the trap is overwritten after starship starts up, some functionality will break.
Some shells support a right prompt which renders on the same line as the input. Starship can set the content of the right prompt using the `right_format` option. Any module that can be used in `format` is also supported in `right_format`. The `$all` variable will only contain modules not explicitly used in either `format` or `right_format`.
Note: The right prompt is a single line following the input location. To right align modules above the input line in a multi-line prompt, see the [`fill` module](../config/#fill).
When using `zsh` (v5.0.5+), the shell adds a default trailing space to the right prompt. This can cause alignment issues specifically when using the Starship `$fill` module. To remove this gap, add the following to your `.zshrc`:
Some shells support a continuation prompt along with the normal prompt. This prompt is rendered instead of the normal prompt when the user has entered an incomplete statement (such as a single left parenthesis or quote).
Starship supports displaying a custom statusline when running inside Claude Code, Anthropic's CLI tool for interactive coding with Claude. This statusline provides real-time information about your Claude session, including the model being used, context window usage, and session costs.
For more information about the Claude Code statusline feature, see the [Claude Code statusline documentation](https://code.claude.com/docs/en/statusline).
### Setup
To use Starship as your Claude Code statusline:
1. Run `/statusline` in Claude Code and ask it to configure Starship, or manually add the following to your `.claude/settings.json`:
```json
{
"statusLine":{
"type":"command",
"command":"starship statusline claude-code"
}
}
```
2. Customize the statusline appearance in your `~/.config/starship.toml` (see [Configuration](#configuration) below)
### Overview
When invoked with `starship statusline claude-code`, Starship receives Claude Code session data via stdin and renders a statusline using a dedicated profile named `claude-code`.
The profile includes three specialized modules:
-`claude_model`: Displays the current Claude model being used
-`claude_context`: Shows context window usage with a visual gauge
-`claude_cost`: Displays session cost and statistics
You can customize the Claude Code statusline by modifying the `claude-code` profile and individual module configurations in your `~/.config/starship.toml`:
The `claude_context` module displays context window usage as a percentage and visual gauge. The style automatically changes based on configurable thresholds.
| `disabled` | `false` | Disables the `claude_context` module. |
##### Display
The `display` option is an array of objects that define thresholds and styles for different usage levels. The module uses the style from the highest matching threshold or hides the module if `hidden` is `true`.
\*: This variable can only be used as a part of a style string
#### Examples
**Minimal gauge-only display**
```toml
# ~/.config/starship.toml
[claude_context]
format="[$gauge]($style) "
gauge_width=10
```
**Detailed token information**
```toml
# ~/.config/starship.toml
[claude_context]
format="[$percentage ($input_tokens in / $output_tokens out)]($style) "
```
**Custom gauge symbols**
```toml
# ~/.config/starship.toml
[claude_context]
gauge_full_symbol="▰"
gauge_partial_symbol=""
gauge_empty_symbol="▱"
gauge_width=10
format="[$gauge]($style) "
```
**Custom thresholds**
```toml
# ~/.config/starship.toml
[[claude_context.display]]
threshold=0
style="bold green"
[[claude_context.display]]
threshold=50
style="bold yellow"
[[claude_context.display]]
threshold=75
style="bold orange"
[[claude_context.display]]
threshold=90
style="bold red"
```
### Claude Cost
The `claude_cost` module displays the total cost of the current Claude Code session in USD. Like `claude_context`, it supports threshold-based styling.
| `disabled` | `false` | Disables the `claude_cost` module. |
##### Display
The `display` option is an array of objects that define cost thresholds and styles. The module uses the style from the highest matching threshold or hides the module if `hidden` is `true`.
Style strings are a list of words, separated by whitespace. The words are not case sensitive (i.e. `bold` and `BoLd` are considered the same string). Each word can be one of the following:
where `<color>` is a color specifier (discussed below). `fg:<color>` and `<color>` currently do the same thing, though this may change in the future.
`<color>` can also be set to `prev_fg` or `prev_bg` which evaluates to the previous item's foreground or background color respectively if available or `none` otherwise.
`inverted` swaps the background and foreground colors. The order of words in the string does not matter.
The `none` token overrides all other tokens in a string if it is not part of a `bg:` specifier, so that e.g. `fg:red none fg:blue` will still create a string with no styling. `bg:none` sets the background to the default color so `fg:red bg:none` is equivalent to `red` or `fg:red` and `bg:green fg:red bg:none` is also equivalent to `fg:red` or `red`. It may become an error to use `none` in conjunction with other tokens in the future.
- One of the standard terminal colors: `black`, `red`, `green`, `blue`, `yellow`, `purple`, `cyan`, `white`. You can optionally prefix these with `bright-` to get the bright version (e.g. `bright-white`).
- A `#` followed by a six-digit hexadecimal number. This specifies an [RGB color hex code](https://www.w3schools.com/colors/colors_hexadecimal.asp).
- A number between 0-255. This specifies an [8-bit ANSI Color Code](https://i.stack.imgur.com/KTSQa.png).
