codex-wrapped

codex-wrapped

Your year in code, beautifully visualized.

Credit: Built on top of opencode-wrapped by moddi3 (@moddi3io).

Found this useful? Follow @nummanali for more AI tooling!

Generate a personalized "Spotify Wrapped"-style summary of your Codex usage.

Installation

Quick Start

Run directly without installing:

npx codex-wrapped # or bunx, or yarn/pnpm dlx

Global Install

npm install -g codex-wrapped # or bun/yarn/pnpm

Then run anywhere:

codex-wrapped

Usage Options

Option	Description
--year, -y	Generate wrapped for a specific year
--help, -h	Show help message
--version, -v	Show version number

Features

• Sessions, messages, tokens, projects, and streaks
• GitHub-style activity heatmap
• Top models and providers breakdown
• Usage cost (when available)
• Shareable PNG image
• Inline image display (Ghostty, Kitty, iTerm2, WezTerm, Konsole)
• Auto-copy to clipboard

Terminal Support

The wrapped image displays natively in terminals that support inline images:

Terminal	Protocol	Status
Ghostty	Kitty Graphics	Full support
Kitty	Kitty Graphics	Full support
WezTerm	Kitty + iTerm2	Full support
iTerm2	iTerm2 Inline	Full support
Konsole	Kitty Graphics	Full support
Other terminals	—	Image saved to file only

Output

The tool generates:

• Terminal Summary — Quick stats overview in your terminal
• PNG Image — A beautiful, shareable wrapped card saved to your home directory
• Clipboard — Automatically copies the image to your clipboard

Data Source

Codex Wrapped reads data from your local Codex CLI installation:

~/.codex/ (history.jsonl, sessions, logs)

No data is sent anywhere. Everything is processed locally.

Building

Development

# Run in development mode with hot reload
bun run dev

Production Build

# Build for all platforms
bun run build

Releasing

Releases are automated via semantic-release. Merging PRs with conventional commits to main triggers a release.

Tech Stack

• Runtime: Bun
• Image Generation: Satori + Resvg
• CLI UI: @clack/prompts
• Font: IBM Plex Mono

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Built for the Codex community

Credit: ccusage