Cobalt Spark

Cobalt Spark is a compact Zsh theme with live Git updates, designed for everyday work. Restrained colors keep essential context visible without competing with command output, while a prominent lightning anchor makes command lines easy to find when scanning the terminal.

A fuller static preview is also available and can be compared with the same terminal session rendered using robbyrussell.

Overview

• Live Git updates: the Git segment refreshes automatically when an IDE, coding agent, or another terminal changes the repository—without pressing Enter.
• Compact Git segment with configurable branch prefix shortening, working-tree dirtiness, operations in progress, upstream divergence, commits unique to the current branch, and an early notice about remote changes.
• Compact working-directory display with the current directory and an abbreviated parent.
• A hotkey to quickly copy the current working directory.
• Command and pipeline status indication.
• Python virtual environments, nested shell levels, and background jobs when present.
• Informative continuation prompts for incomplete multiline commands.
• Supports Oh My Zsh, Zsh plugin managers, and direct installation.

Try it

Try Cobalt Spark without changing your configuration. Run from Zsh:

source <(curl -fsSL https://raw.githubusercontent.com/azhuchkov/cobalt-spark/main/demo/try.zsh)

The script starts an isolated temporary session. Using source lets it pick up supported plugins from your current Zsh session automatically. No plugins are installed. Type exit to return and remove the temporary copy. Requires Zsh, Git, and curl.

Use a dark terminal color scheme. To match the screenshots or fix missing symbols, see Terminal setup. Install fswatch to try live Git updates.

Installation

Note

To enable Live Git updates, install fswatch with your package manager. You can skip this step if you don’t need automatic updates while the prompt is idle.

Choose the setup that matches your Zsh environment. After editing ~/.zshrc, open a new Zsh session to activate the theme.

Oh My Zsh

Clone the repository into the Oh My Zsh custom themes directory:

git clone https://github.com/azhuchkov/cobalt-spark.git \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/cobalt-spark"

Then select the theme in ~/.zshrc:

ZSH_THEME="cobalt-spark/cobalt-spark"

Zsh plugin managers

The theme also follows the Zsh Plugin Standard, so it can be loaded using popular plugin managers like Zinit, Antigen, or zplug.

This installation method is newer and has received less real-world testing than the Oh My Zsh integration.

Add azhuchkov/cobalt-spark using your plugin manager's installation syntax. Managers that support standard Zsh plugin conventions should automatically load cobalt-spark.plugin.zsh.

For Zinit, add this to ~/.zshrc:

zinit light azhuchkov/cobalt-spark

For Antigen, add this before antigen apply in ~/.zshrc:

antigen bundle azhuchkov/cobalt-spark --branch=main

For zplug, add this before zplug check and zplug load in ~/.zshrc:

zplug "azhuchkov/cobalt-spark"

Direct installation

Clone the repository anywhere convenient:

git clone https://github.com/azhuchkov/cobalt-spark.git ~/.cobalt-spark

Then source the standard plugin entry point from ~/.zshrc:

source ~/.cobalt-spark/cobalt-spark.plugin.zsh

Updating

To update Cobalt Spark to the latest version, follow the instructions for your installation method.

Oh My Zsh:

git -C "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/cobalt-spark" pull --ff-only

Zsh plugin managers: update azhuchkov/cobalt-spark using your plugin manager's update command.

Direct installation:

git -C ~/.cobalt-spark pull --ff-only

If you cloned the repository elsewhere, adjust the path accordingly.

After updating, open a new terminal tab or window to load the updated theme.

Reading the prompt

Command status

The leading • shows the previous command's status:

• Gray — the command succeeded.
• Red — the command returned a non-zero exit status.
• Yellow — the last pipeline stage succeeded, but an earlier stage failed (excluding SIGPIPE).

Git indicators

The Git segment shows the current branch, or @ followed by a tag or commit hash when HEAD is detached.

• * — uncommitted changes; red if there are unresolved conflicts.
• ! — a Git operation is in progress, such as a merge or rebase; red if there are unresolved conflicts.
• ↑ / ↑3 — one / three commits ahead of upstream.
• ↓ — behind upstream; may appear together with ↑.
• ⇣ — incoming commits detected by Git prefetch, before an explicit fetch.
• ⇡ — commits unique to this branch, absent from other branches and tags. Shown when no upstream is configured and the repository has a remote.
• …/ — a shortened branch prefix, such as feature/.

Indicators follow this priority: Git operation → uncommitted changes → commit divergence. For example, editing a file replaces the arrows with *; they return when the working tree is clean.

Other context

• [2] before the directory — nested shell level.
• & on the right — background jobs; yellow if any are suspended.
• [.env] on the right — active Python virtual environment.
• ⚡ — the start of your command.

Configuration

Cobalt Spark works without additional configuration. The settings below are shell variables; put persistent values in ~/.zshrc before loading the theme. For Oh My Zsh, place them before source $ZSH/oh-my-zsh.sh; for plugin managers or direct installation, place them before the command that loads Cobalt Spark. The live watcher reads its settings when it starts.

For example, an Oh My Zsh configuration could include:

ZSH_THEME="cobalt-spark/cobalt-spark"
COBALT_SPARK_THEME_GIT_HIDDEN_PREFIXES=(feature feat fix)
COBALT_SPARK_THEME_PARENT_CAP=3
COBALT_SPARK_THEME_LIVE_GIT_LATENCY=1.5

# Keep your existing Oh My Zsh load command after the settings.
source "$ZSH/oh-my-zsh.sh"

Live Git updates

When fswatch is installed, Cobalt Spark watches the current repository and updates the Git segment while the prompt is idle. Without fswatch, the Git segment still works but updates only when the prompt is rendered again.

The watcher latency defaults to 500 milliseconds. To change it, set a value in seconds like this: COBALT_SPARK_THEME_LIVE_GIT_LATENCY=1.5.

To turn off live Git updates entirely, set COBALT_SPARK_THEME_LIVE_GIT_OFF to a non-empty value. A running watcher stops the next time the prompt is rendered.

Python virtual environments

In standalone setups, Cobalt Spark detects the active Python environment automatically.

When using Oh My Zsh, enable its virtualenv plugin by adding it to the existing plugin list in ~/.zshrc, for example:

plugins=(git virtualenv)

Quickly copy the current directory

Optionally, you can bind a hotkey to quickly copy the current working directory:

# Press Ctrl+X, then Ctrl+P to copy the CWD
bindkey -M emacs '^X^P' cobalt-spark-copy-cwd

For best compatibility with other plugins, place this binding near the end of ~/.zshrc.

Theme options

Option	Default	Effect
COBALT_SPARK_THEME_GIT_HIDDEN_PREFIXES	(feature feat bugfix chore docs refactor fix)	Branch prefixes collapsed to … when followed by /. Set to () to show full branch names.
COBALT_SPARK_THEME_PARENT_CAP	5	Leading characters retained in the abbreviated parent directory. Set to 0 to hide the parent.
COBALT_SPARK_THEME_PROMPT_SIGN	Space + ⚡	Prompt anchor; supports embedded line breaks.

For a different prompt anchor, set COBALT_SPARK_THEME_PROMPT_SIGN=' % '. To make the prompt multiline, embed a line break: COBALT_SPARK_THEME_PROMPT_SIGN=$'\n⚡'.

Terminal setup

Color scheme

Use a dark terminal color scheme, such as Tokyo Night (used in the screenshots) or Catppuccin Macchiato. For a quieter, more subdued look during long terminal sessions, One Dark is a good choice.

Font

Use a font that includes the lightning bolt (⚡). To match the screenshots, use JetBrains Mono Nerd Font Complete v2.3.3: newer versions have a different lightning glyph.

Which font files should I install?

The archive contains several variants and styles:

• NL — no ligatures. Choose this variant if you prefer characters such as != and -> to remain visually separate, regardless of your terminal's ligature settings.
• An additional Mono after Nerd Font Complete — fits icons into a single character cell, making some icons smaller. This is separate from Mono in the base name JetBrains Mono. The variant without this additional Mono allows larger icons and is used in the screenshots.
• Regular, Bold, Italic, and Bold Italic — different styles of the same variant; install the styles you need.

The NL and icon-width choices are independent. Choose your preferred combination, install its font files, and select it in your terminal settings.

Tips & Tricks

Command correction

To have Zsh suggest corrections for misspelled command names, enable CORRECT:

setopt CORRECT

Command timing

REPORTTIME makes Zsh automatically show a timing summary after a command uses more CPU time than the given number of seconds. CPU time counts active work, not time spent waiting for input or the network. TIMEFMT controls what the summary looks like; this example shows elapsed time, CPU usage, and the command. It also controls the output of Zsh's time keyword:

REPORTTIME=3
TIMEFMT="${(%):-%F{8\}}◷ ${(%):-%F{14\}}%*Es ${(%):-%F{8\}}· ${(%):-%F{11\}}%P${(%):-%F{8\}} CPU · ${(%):-%f}%J"

Command timestamps

If you want to know when commands were run rather than how long they took, some terminal emulators can provide this information without adding it to the prompt. For example, iTerm2 can show timestamps for terminal lines with View → Show Timestamps.

Many terminal emulators also support shell integration that tracks command boundaries and can expose related metadata. Available features vary by terminal.

Git prefetch

To let the prompt detect upstream changes before an explicit fetch, enable Git's built-in maintenance. Run this command from within the repository:

git maintenance start

Git will periodically prefetch changes and perform other housekeeping in the background. Prefetched changes are stored separately, so remote-tracking branches are not updated until you run git fetch. The prompt uses this data to provide an early warning that your branch is behind its upstream.

Troubleshooting

• If prompt symbols do not render correctly, make sure you have configured a suitable font in your terminal emulator; see Terminal setup. You can also replace the prompt anchor using theme options.
• If iTerm2 adds a triangle beside each prompt, turn off Show mark indicators under Settings → Profiles → Terminal so it does not interfere with the theme's prompt.
• If the prompt shows an unexpectedly high shell level inside tmux, add set-environment -gu SHLVL to ~/.tmux.conf. For an already running tmux server, run tmux set-environment -gu SHLVL; the fix applies to new panes and windows.
• When using Oh My Zsh, if the prompt marks a repository dirty while git status is clean, Oh My Zsh may be counting a commit change in an ignored submodule. Set GIT_STATUS_IGNORE_SUBMODULES=git in the current session or a Zsh startup file to make it follow Git's policy.
• If the Git segment is slow in a large repository, learn about Git's core.untrackedCache and built-in core.fsmonitor.
• On BSD systems, the fswatch kqueue monitor uses one file descriptor per watched file. If live Git updates appear incomplete in a large repository, check the current soft and hard limits with ulimit -Sn and ulimit -Hn. If appropriate for your system, set ulimit -Sn hard in your Zsh startup file, then restart the shell or reload the theme.
• If you see zsh-syntax-highlighting: unhandled ZLE widget 'cobalt-spark-copy-cwd', move the binding of the hotkey toward the end of ~/.zshrc, after all plugins are loaded; the warning itself is harmless.
• If upstream changes take longer than expected to appear in the prompt, note that Git maintenance normally prefetches them hourly. Also Git versions before 2.45.3 may stop processing repositories after the first maintenance failure, so upgrading Git is recommended.

License

Licensed under the MIT License.