Starship 进阶配置实战：Transient Prompt、自定义 Hook、右提示符与 Claude Code 状态栏

Starship 的绝大多数需求在 starship.toml 里就能解决，但还有一类需求——替换已打印的提示符（transient prompt）、在提示符渲染前后插入自定义命令、修改窗口标题、启用右提示符与续行提示符、以及为 Claude Code 提供状态栏——需要借助 shell 层面的钩子与 Starship 提供的内部扩展点来实现。本文以官方文档 docs/advanced-config/README.md 为主线，完整覆盖上述全部进阶技术点，并结合 src/init/ 下各 shell 的初始化脚本与 src/ 中的模块源码，解释每个扩展点的实际工作原理与边界条件，读完即可在 PowerShell、Cmd、Fish、Bash、Zsh 中完成一套完整的进阶定制。

注意：本节描述的这些配置（尤其是各 shell 中约定的钩子函数名）属于 Starship 的内部扩展接口，未来版本可能会变更，升级后建议对照文档复查。

Transient Prompt（瞬时提示符）概述

所谓 transient prompt，是指用一段自定义的短字符串（默认是 > 或 ❯）替换掉上一行已经打印出来的完整提示符。其价值在于：当你不需要每次都在屏幕上方保留完整的项目、Git、运行时信息时，可以让历史行保持干净，只在当前输入行前显示极简符号。Starship 在 PowerShell、Cmd（经 Clink）、Fish、Bash（经 Ble.sh 框架）中分别提供了不同的启用方式，且各 shell 均支持自定义左侧替换内容与（部分 shell）右侧附加内容。

PowerShell 中的 TransientPrompt

在当前 shell 会话中运行 Enable-TransientPrompt 即可启用；要永久生效，将该语句写入 $PROFILE；随时可用 Disable-TransientPrompt 关闭。默认情况下输入行左侧会被替换为 >；要自定义，只需定义一个名为 Invoke-Starship-TransientFunction 的函数。例如，让替换内容显示 Starship 的 character 模块：

function Invoke-Starship-TransientFunction {
  &starship module character
}

Invoke-Expression (&starship init powershell)

Enable-TransientPrompt

从源码结构看，初始化脚本 src/init/starship.ps1 中定义了 Enable-TransientPrompt / Disable-TransientPrompt 两个函数，通过 $script:TransientPrompt 开关控制；在提示符渲染流程中（src/init/starship.ps1），一旦开关为真，就会检测 Test-Path function:Invoke-Starship-TransientFunction，若存在则调用它生成替换文本。这也解释了为什么自定义函数必须使用文档中给定的这个确切名字。

Cmd 中的 TransientPrompt 与 TransientRightPrompt

在安装了 Clink 的 Cmd 环境中，可用自定义字符串替换上一行提示符。启用方式（只需执行一次）：

clink set prompt.transient <value>

其中 <value> 可取：

• always：总是替换上一条提示符
• same_dir：仅当工作目录未变化时替换
• off：不替换（即关闭 transient）

自定义显示内容通过修改 Clink 的配置文件 starship.lua 完成：

• 左侧：默认替换为 >。定义函数 starship_transient_prompt_func，它接收当前提示符字符串作为参数。例如显示 character 模块：

function starship_transient_prompt_func(prompt)
  return io.popen("starship module character"
    .." --keymap="..rl.getvariable('keymap')
  ):read("*a")
end
load(io.popen('starship init cmd'):read("*a"))()

• 右侧：默认为空。定义函数 starship_transient_rprompt_func（同样接收当前提示符字符串）。例如显示上一条命令的启动时间：

function starship_transient_rprompt_func(prompt)
  return io.popen("starship module time"):read("*a")
end
load(io.popen('starship init cmd'):read("*a"))()

其底层接线可以在 src/init/starship.lua 中确认：初始化脚本在检测到 starship_transient_prompt_func / starship_transient_rprompt_func 已定义时，会分别把 Clink 的 starship_prompt:transientfilter 与 starship_prompt:transientrightfilter 挂接到这两个用户函数上。

Fish 中的 TransientPrompt 与 TransientRightPrompt

在 Fish 会话中运行 enable_transience 启用；永久生效请写入 ~/.config/fish/config.fish；disable_transience 可即时关闭。

注意：Fish 的特殊之处是——transient 提示符只在命令行非空且语法正确时才会被打印。

• 左侧：默认替换为加粗绿色的 ❯。定义函数 starship_transient_prompt_func，例如显示 character 模块：

function starship_transient_prompt_func
  starship module character
end
starship init fish | source
enable_transience

• 右侧：默认为空。定义函数 starship_transient_rprompt_func，例如显示上一条命令的启动时间：

function starship_transient_rprompt_func
  starship module time
end
starship init fish | source
enable_transience

从 src/init/starship.fish 的源码可以看到其实现细节：enable_transience 会优先检测 Fish 4.1+ 的内置 transient 支持（fish_transient_prompt），否则回退到绑定回车的自定义 keybinding（bind --user \r __starship_transient_execute），在 fish_postexec 事件中重置 transient 标志，最终在最终渲染阶段（--final-rendering）调用 starship_transient_prompt_func / starship_transient_rprompt_func 生成左右两侧的替换内容。

Bash 中的 Transient Prompt（基于 Ble.sh）

Bash 的 transient prompt 依赖 Ble.sh 框架 v0.4 或更高版本。在 ~/.bashrc 中加入：

bleopt prompt_ps1_transient=<value>

<value> 是 always、same-dir 和 trim 组成的冒号分隔列表，其语义为：

• 当 prompt_ps1_final 为空且 prompt_ps1_transient 非空时，离开当前命令行时 PS1 指定的提示符会被擦除；
• 若包含 trim，多行 PS1 只保留最后一行、其余擦除；否则整行按 PS1= 重绘；
• 若包含 same-dir 且当前工作目录与上一条命令行的最终目录不同，则忽略该选项（不擦除）。

自定义左右内容需修改 ~/.blerc（或 ~/.config/blesh/init.sh）：

• 左侧：配置 prompt_ps1_final 选项，例如显示 character 模块：

bleopt prompt_ps1_final='$(starship module character)'

• 右侧：配置 prompt_rps1_final 选项，例如显示上一条命令的启动时间：

bleopt prompt_rps1_final='$(starship module time)'

自定义 Pre-Prompt 与 Pre-Execution 命令

Cmd（Clink）

Clink 提供了非常灵活的 pre-prompt / pre-exec 命令 API，与 Starship 配合只需修改 starship.lua：

• 提示符绘制前：定义函数 starship_preprompt_user_func，参数为当前提示符字符串。例如在提示符前打印一枚火箭：

function starship_preprompt_user_func(prompt)
  print("🚀")
end

load(io.popen('starship init cmd'):read("*a"))()

• 命令执行前：定义函数 starship_precmd_user_func，参数为即将执行的命令行字符串。例如打印将要执行的命令：

function starship_precmd_user_func(line)
  print("Executing: "..line)
end

load(io.popen('starship init cmd'):read("*a"))()

Bash

Bash 不像其他 shell 那样有正式的 preexec/precmd 框架，因此完全可定制的钩子较难实现；Starship 提供了有限的介入点：

• 提示符绘制前：定义函数并把函数名赋给 starship_precmd_user_func。例如绘制一枚火箭：

function blastoff(){
    echo "🚀"
}
starship_precmd_user_func="blastoff"

• 命令执行前：可使用 Bash 的 DEBUG trap 机制。但必须在初始化 Starship 之前设置 trap！Starship 可以保存 DEBUG trap 的值，但如果 Starship 启动后 trap 又被其他代码覆盖，部分功能会损坏：

function blastoff(){
    echo "🚀"
}
trap blastoff DEBUG     # 必须在运行 starship 之前 trap DEBUG
set -o functrace
eval $(starship init bash)
set +o functrace

PowerShell

PowerShell 同样没有正式的 preexec/precmd 框架。Starship 允许插入的介入点是创建一个名为 Invoke-Starship-PreCommand 的函数：

function Invoke-Starship-PreCommand {
    $host.ui.Write("🚀")
}

修改终端窗口标题

部分 shell 会自动修改窗口标题（例如反映当前工作目录），Fish 甚至默认就会这么做。Starship 本身不做这件事，但给 bash、zsh、cmd、powershell 添加该功能很简单。

首先在 bash/zsh 中定义窗口标题修改函数（两者写法相同）：

function set_win_title(){
    echo -ne "\033]0; YOUR_WINDOW_TITLE_HERE \007"
}

可以用变量定制标题（$USER、$HOSTNAME、$PWD 是常用选择）。

• 在 bash 中，将该函数设为 Starship 的 precmd 函数：

starship_precmd_user_func="set_win_title"

• 在 zsh 中，将其加入 precmd_functions 数组：

precmd_functions+=(set_win_title)

若效果满意，把上述内容写入 ~/.bashrc 或 ~/.zshrc 使其永久生效。例如想在终端标签页标题中显示当前目录名，可加入：

function set_win_title(){
    echo -ne "\033]0; $(basename "$PWD") \007"
}
starship_precmd_user_func="set_win_title"

对于 Cmd，可以用 starship_preprompt_user_func 修改窗口标题：

function starship_preprompt_user_func(prompt)
  console.settitle(os.getenv('USERNAME').."@"..os.getenv('COMPUTERNAME')..": "..os.getcwd())
end

load(io.popen('starship init cmd'):read("*a"))()

PowerShell 则通过 Invoke-Starship-PreCommand 实现类似效果：

# 编辑 $PROFILE
function Invoke-Starship-PreCommand {
  $host.ui.RawUI.WindowTitle = "$env:USERNAME@$env:COMPUTERNAME`: $pwd `a"
}

Invoke-Expression (&starship init powershell)

启用右提示符（right_format）

部分 shell 支持右提示符（right prompt），它与输入位于同一行、靠右渲染。Starship 用 right_format 选项设置其内容；凡是可以在 format 中使用的模块都可以用在 right_format 中。$all 变量只包含未被 format 或 right_format 显式使用的模块。

注意：右提示符是紧跟输入位置的单行内容；若要在多行提示符中把模块右对齐到输入行的上方，应使用 fill 模块。

right_format 目前支持的 shell 为：elvish、fish、zsh、xonsh、cmd、nushell、bash（其中 bash 需要 Ble.sh 框架 v0.4 或更高版本）。

示例

# ~/.config/starship.toml

# A minimal left prompt
format = """$character"""

# move the rest of the prompt to the right
right_format = """$all"""

产生的提示符形如：

▶                                   starship on  rprompt [!] is 📦 v0.57.0 via 🦀 v1.54.0 took 17s

底层实现上，各 shell 的初始化脚本会调用 starship prompt --right 渲染右侧内容，例如 zsh 在 src/init/starship.zsh 中直接把 RPROMPT 设置为 $('::STARSHIP::' prompt --right ...)；Bash 则在 Ble.sh 存在时设置 bleopt prompt_rps1（见 src/init/starship.bash）；Cmd 的 Clink 脚本则通过 starship_prompt:rightfilter 挂接（src/init/starship.lua）。

使用 zsh（v5.0.5+）时，shell 会给右提示符追加一个默认尾随空格，当配合 Starship 的 $fill 模块使用时可能引起对齐问题。要消除这个间隙，请在 .zshrc 中加入：

ZLE_RPROMPT_INDENT=0

续行提示符（Continuation Prompt）

部分 shell 在正常提示符之外还支持续行提示符：当用户输入了不完整的语句（例如单个左括号或引号）时，提示符位置会渲染续行提示符而不是正常提示符。

Starship 通过 continuation_prompt 选项设置它，默认值为 '∙ '。

注意：continuation_prompt 应设置为不含任何变量的字面字符串。目前仅以下 shell 支持续行提示符：

• bash
• zsh
• PowerShell

示例

# ~/.config/starship.toml

# A continuation prompt that displays two filled-in arrows
continuation_prompt = '▶▶ '

从初始化脚本可以确认各 shell 的接线方式：bash 将其写入 PS2（src/init/starship.bash），zsh 写入 PROMPT2（src/init/starship.zsh），PowerShell 则通过 Set-PSReadLineOption -ContinuationPrompt 调用 starship prompt --continuation（src/init/starship.ps1）。

为 Claude Code 提供状态栏（Statusline）

Starship 支持在 Claude Code（Anthropic 的交互式编程 CLI 工具）中显示自定义状态栏，实时展示当前会话使用的模型、上下文窗口占用与会话花费。

设置步骤

1. 在 Claude Code 中运行 /statusline 并让它配置 Starship，或手动向 .claude/settings.json 加入：

{
  "statusLine": {
    "type": "command",
    "command": "starship statusline claude-code"
  }
}

2. 在 ~/.config/starship.toml 中定制状态栏外观（参见下文"配置"部分）。

工作原理概览

当以 starship statusline claude-code 调用时，Starship 通过 stdin 接收 Claude Code 传入的会话数据（JSON），并使用名为 claude-code 的专用 profile 渲染状态栏。该 profile 包含三个专用模块：

• claude_model：显示当前会话使用的 Claude 模型
• claude_context：以可视化仪表（gauge）显示上下文窗口占用
• claude_cost：显示会话花费与统计信息

默认 profile 格式为：

[profiles]
claude-code = "$claude_model$git_branch$claude_context$claude_cost"

源码层面，命令行入口在 src/main.rs 中定义了 Statusline 子命令，其 provider 取值为 claude-code，未显式指定 --profile 时默认使用 claude-code 这一 profile（src/main.rs）。stdin 的 JSON 负载被反序列化为 src/utils/statusline.rs 中的 ClaudeCodeData 结构（含 model、context_window、cost、effort 等字段），再通过 src/context/mod.rs 的 with_claude_code_data 注入渲染上下文；三个 claude_* 模块在没有该数据时直接返回空，因此在普通终端提示符中不会出现。值得注意的是，反序列化对会话开始阶段的 null 字段做了显式容错（见 src/utils/statusline.rs 的 deserialize_null_default），而类型不匹配的字段仍会报错。

配置

可以在 ~/.config/starship.toml 中修改 claude-code profile 与各个模块来定制状态栏：

# ~/.config/starship.toml

# Customize the claude-code profile
[profiles]
claude-code = "$claude_model$claude_context$claude_cost"

# Configure individual modules
[claude_model]
format = "$symbol$model "
symbol = "🤖 "
style = "bold blue"

[claude_context]
format = "$gauge $percentage "
gauge_width = 10

[claude_cost]
format = "$symbol$cost "
symbol = "💰 "

claude_model 模块

显示当前会话使用的 Claude 模型。

选项

选项	默认值	说明
format	'$symbol$model '	模块格式
symbol	'🤖 '	模型名前显示的符号
style	'bold blue'	模块样式
model_aliases	{}	模型 ID 或显示名到短别名的映射；先按 ID 匹配，再按显示名匹配
disabled	false	禁用 claude_model 模块

变量

变量	示例	说明
model	Claude 3.5 Sonnet	当前模型的显示名
model_id	claude-3-5-sonnet	模型 ID
effort	high	推理 effort 级别（若有上报）
symbol		镜像选项 symbol 的值
style*		镜像选项 style 的值

*：该变量只能作为样式字符串的一部分使用

实现上，别名查找逻辑见 src/modules/claude_model.rs：先用 model.id 查 model_aliases，未命中再用 display_name 查，仍无则回退到原始显示名。

示例

# ~/.config/starship.toml

# Basic customization
[claude_model]
format = "on $symbol$model "
symbol = "🧠 "
style = "bold cyan"

# Using model aliases for vendor-specific model names
# You can alias by model ID or display name
[claude_model.model_aliases]
# Alias by vendor model ID (e.g. AWS Bedrock)
"global.anthropic.claude-sonnet-4-5-20250929-v1:0" = "Sonnet 4.5"
# Alias by display name
"Claude Sonnet 4.5 (Vendor Proxy)" = "Sonnet"

claude_context 模块

以百分比 + 可视化仪表显示上下文窗口占用；样式会根据可配置的阈值自动变化。

选项

选项	默认值	说明
format	'$gauge $percentage '	模块格式
symbol	''	仪表前显示的符号
gauge_width	5	仪表的字符宽度
gauge_full_symbol	'█'	已满段使用的符号
gauge_partial_symbol	'▒'	半满段使用的符号
gauge_empty_symbol	'░'	空段使用的符号
display	见下文	阈值与样式配置
disabled	false	禁用 claude_context 模块

Display

display 是一个对象数组，定义不同占用水平下的阈值与样式。模块会采用最高匹配阈值的样式；若匹配到的配置 hidden 为 true，则整个模块隐藏。默认配置在 src/configs/claude_context.rs 中定义：threshold = 0 时 hidden = true，随后 30% 绿色、60% 黄色、80% 红色。

选项	默认值	说明
threshold	0.0	匹配该配置所需的最小上下文占用百分比
style	bold green	匹配该配置时 style 的取值
hidden	false	匹配该配置时隐藏模块

[[claude_context.display]]
threshold = 0
hidden = true

[[claude_context.display]]
threshold = 30
style = "bold green"

[[claude_context.display]]
threshold = 60
style = "bold yellow"

[[claude_context.display]]
threshold = 80
style = "bold red"

阈值匹配的具体实现在 src/modules/claude_context.rs：将 used_percentage 截断到 0–100 后，筛选出所有 percentage >= threshold 的 display 项并取 threshold 最大者；若该项 hidden 为真则整个模块不渲染。

变量

变量	示例	说明
gauge	██▒░░	上下文占用的可视化表示
percentage	65%	上下文占用百分比
input_tokens	45.2k	会话总输入 token 数
output_tokens	12.3k	会话总输出 token 数
curr_input_tokens	5.1k	最近一次 API 调用的输入 token
curr_output_tokens	1.2k	最近一次 API 调用的输出 token
curr_cache_creation_tokens	1.5k	最近一次 API 调用的缓存创建 token
curr_cache_read_tokens	23.4k	最近一次 API 调用的缓存读取 token
total_tokens	200k	上下文窗口总大小
symbol		镜像选项 symbol 的值
style*		镜像匹配到的 display 阈值的样式

*：该变量只能作为样式字符串的一部分使用

token 数值统一经 src/utils/mod.rs 的 humanize_int 压缩显示（如 1200 → 1.2k、1000000 → 1M），这也是变量示例中 45.2k 这类格式的由来。

示例

仅显示仪表的极简形态

# ~/.config/starship.toml

[claude_context]
format = "$gauge "
gauge_width = 10

详细 token 信息

# ~/.config/starship.toml

[claude_context]
format = "$percentage ($input_tokens in / $output_tokens out) "

自定义仪表符号

# ~/.config/starship.toml

[claude_context]
gauge_full_symbol = "▰"
gauge_partial_symbol = ""
gauge_empty_symbol = "▱"
gauge_width = 10
format = "$gauge "

自定义阈值

# ~/.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"

一个实现细节：仪表的"半满段"仅当余量不小于 0.25 格时才显示（见 src/modules/claude_context.rs 中 partial 判定逻辑），因此 65% 的 5 格宽度会呈现为 ██▒░░ 这类效果。

claude_cost 模块

显示当前 Claude Code 会话的总花费（美元）。与 claude_context 类似，它支持基于阈值的样式切换。

选项

选项	默认值	说明
format	'$symbol(\\$$cost) '	模块格式
symbol	'💰 '	花费前显示的符号
display	见下文	阈值与样式配置
disabled	false	禁用 claude_cost 模块

Display

display 是对象数组，定义花费阈值与样式；模块同样采用最高匹配阈值的样式或按 hidden 隐藏。

选项	默认值	说明
threshold	0.0	匹配该配置所需的最低花费（美元）
style	bold green	匹配该配置时 style 的取值
hidden	false	匹配该配置时隐藏模块

默认配置（定义于 src/configs/claude_cost.rs）：

[[claude_cost.display]]
threshold = 0.0
hidden = true

[[claude_cost.display]]
threshold = 1.0
style = "bold yellow"

[[claude_cost.display]]
threshold = 5.0
style = "bold red"

变量

变量	示例	说明
cost	1.23	会话总花费（美元，保留两位小数）
duration	1m 30s	会话总时长
api_duration	45s	API 调用总时长
lines_added	1.2k	新增代码总行数
lines_removed	500	删除代码总行数
symbol		镜像选项 symbol 的值
style*		镜像匹配到的 display 阈值的样式

*：该变量只能作为样式字符串的一部分使用

示例

# ~/.config/starship.toml

# Cost with code change statistics
[claude_cost]
format = "$symbol$cost (+$lines_added -$lines_removed) "

# Hide module until cost exceeds $0.10
[[claude_cost.display]]
threshold = 0.0
hidden = true

[[claude_cost.display]]
threshold = 0.10
style = "bold yellow"

[[claude_cost.display]]
threshold = 2.0
style = "bold red"

# Show duration information
[claude_cost]
format = "$symbol$cost ($duration) "

样式字符串（Style Strings）

样式字符串是以空白分隔的单词列表，单词大小写不敏感（bold 与 BoLd 视为相同）。每个单词可以是以下之一：

• bold
• italic
• underline
• dimmed
• inverted
• blink
• hidden
• strikethrough
• bg:<color>
• fg:<color>
• <color>
• none

其中 <color> 是颜色说明符（见下）。fg:<color> 与 <color> 目前效果相同，但未来可能会分化。<color> 还可以取 prev_fg 或 prev_bg，在有值时分别求值为前一个元素的前景色或背景色，否则求值为 none。inverted 交换背景色与前景色。字符串中单词的顺序无关紧要。

none 令牌（若非出现在 bg: 说明符中）会覆盖字符串中其他所有令牌，因此例如 fg:red none fg:blue 产生的仍是无任何样式的字符串。bg:none 把背景设为默认色，所以 fg:red bg:none 等价于 red 或 fg:red；bg:green fg:red bg:none 也等价于 fg:red 或 red。未来 none 与其他令牌同时使用可能变为错误。

颜色说明符可以是以下之一：

• 标准终端七色之一：black、red、green、blue、yellow、purple、cyan、white。可加 bright- 前缀获得明亮版本（如 bright-white）
• # 后跟六位十六进制数，即 RGB 颜色十六进制码
• 0–255 之间的数字，即 8-bit ANSI 颜色码

若为前景/背景指定了多个颜色，字符串中最后一个生效。

并非所有样式字符串都能在每种终端中正确显示。已知缺陷包括：

• 许多终端默认禁用 blink
• hidden 在 iTerm 中不受支持
• macOS 自带的 Terminal.app 默认不支持 strikethrough

小结

Starship 的进阶配置体系由三类机制组成：其一是 shell 层面的扩展点——各 shell 初始化脚本（src/init/ 下的 starship.ps1、starship.lua、starship.fish、starship.bash、starship.zsh）预留了 starship_transient_prompt_func、starship_preprompt_user_func、starship_precmd_user_func、Invoke-Starship-TransientFunction、Invoke-Starship-PreCommand 等约定名称的钩子，覆盖 transient prompt、pre/prompt 命令与窗口标题定制；其二是配置层面新增的顶层选项 right_format 与 continuation_prompt，分别解锁右提示符与续行提示符；其三是面向 Claude Code 的 statusline claude-code 子命令，通过 stdin 接收会话 JSON 并以专用 claude-code profile 驱动 claude_model、claude_context、claude_cost 三个模块。需要牢记的前提是：这些钩子函数名与部分行为依赖具体 shell（及 Bash 场景下的 Ble.sh v0.4+），且属于可能随版本演进的接口。