Cobalt Spark

Cobalt Spark is a compact Zsh theme 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.

Installation

Choose the setup that matches your Zsh environment:

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

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. The live watcher reads its settings when it starts.

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

• COBALT_SPARK_THEME_GIT_HIDDEN_PREFIXES lists branch prefixes collapsed to … in the Git segment when followed by /. The defaults are feature, feat, bugfix, chore, docs, refactor, and fix. Assign an empty array to show full branch names.
• COBALT_SPARK_THEME_PARENT_CAP controls how many leading characters of the parent directory name are retained when it is abbreviated. Set it to 0 to hide the parent directory entirely.
• Set COBALT_SPARK_THEME_PROMPT_SIGN to use a different prompt anchor, for example COBALT_SPARK_THEME_PROMPT_SIGN=' % '. You can also make the prompt multiline by embedding 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.