Momentum in your shell prompt

Open a terminal. There’s your project directory, your git branch, maybe the time. What isn’t there: any signal about whether you’re in flow or whether this project has been sitting cold for two weeks.

kgp adds that signal. One character, a space, and a relative time. That’s it.

> 2m ago    # hot - you were just here
~ 4h ago    # warm - momentum is fading
* 12d ago   # cold - you've been away
! blocked   # something is in your way

It shows up in your prompt every time you run a command. You don’t have to ask. You don’t have to remember. You glance left and you know.

What the symbols mean

The three states map directly to how momentum actually decays:

Hot (>) means you saved a checkpoint less than 30 minutes ago. You’re in it. The work is fresh. If you left and came back, you won’t need to reconstruct anything.

Warm (~) means 30 minutes to 8 hours. You’ve stepped away but the context is still there. A few seconds of reading the last checkpoint and you’re back in flow.

Cold (*) means more than 8 hours. This is the state that kills side projects. You see it and you know this one needs real re-entry work, not just a glance at the last file you edited.

Blocked (! blocked) is special. If your last checkpoint flagged a blocker, that takes over the entire display. The time doesn’t matter. What matters is that something is in your way and you left yourself a note about it.

The thresholds are not arbitrary. Hot means “still in the session, basically.” Warm means “same day, manageable.” Cold means “the next time you open this, plan for a slow start.” Eight hours is roughly the end of a workday.

How it works

kgp is a Rust binary with no external dependencies beyond the shared KeepGoing crate. When you run a command in your terminal, it executes in milliseconds:

1. Walk up from the current directory to find .git/
2. Open .keepgoing/keepgoing.db read-only
3. Fetch the latest checkpoint record
4. Compute elapsed time and render a line
5. Print the result (or nothing if you’re not in a KeepGoing project)

The time math is done without pulling in any date/time crates. It implements ISO 8601 parsing from scratch using Howard Hinnant’s civil-from-days algorithm. The dependency list stays clean. The binary stays small.

The read is always read-only. kgp never writes anything. It can’t block your prompt, corrupt your database, or fail in a way that breaks your shell. If anything goes wrong - missing database, no checkpoints yet, parsing error - it exits 0 and prints nothing.

Shell integration

For Zsh, prepend it to PS1:

PS1='$(kgp) '$PS1

After a checkpoint save, your prompt looks like:

> 0m ago ~/projects/myapp main$

For Starship, add a custom segment to ~/.config/starship.toml:

[custom.keepgoing]
command = "kgp"
when = "true"
format = "[$output]($style) "
style = "dimmed white"

Both integrations call the binary on every command. The startup time is fast enough that you won’t notice it. Rust binary startup on a modern machine is measured in single-digit milliseconds.

The relationship to checkpoints

kgp only has data to show if you’re saving checkpoints. A checkpoint is the record of what you were doing, what comes next, and whether anything is blocking you. When you work with Claude Code and KeepGoing, checkpoints are saved automatically whenever you ask Claude to summarize progress.

The shell prompt is the ambient display for that data. The momentum dashboard inside Claude Code sessions is the detailed view. They read from the same source and reflect the same state.

If your prompt shows * 3d ago, that’s the same signal you’d see in the Claude Code status line. The difference is that the shell prompt is always visible, in every terminal, whether you have a Claude session open or not.

Getting set up

If you have KeepGoing installed:

keepgoing setup

This sets up Claude Code hooks, initializes the database structure, and installs the binaries. The kgp binary lands in ~/.keepgoing/bin/ and needs to be on your PATH.

If you don’t have KeepGoing yet:

curl -fsSL https://keepgoing.dev/install.sh | bash -s -- claude

After installation, add the shell integration for whichever prompt you use and open a project. Save your first checkpoint and watch the indicator go from absent to > 0m ago.

---

The best developer tools don’t ask for your attention. They make information visible and let you decide what to do with it. kgp is three characters. Most of the time you won’t consciously read it. But when you open a terminal on a project you haven’t touched in two weeks and it says * 14d ago, you’ll know exactly what you’re walking into.