Your year in the terminal. shellrecap is an interactive TUI that reads your shell history and turns it into insights about how you work, plus a Spotify-Wrapped style recap of your year.
tutorial-voiceover.mp4
- Features
- Installation
- Supported Shells
- Configuration
- Usage
- Themes
- Share Your Recap
- Development
- Troubleshooting
- Contributing
- License
- Shell history analysis for bash, zsh, fish, PowerShell, cmd and Nushell, on Linux, macOS, Windows and WSL
- Tech stack detection
- Productivity metrics
- Work pattern analysis
- Tool usage statistics
- A yearly recap with ASCII animations, a heatmap of every day of your year and optional AI-written slides
- Themes that match your terminal, whether it's dark, pitch black, light or Ubuntu purple
- Share your recap as animated GIFs and pictures in one keypress
Download the latest release for your platform:
| Platform | Architecture | Download Link |
|---|---|---|
| Linux | amd64 | Download |
| Linux | arm64 | Download |
| macOS | amd64 | Download |
| macOS | arm64 | Download |
| Windows | amd64 | Download |
| Windows | arm64 | Download |
Downloads the right binary for your system into the current directory and starts it. It works in WSL and in Git Bash on Windows too.
curl -fsSL https://raw.githubusercontent.com/ksauraj/shellrecap/master/setup.sh | bashDownloads shellrecap.exe into the current folder and starts it. Works in Windows PowerShell and
PowerShell 7.
irm https://raw.githubusercontent.com/ksauraj/shellrecap/master/setup.ps1 | iexwget -qO - https://raw.githubusercontent.com/ksauraj/shellrecap/master/setup.sh | bashgo install github.com/ksauraj/shellrecap/cmd/shellrecap@latest# Linux/macOS
wget https://github.com/ksauraj/shellrecap/releases/latest/download/shellrecap-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
chmod +x shellrecap-*
./shellrecap-*
# Windows PowerShell
Invoke-WebRequest -Uri "https://github.com/ksauraj/shellrecap/releases/latest/download/shellrecap-windows-amd64.exe" -OutFile "shellrecap.exe"shellrecap reads every shell history it finds and shows them together.
| Shell | History it reads | Times saved |
|---|---|---|
| bash | ~/.bash_history |
When HISTTIMEFORMAT is set |
| zsh | ~/.zsh_history, ~/.histfile, $ZDOTDIR/.zsh_history |
With EXTENDED_HISTORY |
| fish | ~/.local/share/fish/fish_history |
Always |
| PowerShell | PSReadLine's history: %APPDATA%\Microsoft\Windows\PowerShell\PSReadLine on Windows, ~/.local/share/powershell/PSReadLine elsewhere |
Never |
| cmd | Clink's history, %LOCALAPPDATA%\clink\clink_history |
With clink set history.time_stamp save |
| Nushell | history.txt in Nushell's config folder |
Never in the default text format |
Times are what the Recap's year, the hours you work and your streaks come from. History without them still counts toward everything else, and the Recap covers all of it when none of your history has times. To start saving them:
# bash: add to ~/.bashrc
export HISTTIMEFORMAT='%F %T '
# zsh: add to ~/.zshrc
setopt EXTENDED_HISTORY:: cmd with Clink
clink set history.time_stamp saveThe Shell Configuration card in the Overview also reads each shell's aliases, environment variables
and plugins: from ~/.bashrc and the like, PowerShell's profile (Set-Alias, one-line functions,
$env: and Import-Module), Nushell's config.nu and env.nu, and Clink's scripts.
On Windows, shellrecap reads:
- PowerShell: Windows PowerShell and PowerShell 7 share their history, including the history from VS Code's PowerShell terminal. The profile is found in your Documents folder, even when OneDrive has moved it.
- cmd: cmd forgets its history when you close it. Clink saves it, and shellrecap reads Clink's history.
- Git Bash, MSYS2 and Cygwin: their bash and zsh history.
- Nushell: from
%APPDATA%\nushell. - WSL: the bash, zsh and fish history of every WSL distro, shown as
bash (WSL)and so on. A distro that isn't running is started to read it, which can take a few seconds.
Run inside WSL, shellrecap reads your Linux history as usual, and also the Windows side's
PowerShell, cmd and Git Bash history, shown as bash (Windows) and so on. Share images are saved
to your Windows Pictures folder, so you can post them from your browser, and the clipboard and
file manager are Windows'.
Commands are matched the way Windows runs them: git.exe, Git and
& "C:\Program Files\Git\cmd\git.exe" all count as git.
The auto theme follows the classic console's colors, like Windows PowerShell's blue. Windows
Terminal doesn't report its background color, so pick a theme with t there if dark doesn't suit
your color scheme. Your choice is remembered.
Requirements:
- Go 1.20 or higher
- A Gemini and/or Groq API key (optional, for the AI-written slides)
# Clone repository
git clone https://github.com/ksauraj/shellrecap.git
cd shellrecap
# Build, optionally compiling in API keys
make build
make build GEMINI_API_KEY=your_gemini_key GROQ_API_KEY=your_groq_key
# Or using go build directly
go build ./cmd/shellrecapKeys compiled in are sealed first, so they aren't stored in the binary as plain text where
strings or a key-scanning bot would find them, and make doesn't print them. To build
with keys without make, seal each one with internal/secret/sealkey, which reads the key from
the environment variable you name:
pkg=github.com/ksauraj/shellrecap/internal/ai
go build -ldflags "-s -w -X $pkg.geminiAPIKey=$(go run ./internal/secret/sealkey GEMINI_API_KEY) \
-X $pkg.groqAPIKey=$(go run ./internal/secret/sealkey GROQ_API_KEY)" ./cmd/shellrecapSealing is obfuscation, not encryption: shellrecap has to read its own keys, so a determined person can still dig them out of a binary. Give keys you ship spending limits or quotas. A key compiled in as plain text is ignored.
The Recap view is computed locally from your history. With an API key it also gets a few AI-written slides (persona, roast, superpower and forecast).
What's sent to the AI is a short summary of counts: your top programs and git subcommands, languages, tools, typos, and when in the day and week you're busiest. Never sent:
- Command lines, arguments, file names, paths or directories
- Your user name, host name, environment variables or the dates you ran things
- Names that could be private even as a program name: anything that looks like a token or
key (
ghp_…,sk-…,AIza…), a host name, a long random string or number, or one of your own scripts (deploy-acme.sh)
Press a in the app to open the Advanced panel, pick Gemini or Groq, press Enter and paste
your key. It's checked, saved and used straight away. Both are free:
Gemini
- You need a Google account. A personal Gmail works; on a work or school account, the admin may have turned AI Studio off.
- Open aistudio.google.com/apikey and sign in. Accept the terms the first time.
- Click Create API key. AI Studio makes a Google Cloud project for it, so you don't need to set up Google Cloud yourself, or billing for the free tier. If you already use Google Cloud, you can pick one of your projects instead.
- Copy the key. It starts with
AIza.
The free tier isn't offered in every country; where it isn't, turn on billing for the project. On the free tier, Google may use what's sent to improve its products.
Groq
- Sign up at console.groq.com with your email, Google or GitHub account. No card is needed for the free plan.
- Open console.groq.com/keys and click Create API Key.
- Copy the key straight away, Groq only shows it once. It starts with
gsk_.
Pasted keys are saved to keys.json next to your config (~/.config/shellrecap on Linux),
readable only by you, and come first: then GEMINI_API_KEY / GROQ_API_KEY, then any key built
into shellrecap. Press d in the panel to remove a saved key.
shellrecap asks Gemini first and falls back to Groq if Gemini fails or has no key. Each provider has a backup model for when its preferred one is overloaded. Both work on their free tiers.
| Provider | Models, in order | Free tier limits (per account) |
|---|---|---|
| Gemini | gemini-3.8-flash, then gemini-3.5-flash-lite |
See Gemini API rate limits |
| Groq | qwen/qwen3.8-27b, then openai/gpt-oss-120b |
30 requests/min, 1,000 requests/day, 8K tokens/min, 200K tokens/day |
| Variable | Description |
|---|---|
GEMINI_API_KEY |
Gemini API key, used when none was pasted in with a |
GROQ_API_KEY |
Groq API key, used when none was pasted in with a |
GEMINI_MODEL |
Gemini model to use when --model isn't given |
GROQ_MODEL |
Groq model to use when --model isn't given |
SHELLRECAP_CACHE_DIR |
Where AI slides are cached, defaults to ~/.cache/shellrecap on Linux |
SHELLRECAP_SHARE_DIR |
Where share images are saved, defaults to a shellrecap folder in Pictures |
SHELLRECAP_CONFIG_DIR |
Where your theme and share choices are saved, defaults to ~/.config/shellrecap on Linux |
SHELLRECAP_THEME |
Color theme, like --theme |
SHELLRECAP_BACKGROUND |
Your terminal's background color, like #300a24, for the auto theme |
AI slides are cached per year and per model, so the AI isn't called on every launch. Cached
slides are reused as long as your stats are unchanged, or for up to a week while your command
count stays within 10% of when they were generated. Press r to re-read your history and
regenerate them. Each AI slide says which model wrote it and how long it took.
shellrecap| Flag | Description |
|---|---|
--provider <name> |
auto (default: Gemini, falling back to Groq), gemini or groq |
--model <model> |
Model to use with --provider, e.g. openai/gpt-oss-20b |
--no-cache |
Always ask the AI for fresh slides |
--theme <name> |
Color theme: auto, dark, black, light or terminal |
--version |
Print the version |
# Compare providers and models
shellrecap --provider groq --no-cache
shellrecap --provider groq --model openai/gpt-oss-20b --no-cache
shellrecap --provider gemini --model gemini-3.5-flash-lite --no-cache| Key | Action |
|---|---|
Tab / Shift+Tab |
Next / previous view |
1-5 |
Jump to a view |
←/→ |
Change slides in Recap, switch views elsewhere |
↑/↓, PgUp/PgDn, mouse |
Scroll the current view |
g / G |
Jump to top / bottom |
Space |
Pause / resume slide autoplay in Recap |
s |
Share your recap |
a |
Advanced: paste your own Gemini or Groq API key |
t |
Switch to the next color theme |
r |
Re-read history and regenerate AI slides |
q |
Quit application |
- Overview: General statistics
- Tech Profile: Technical expertise analysis
- Work Patterns: Productivity patterns
- Tool Usage: Developer tools usage
- Recap: Your year in the terminal: top commands, peak hours, git story, stack, new tools, typos and persona
shellrecap picks its colors to suit your terminal. Press t to try the next theme; your choice is
remembered.
| Theme | What it looks like |
|---|---|
auto |
The default. Reads your terminal's background color and blends every grey from it, so it fits any color scheme, like Ubuntu's purple. Accents are adjusted until they're easy to read. |
dark |
Muted accents on neutral greys |
black |
A little more contrast, for pitch-black terminals and OLED screens |
light |
Deeper accents on pale greys, for light terminals |
terminal |
Your terminal's own 16 colors. Used by auto when the terminal can't show more |
Most terminals report their background color. If yours doesn't and auto looks off, tell it the
color, or pick a theme:
SHELLRECAP_BACKGROUND='#300a24' shellrecap # the auto theme, for this background
shellrecap --theme light # or SHELLRECAP_THEME=lightPress s in the app, or run shellrecap share, and your recap is saved as GIFs and pictures:
| File | What it is | Best for |
|---|---|---|
shellrecap-2026-recap.gif |
Every Recap slide, animated, under 1 MB | X, Discord, Reddit, Slack |
shellrecap-2026-tour.gif |
Every tab, then the Recap slides, animated | X, Discord, Reddit, Slack |
shellrecap-2026-poster.png |
A one-image summary poster | Instagram, LinkedIn, Bluesky |
shellrecap-2026-overview.png and the other tabs |
A picture of each tab | Posts with several pictures |
shellrecap-2026-slide-01.png and on |
A picture of each Recap slide (off by default) | Carousels |
They're saved to a shellrecap folder in your Pictures folder and the poster is copied to your
clipboard. Pick X, Bluesky or LinkedIn in the share menu to open a new post with a caption ready,
then paste or drag in the image. Nothing is uploaded until you post it yourself. The images show
program names, subcommands like git commit and counts, never full command lines or your alias
definitions.
Press c in the share menu to customize what's created:
| Option | Choices |
|---|---|
| Images | Any of the Recap GIF, tour GIF, poster, tab pictures and slide pictures |
| AI slides | Include the AI-written slides or leave them out |
| GIF size | standard (1080x1080 Recap, 1280x960 tour) or small (720x720, 960x720) |
| Picture shape | portrait (1080x1350), story (1080x1920), square (1080x1080) or landscape (1920x1080) |
| Image theme | dark, black (pitch black) or light |
Your choices are saved in ~/.config/shellrecap/config.json on Linux
(%APPDATA%\shellrecap\config.json on Windows) and used by shellrecap share too. Set
SHELLRECAP_CONFIG_DIR to keep them somewhere else.
On Linux, copying to the clipboard needs wl-copy (Wayland) or xclip (X11). Without them, or
over SSH, the images are still saved.
shellrecap share # save the images and print links to post them
shellrecap share --out ~/Desktop # save them somewhere else
shellrecap share --only recap-gif,poster # just these: recap-gif, tour-gif, poster, tabs, slides
shellrecap share --shape story --theme light --gif-size small
shellrecap share --no-ai # leave out the AI-written slides# Clone repository
git clone https://github.com/ksauraj/shellrecap.git
cd shellrecap
# Install dependencies
go mod download
# Run tests
make test
# Build and run
make run- Permission Denied
chmod +x shellrecap- Binary Not Found
export PATH=$PATH:$(pwd)-
Windows: no history found cmd doesn't save history unless Clink is installed. If your PowerShell history is somewhere unusual, check where PSReadLine keeps it with
(Get-PSReadLineOption).HistorySavePath. -
Git Bash: the app doesn't respond to keys Run it as
winpty ./shellrecap.exe, or from Git Bash inside Windows Terminal. The install script does this for you. -
API Key Issues Press
ato paste a key and see which key each provider is using. Or set the keys at runtime, or build with them:
export GEMINI_API_KEY=your_gemini_key GROQ_API_KEY=your_groq_key
make build GEMINI_API_KEY=your_gemini_key GROQ_API_KEY=your_groq_key- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
Ksauraj - GitHub
Project Link: https://github.com/ksauraj/shellrecap