Starship 高级配置完全指南瞬态提示符、Shell 钩子函数、右侧提示符与 Claude Code Statusline【免费下载链接】starship☄️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starshipStarship 是极简、高速且无限可定制的 Shell 提示符框架。当常规的starship.toml配置无法满足需求时你还可以通过各 Shell 自身的机制实现瞬态提示符Transient Prompt、pre-prompt/pre-exec 钩子、终端窗口标题动态化、右侧提示符Right Prompt、续行提示符Continuation Prompt甚至将 Starship 用作 Claude Code 的实时状态栏Statusline。读完本文你将掌握 PowerShell、CmdClink、Fish、BashBle.sh、Zsh 五类 Shell 环境下这些高级特性的完整配置方法并能用样式字符串Style Strings精确定制每一个模块的显示效果。[!WARNING] 本节涉及的配置在 Starship 未来版本中可能发生变更升级 Starship 后建议重新核对本文内容。瞬态提示符Transient Prompt让历史命令区回归简洁瞬态提示符的核心思想是当一条命令执行完毕后把屏幕上已经用过的旧提示符替换成一段更精简的内容从而让终端的历史输出区更干净、更聚焦。它的典型使用场景是命令输入过程中需要完整信息Git 分支、运行环境、耗时等但命令执行结束后这些信息已经不再重要。Starship 在每个 Shell 中通过不同的机制暴露这一能力下面逐一说明。PowerShellEnable-TransientPrompt / Disable-TransientPrompt在 PowerShell 会话中运行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.ps1Enable-TransientPrompt通过Set-PSReadLineKeyHandler -Key Enter绑定回车键在按下回车时先检查命令语法是否合法$parseErrors.Count -eq 0只有语法正确才会触发瞬态替换并重新渲染提示符Disable-TransientPrompt则把回车键恢复为默认的AcceptLine。这意味着语法不完整的命令不会触发瞬态提示符与文档中 Fish 的行为保持一致。CmdClink 的 prompt.transient 与 Lua 钩子在 Windows Cmd 下瞬态提示符由 Clink 提供。只需执行一次clink set prompt.transient value即可配置value取值为取值行为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.lua中的promptfilter与rightfilter会检测这两个函数是否存在存在则用其返回值作为瞬态提示符内容。Fishenable_transience / disable_transienceFish 下运行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 的实现可以看到一个重要的版本差异当 Fish 版本 ≥ 4.1 时enable_transience直接设置全局变量fish_transient_prompt 1使用 Fish 内建的瞬态提示符支持在更早版本中则通过bind --user \r __starship_transient_execute绑定回车键实现。同时starship_transient_prompt_func/starship_transient_rprompt_func在渲染时会被注入--terminal-width、--status、--keymap、--cmd-duration、--jobs等运行时参数见 src/init/starship.fish。Bash通过 Ble.sh 实现Bash 需要依赖 Ble.shv0.4 及以上才能替换已打印的提示符。在~/.bashrc中加入bleopt prompt_ps1_transientvalue即可开启value是一个以冒号分隔的列表可包含always、same-dir、trim三个字段其语义为当prompt_ps1_final为空、且prompt_ps1_transient为非空值时离开当前命令行时PS1指定的提示符会被擦除若value包含trim字段多行PS1只保留最后一行其余行被擦除否则命令行会按PS1被重绘若value包含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 钩子函数钩子函数让你在提示符即将绘制和命令即将执行两个时机插入自定义逻辑例如打印装饰字符、记录命令历史、修改窗口标题等。CmdClinkstarship_preprompt_user_func / starship_precmd_user_funcClink 提供了非常灵活的 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))()从 src/init/starship.lua 的源码可以看到starship_precmd_user_func在clink.onendedit事件中被调用携带当前命令行starship_preprompt_user_func在promptfilter中被调用携带待渲染的提示符这正是 Clink 的编辑结束与提示符过滤两个生命周期点。Bashprecmd 变量与 DEBUG trapBash 没有其他 Shell 那种正式的 preexec/precmd 框架因此无法提供完全自定义的钩子但 Starship 允许你把自己的函数插入提示符渲染流程在提示符绘制前执行自定义函数定义函数后将其名称赋给starship_precmd_user_func。例如function blastoff(){ echo } starship_precmd_user_funcblastoff在命令执行前执行自定义函数使用 Bash 的DEBUGtrap 机制。但必须在初始化 Starship 之前就 trap DEBUG 信号Starship 会保留 DEBUG trap 的值但如果在 Starship 启动之后再覆盖 trap部分功能会损坏。正确写法function blastoff(){ echo } trap blastoff DEBUG # Trap DEBUG *before* running starship set -o functrace eval $(starship init bash) set o functracesrc/init/starship.bash 中保留了starship_precmd_user_func的取值逻辑印证了预先把函数名交给 Starship这一约定。PowerShellInvoke-Starship-PreCommandPowerShell 同样没有正式的 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)效果满意后把这些行加入 Shell 配置文件~/.bashrc或~/.zshrc即可每次启动新 Shell 时自动生效。例如在终端 tab 标题中显示当前目录名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的函数编辑$PROFILE# edit $PROFILE function Invoke-Starship-PreCommand { $host.ui.RawUI.WindowTitle $env:USERNAME$env:COMPUTERNAME: $pwd a } Invoke-Expression (starship init powershell)启用右侧提示符Right Promptright_format部分 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 # 极简左侧提示符 format $character # 把其余模块移到右侧 right_format $all渲染效果类似▶ starship on  rprompt [!] is v0.57.0 via v1.54.0 took 17s使用 zshv5.0.5时Shell 会给右侧提示符自动添加一个默认尾随空格。当使用 Starship 的$fill模块时这可能导致对齐问题。要消除这个间隙在.zshrc中加入ZLE_RPROMPT_INDENT0续行提示符Continuation Prompt部分 Shell 支持与普通提示符配套的续行提示符当用户输入了不完整的语句例如单独的左括号或引号时会用续行提示符替代普通提示符渲染。Starship 通过continuation_prompt选项设置续行提示符默认值为∙ 。两个重要约束continuation_prompt必须设置为不含任何变量的字面字符串续行提示符仅在以下 Shell 中可用bash、zsh、PowerShell。配置示例# ~/.config/starship.toml # 显示两个实心箭头的续行提示符 continuation_prompt ▶▶ Claude Code Statusline把 Starship 变成 AI 编程的实时状态栏Starship 支持在 Claude CodeAnthropic 的交互式 AI 编程 CLI 工具内部渲染自定义状态栏。该状态栏实时展示 Claude 会话信息当前使用的模型、上下文窗口占用、以及会话成本。设置方式要让 Starship 成为 Claude Code 的状态栏二选一在 Claude Code 中运行/statusline并让它配置 Starship手动在.claude/settings.json中加入{ statusLine: { type: command, command: starship statusline claude-code } }然后在~/.config/starship.toml中自定义状态栏外观见下文配置。工作原理与数据来源当以starship statusline claude-code调用时Starship 通过stdin接收 Claude Code 的会话数据并使用名为claude-code的专属 profile 渲染状态栏。默认 profile 格式为[profiles] claude-code $claude_model$git_branch$claude_context$claude_cost该 profile 包含三个专用模块claude_model显示当前使用的 Claude 模型claude_context以可视化仪表显示上下文窗口占用claude_cost显示会话成本与统计信息。从源码看stdin 会话数据的反序列化结构定义在 src/utils/statusline.rsClaudeCodeData包含modelid与display_name、context_windowcontext_window_size、total_input_tokens、total_output_tokens、used_percentage、current_usage其中current_usage细分当次 API 调用的输入/输出/cache 创建/cache 读取 token、costtotal_cost_usd、total_duration_ms、total_api_duration_ms、total_lines_added、total_lines_removed以及effort推理力度级别等字段并有配套单元测试验证各类 payload 的反序列化。statusline子命令本身定义在 src/main.rs支持--profile参数指定渲染所用的 profile。整体配置入口你可以通过修改claude-codeprofile 及各个模块的配置来定制状态栏# ~/.config/starship.toml # 自定义 claude-code profile [profiles] claude-code $claude_model$claude_context$claude_cost # 配置各模块 [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_model显示当前会话使用的 Claude 模型。选项选项默认值说明format$symbol$model 模块的格式symbol 模型名称前显示的符号stylebold blue模块样式model_aliases{}模型 ID 或显示名称到短别名的映射优先匹配 ID其次匹配显示名称disabledfalse禁用claude_model模块变量变量示例说明modelClaude 3.5 Sonnet当前模型的显示名称model_idclaude-3-5-sonnet模型 IDefforthigh推理力度级别若会话上报symbol与选项symbol一致style*与选项style一致*: 该变量只能用作 style 字符串的一部分。示例# ~/.config/starship.toml # 基础定制 [claude_model] format on $symbol$model symbol style bold cyan # 为厂商专有模型名设置别名 # 可以按模型 ID 或显示名称设置别名 [claude_model.model_aliases] # 按厂商模型 ID 设置别名例如 AWS Bedrock global.anthropic.claude-sonnet-4-5-20250929-v1:0 Sonnet 4.5 # 按显示名称设置别名 Claude Sonnet 4.5 (Vendor Proxy) Sonnet以上默认值可在 src/configs/claude_model.rs 中确认model_aliases在配置结构中使用IndexMapString, str存储保证别名顺序稳定。claude_context 模块claude_context以百分比和可视化仪表显示上下文窗口占用样式会根据可配置的阈值自动切换。选项选项默认值说明format$gauge $percentage 模块的格式symbol仪表前显示的符号gauge_width5仪表宽度字符数gauge_full_symbol█仪表已填充段使用的符号gauge_partial_symbol▒仪表部分填充段使用的符号gauge_empty_symbol░仪表空段使用的符号display见下文阈值与样式配置disabledfalse禁用claude_context模块以上默认值gauge_width: 5、gauge_full_symbol: █及默认阈值 0/30/60/80可在 src/configs/claude_context.rs 中核对。Display 子配置display是一个对象数组定义不同占用级别对应的阈值与样式。模块会采用匹配到的最高阈值对应的样式若匹配项hidden为true则隐藏模块。选项默认值说明threshold0.0匹配该配置所需的最低上下文窗口占用百分比stylebold green命中该配置时的style值hiddenfalse命中该配置时隐藏此模块默认的 display 配置[[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会话累计输入 token 数output_tokens12.3k会话累计输出 token 数curr_input_tokens5.1k最近一次 API 调用的输入 token 数curr_output_tokens1.2k最近一次 API 调用的输出 token 数curr_cache_creation_tokens1.5k最近一次 API 调用的 cache 创建 token 数curr_cache_read_tokens23.4k最近一次 API 调用的 cache 读取 token 数total_tokens200k上下文窗口总大小symbol与选项symbol一致style*镜像匹配到的 display 阈值对应的样式*: 该变量只能用作 style 字符串的一部分。示例仅仪表的最小化显示# ~/.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 redclaude_cost 模块claude_cost以美元显示当前 Claude Code 会话的总成本。与claude_context类似它也支持基于阈值的样式切换。选项选项默认值说明format$symbol(\$$cost) 模块的格式symbol 成本前显示的符号display见下文阈值与样式配置disabledfalse禁用claude_cost模块默认值同样在 src/configs/claude_cost.rs 中有对应实现format: $symbol(\$$cost) 、symbol: 、默认 display 阈值 0.0/1.0/5.0。Display 子配置display是一个对象数组定义成本阈值与样式。模块采用匹配到的最高阈值对应的样式若匹配项hidden为true则隐藏模块。选项默认值说明threshold0.0匹配该配置所需的最低成本美元stylebold 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会话总成本美元保留两位小数duration1m 30s会话总时长api_duration45sAPI 调用总时长lines_added1.2k新增代码行数lines_removed500删除代码行数symbol与选项symbol一致style*镜像匹配到的 display 阈值对应的样式*: 该变量只能用作 style 字符串的一部分。示例# ~/.config/starship.toml # 成本与代码变更统计 [claude_cost] format $symbol$cost ($lines_added -$lines_removed) # 成本超过 $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 # 显示时长信息 [claude_cost] format $symbol$cost ($duration) 样式字符串Style Strings完全语法样式字符串是一组用空白分隔的单词单词不区分大小写bold与BoLd被视为同一字符串。每个单词可以是bolditalicunderlinedimmedinvertedblinkhiddenstrikethroughbg:colorfg:colorcolornone其中color是颜色说明符见下文。fg:color与color目前行为相同但未来可能改变。color还可以设为prev_fg或prev_bg分别表示前一个元素的前景色或背景色若可用否则为none。inverted会交换背景色与前景色。字符串中单词的顺序无关紧要。none的语义需要特别注意只要none不是bg:说明符的一部分它就会覆盖字符串中所有其他标记。例如fg:red none fg:blue仍然会生成无任何样式的字符串。bg:none把背景设为默认色因此fg:red bg:none等价于red或fg:redbg:green fg:red bg:none同样等价于fg:red或red。未来版本中none与其他标记混用可能变成错误用法。颜色说明符可以是以下三种之一标准终端颜色之一black、red、green、blue、yellow、purple、cyan、white。可加上bright-前缀得到高亮版本例如bright-white。以#开头的六位十六进制数表示 RGB 颜色十六进制码例如#ff0000。0-255 之间的数字表示 8-bit ANSI 颜色码。如果前景/背景同时指定了多个颜色字符串中最后一个颜色优先。已知的终端兼容性问题许多终端默认禁用blink支持iTerm 不支持hiddenmacOS 默认的 Terminal.app 不支持strikethrough。因此并非所有样式字符串都能在所有终端正确显示跨终端使用时建议测试验证。总结与适用范围本文覆盖了 Starship 在starship.toml之外的六大高级能力按 Shell 归纳如下能力PowerShellCmd (Clink)FishBashZsh瞬态提示符Enable-TransientPromptclink set prompt.transientenable_transienceBle.shprompt_ps1_transient—使用其他方案pre-prompt 钩子Invoke-Starship-PreCommandstarship_preprompt_user_func—starship_precmd_user_funcprecmd_functionspre-exec 钩子Invoke-Starship-PreCommandstarship_precmd_user_func—DEBUGtrap须先于 init—右侧提示符—right_formatright_formatBle.sh right_formatright_formatZLE_RPROMPT_INDENT0续行提示符continuation_prompt——continuation_promptcontinuation_promptClaude Code Statusline三个模块通用claude_model/claude_context/claude_cost通过.claude/settings.json接入所有高级配置均以~/.config/starship.toml为最终落点相关模块的配置结构定义可继续查阅 src/configs/claude_model.rs、src/configs/claude_context.rs、src/configs/claude_cost.rs 与 src/utils/statusline.rs。由于本节配置在未来版本中可能调整升级 Starship 后建议回归验证。【免费下载链接】starship☄️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!项目地址: https://gitcode.com/GitHub_Trending/st/starship创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考