Starship 高级配置实战：Transient Prompt、右侧提示符、Shell 钩子与 Claude Code Statusline 完全指南

Starship 高级配置实战Transient Prompt、右侧提示符、Shell 钩子与 Claude Code Statusline 完全指南【免费下载链接】starship☄️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starshipStarship 的日常定制大多在starship.toml中完成但很多进阶需求——把上一行提示符替换成极简符号、在提示符渲染前后注入自定义逻辑、让提示符内容出现在输入行右侧、甚至把 Starship 用作 Claude Code 的状态栏——都无法仅靠一个配置文件实现。本文基于 Starship 仓库的官方高级配置文档docs/ar-SA/advanced-config/README.md并结合 init 脚本 与 配置模块 源码系统讲解这些高级配置技术的原理、完整操作与注意事项帮助你把 Starship 从好看推进到深度融入工作流。警告本节涉及的高级配置方式属于非核心 API未来版本的 Starship 可能会对其做出变更升级前建议核对最新文档。一、Trans Prompt瞬态提示符1. 什么是 Transient Prompt瞬态提示符Transient Prompt指命令执行后把上一行完整打印的提示符替换为一行极简字符串如仅保留一个❯。这样长提示符含 Git 状态、运行时版本等只在渲染时出现一次历史滚动区则保持干净特别适合提示符信息冗余但并非每刻都需要的场景。Starship 目前支持四个环境的瞬态提示符PowerShell、Cmd依赖 Clink、Fish 和 Bash依赖 Ble.sh 框架。2. PowerShell 中的 Transient Prompt在 Shell 会话中执行Enable-TransientPrompt即可启用写入$PROFILE可持久化执行Disable-TransientPrompt可临时关闭。默认情况下输入行左侧会被替换为。若要自定义例如显示 Starship 的character模块需定义名为Invoke-Starship-TransientFunction的函数function Invoke-Starship-TransientFunction { starship module character } Invoke-Expression (starship init powershell) Enable-TransientPrompt从源码看src/init/starship.ps1 中确实生成了Enable-TransientPrompt/Disable-TransientPrompt两个函数并维护一个$script:TransientPrompt开关当开关为真且下一轮渲染时脚本检测function:Invoke-Starship-TransientFunction是否存在存在则调用其返回值作为替换提示符随后把开关复位——这解释了为什么自定义函数必须用这个精确的命名。3. Cmd 中的 Transient PromptClinkCmd 需要安装 Clink 生态下的 Clink 框架。启用方式是执行一次clink set prompt.transient valuevalue取值always总是替换上一行提示符same_dir仅当工作目录与上一行相同时替换off不替换即关闭瞬态行为。自定义左右两侧显示内容需修改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后将其挂到 Clink 提示符对象的transientfilter方法上starship_transient_rprompt_func则挂到transientrightfilter上。即这两个 Lua 全局函数是 Starship 与 Clink 瞬态机制之间的约定接口。4. Fish 中的 Transient Prompt在会话中执行enable_transience启用写入~/.config/fish/config.fish持久化执行disable_transience临时关闭。注意Fish 中瞬态提示符仅在命令行非空且语法正确时才会打印。默认左侧被替换为加粗绿色的❯。自定义方式为定义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 内置的瞬态支持设置fish_transient_prompt变量否则回退为绑定回车键bind --user \r __starship_transient_execute的自实现方案渲染时脚本通过type -q starship_transient_prompt_func检查用户函数是否存在并把--terminal-width、--status、--pipestatus、--keymap、--cmd-duration、--jobs等上下文参数一并传入因此该函数内调用starship module时能拿到完整的环境变量。5. Bash 中的 Transient PromptBle.shBash 依赖 Ble.sh 框架 v0.4。在~/.bashrc中加入bleopt prompt_ps1_transientvaluevalue是冒号分隔的always、same-dir、trim列表语义为当prompt_ps1_final为空且prompt_ps1_transient非空时离开当前命令行时PS1指定的提示符会被擦除若包含trim字段多行PS1仅保留最后一行其余行擦除不包含trim时命令行会像PS1空一样重绘若包含same-dir且当前工作目录与上一命令行最终目录不同则忽略prompt_ps1_transient。在~/.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 命令这一类钩子让你在提示符绘制前pre-prompt / precmd或命令执行前pre-execution / preexec插入自己的逻辑例如打印日志、改标题、调用通知脚本。1. CmdClinkClink 提供了非常灵活的 API。按需修改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))()2. BashBash 没有像其他 Shell 那样正式的 preexec/precmd 框架因此 Starship 只能提供有限的钩子插入点pre-prompt定义任意函数后把函数名赋值给starship_precmd_user_func。例如在提示符前打印火箭function blastoff(){ echo } starship_precmd_user_funcblastoffpre-execution利用 Bash 的DEBUGtrap 机制。必须在初始化 Starship之前设置 DEBUG trapStarship 会保存启动时的 DEBUG trap 值如果启动后再覆盖它部分功能会失效。正确写法function blastoff(){ echo } trap blastoff DEBUG # Trap DEBUG *before* running starship set -o functrace eval $(starship init bash) set o functrace其中functracefunctopts/extdebug相关用于保证 DEBUG trap 在函数调用上下文中也能触发。3. PowerShellPowerShell 同样缺乏正式的 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_funcset_win_titlezsh加入precmd_functions数组precmd_functions(set_win_title)效果满意后把上述行写入~/.bashrc或~/.zshrc持久化。例如想在终端标签页标题中显示当前目录名function set_win_title(){ echo -ne \033]0; $(basename $PWD) \007 } starship_precmd_user_funcset_win_titleCmd通过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函数实现类似效果编辑$PROFILEfunction Invoke-Starship-PreCommand { $host.ui.RawUI.WindowTitle $env:USERNAME$env:COMPUTERNAME: $pwd a } Invoke-Expression (starship init powershell)四、启用右侧提示符Right Prompt部分 Shell 支持渲染在输入行同一行的右侧提示符。Starship 通过right_format选项设置其内容凡是能用在format里的模块都可以用在right_format里$all变量将只包含未被format或right_format显式使用的模块。注意右侧提示符是跟随输入位置的一行。若要在多行提示符中让模块在输入行上方右对齐请参考 fill 模块。right_format当前支持的 Shellelvish、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 17szsh 对齐修正zshv5.0.5会给右侧提示符追加默认尾随空格在配合$fill模块使用时会产生对齐问题。在.zshrc中加入以下设置即可消除该间隙ZLE_RPROMPT_INDENT0五、继续行提示符Continuation Prompt部分 Shell 支持继续行提示符当用户输入了不完整语句例如只有一个左括号或引号时换行显示的提示符会替代普通提示符。Starship 使用continuation_prompt选项设置它默认值为∙ 可在 src/configs/starship_root.rs 中确认该默认值。注意continuation_prompt应设置为不含任何变量的字面字符串继续行提示符仅在以下 Shell 中可用bash、zsh、PowerShell。示例# ~/.config/starship.toml # A continuation prompt that displays two filled-in arrows continuation_prompt ▶▶ 六、Claude Code StatuslineStarship 支持在 Claude CodeAnthropic 的交互式编码 CLI 工具内显示自定义状态栏实时展示当前会话使用的模型、上下文窗口占用与会话费用。1. 配置步骤在 Claude Code 中执行/statusline并让它配置 Starship或者手动在.claude/settings.json中加入{ statusLine: { type: command, command: starship statusline claude-code } }在~/.config/starship.toml中自定义状态栏外观见下文。2. 工作原理当以starship statusline claude-code调用时Claude Code 通过stdin传入会话 JSON 数据Starship 读取它并使用名为claude-code的专用 profile 渲染状态栏。从源码可以印证这条调用链src/main.rs 中Commands::Statusline分支在 provider 为ClaudeCode且未显式指定 profile 时默认取claude-code作为 profile 名然后进入print::prompt_with_claude_code渲染。而 stdin 的 JSON 由 src/utils/statusline.rs 中的ClaudeCodeData结构反序列化——它包含modelid/display_name、context_window窗口尺寸、总输入/输出 token、已用百分比、当前调用 token 明细、cost总费用、总时长、API 时长、增删行数等字段并且对显式null字段做了与缺失字段相同的默认值处理deserialize_null_default文件内附带的单元测试覆盖了会话刚开始时字段全为null的 payload 场景。该 profile 包含三个专用模块claude_model显示当前使用的 Claude 模型claude_context以可视化仪表显示上下文窗口占用claude_cost显示会话费用与统计。默认 profile 格式[profiles] claude-code $claude_model$git_branch$claude_context$claude_cost3. 整体配置在~/.config/starship.toml中修改claude-codeprofile 与各模块配置# ~/.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 4. claude_model 模块显示当前会话使用的 Claude 模型。选项默认值与 src/configs/claude_model.rs 中的Default实现一致选项默认值说明format$symbol$model 模块的格式字符串symbol 模型名前显示的符号stylebold blue模块的样式model_aliases{}模型 ID 或显示名到短别名的映射先按 ID 查找再按显示名查找disabledfalse禁用claude_model模块变量变量示例说明modelClaude 3.5 Sonnet当前模型的显示名model_idclaude-3-5-sonnet模型 IDsymbol镜像选项symbol的值style*镜像选项style的值*该变量只能作为样式字符串的一部分使用。示例# ~/.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) Sonnet5. claude_context 模块以百分比和可视化仪表显示上下文窗口占用样式根据可配置的阈值自动变化。选项默认值与 src/configs/claude_context.rs 一致选项默认值说明format$gauge $percentage 模块的格式字符串symbol仪表前显示的符号gauge_width5仪表的字符宽度gauge_full_symbol█仪表满格段使用的符号gauge_partial_symbol▒仪表半格段使用的符号gauge_empty_symbol░仪表空段使用的符号display见下文 Display阈值与样式配置数组disabledfalse禁用claude_context模块Display 子项display是对象数组为不同占用水平定义阈值与样式。模块使用最高匹配阈值的样式若匹配项的hidden为true则隐藏模块。选项默认值说明threshold0.0匹配该配置所需的最低上下文占用百分比stylebold green匹配该显示配置时的style值hiddenfalse匹配该配置时隐藏模块[[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变量变量示例说明gauge██▒░░上下文占用的可视化表示percentage65%上下文占用百分比input_tokens45.2k会话累计输入 tokenoutput_tokens12.3k会话累计输出 tokencurr_input_tokens5.1k最近一次 API 调用的输入 tokencurr_output_tokens1.2k最近一次 API 调用的输出 tokencurr_cache_creation_tokens1.5k最近一次 API 调用的缓存创建 tokencurr_cache_read_tokens23.4k最近一次 API 调用的缓存读取 tokentotal_tokens200k上下文窗口总大小symbol镜像选项symbol的值style*镜像匹配阈值对应的样式*该变量只能作为样式字符串的一部分使用。示例仅显示仪表最小化[claude_context] format $gauge gauge_width 10详细 token 信息[claude_context] format $percentage ($input_tokens in / $output_tokens out) 自定义仪表符号[claude_context] gauge_full_symbol ▰ gauge_partial_symbol gauge_empty_symbol ▱ gauge_width 10 format $gauge 自定义阈值[[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 red6. claude_cost 模块以美元显示当前 Claude Code 会话的总费用与claude_context一样支持基于阈值的样式。选项默认值与 src/configs/claude_cost.rs 一致选项默认值说明format$symbol(\\$$cost) 模块的格式字符串symbol 费用前显示的符号display见下文 Display阈值与样式配置数组disabledfalse禁用claude_cost模块Display 子项display数组定义费用阈值与样式模块采用最高匹配阈值的样式匹配项hidden true时隐藏模块。选项默认值说明threshold0.0匹配该配置所需的最低费用USDstylebold green匹配该显示配置时的style值hiddenfalse匹配该配置时隐藏模块默认配置[[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变量变量示例说明cost1.23会话总费用USD保留两位小数duration1m 30s会话总时长api_duration45sAPI 调用总时长lines_added1.2k累计新增代码行数lines_removed500累计删除代码行数symbol镜像选项symbol的值style*镜像匹配阈值对应的样式*该变量只能作为样式字符串的一部分使用。示例# ~/.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 StringsStarship 中所有模块的style选项以及格式串里的样式片段都使用统一的样式字符串语法样式字符串是由空白分隔的词列表不区分大小写bold与BoLd等价。每个词可以是以下之一bolditalicunderlinedimmedinvertedblinkhiddenstrikethroughbg:colorfg:colorcolornone其中color是颜色指示符见下。当前fg:color与color作用相同未来可能变更。color还可取prev_fg或prev_bg分别解析为前一个项的前景色/背景色若可获得否则为none。inverted交换前景与背景色。词在字符串中的顺序无关紧要。none的覆盖语义只要none不是bg:指示符的一部分它就会覆盖字符串中所有其他 token——例如fg:red none fg:blue最终产生无样式的字符串。bg:none把背景设为默认色因此fg:red bg:none等价于red或fg:redbg:green fg:red bg:none也等价于fg:red。未来none与其他 token 连用可能会直接报错。颜色指示符可以是标准终端色之一black、red、green、blue、yellow、purple、cyan、white。可加bright-前缀取亮色版本例如bright-white#后跟六位十六进制数即 RGB 十六进制颜色码0–255 之间的数字即 8-bit ANSI 颜色码。若对前景/背景指定了多个颜色字符串中最后一个生效。终端兼容性怪癖并非每种终端都能正确显示所有样式已知问题包括许多终端默认禁用blinkiTerm 不支持hiddenmacOS 默认 Terminal.app 不支持strikethrough。小结Starship 的高级配置能力可以归纳为四条主线瞬态提示符PowerShell / Clink / Fish / Ble.sh 四种机制均以约定命名的用户函数为扩展点、pre-prompt 与 pre-execution 钩子starship_preprompt_user_func、starship_precmd_user_func、starship_precmd_user_func变量、Invoke-Starship-PreCommand、Bash DEBUG trap、布局增强right_format右提示符与continuation_prompt继续行提示符以及Claude Code statuslinestarship statusline claude-codeclaude-codeprofile 三个 claude_* 模块。这些扩展点与 src/init/ 目录下各 Shell 的 init 脚本及 src/configs/ 下的配置默认值一一对应当你需要超越starship.toml本身时可以对照本文与对应源码逐层深入。【免费下载链接】starship☄️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starship创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考