Skip to content
/

oh-my-claude (ssenart)

ssenart-oh-my-claude · ssenart/oh-my-claude · ★ 14 · last commit 2026-05-04

Primitive shape
No installable primitives
00

Summary

oh-my-claude (ssenart) — Summary

oh-my-claude by ssenart is entirely different from the other "oh-my-*" frameworks in this batch: it is a status line customization tool for Claude Code, not an orchestration framework. It provides a fully customized terminal status line powered by oh-my-posh, showing 7 display segments: current directory, git status, context window usage percentage, session token count, Pro usage percentages (5h/7d), Pro limit reset timers, and current AI model name. The system works via a statusline.sh bash script called on every Claude Code refresh, reading a JSON cache file for usage data to avoid blocking, and triggering a background update-usage.sh process every 60 seconds. Pro usage tracking reads credentials from macOS Keychain or ~/.claude/.credentials.json. The project is at version 1.9.2 with 14 stars and a bats-core test suite.

Differs from seeds: None of the 11 seeds address terminal status line customization. The only vaguely related seed is agent-os (bash-script-bundle that modifies ~/.claude/ settings), but ssenart's project is purely observability-focused — no commands, skills, agents, hooks that change agent behavior. It is a Tier B observability tool, not an orchestration framework.

01

Overview

oh-my-claude (ssenart) — Overview

Origin

Created by ssenart as a practical tool for monitoring Claude Code usage and context. Version 1.9.2, MIT license, 14 stars. Named after "oh-my-zsh" and "oh-my-posh" — following the shell customization naming convention.

Philosophy

Real-time observability for Claude Code sessions without blocking the terminal:

"Non-blocking background updates with JSON caching" "Performance: Status line render: ~50ms (fast!)" "Usage update: ~2-5s (runs in background, doesn't block)"

What It Monitors

Segment Color Content
Path Orange Current directory
Git Yellow* Branch + staged/modified/ahead/behind status
Context Teal Context window usage %
Code Cyan Session token count (e.g., 14.3M)
Pro Pink 5h usage % and 7d usage %
Reset Purple Time until limits reset (e.g., 5h:2h1min 7d:Thu09:59)
Model Blue Current AI model name

*Git color changes dynamically (clean/dirty/ahead/behind/diverged)

Why "oh-my-claude" Name

The name follows the oh-my-* convention for shell/terminal customization tools (oh-my-zsh for zsh, oh-my-posh for PowerShell/cross-platform prompts). This is a terminal enhancement, not an AI agent framework — the naming is from the shell tool tradition.

02

Architecture

oh-my-claude (ssenart) — Architecture

Distribution

  • Type: Bash script bundle
  • Version: 1.9.2
  • Install: Web installer or local clone
# Web install
curl -s https://raw.githubusercontent.com/ssenart/oh-my-claude/main/install.sh | bash

# Custom directory
curl -s https://raw.githubusercontent.com/ssenart/oh-my-claude/main/install.sh | bash -s -- -d ~/.custom/location

# Local install
git clone https://github.com/ssenart/oh-my-claude.git && bash local-install.sh

Directory Tree

oh-my-claude/
├── src/
│   ├── statusline.sh           # Main status line script (called on every Claude refresh)
│   ├── common.sh               # Shared utility functions
│   ├── update-usage.sh         # Background usage updater (every 60s)
│   ├── fetch-code-usage.sh     # Fetches session token count
│   ├── fetch-pro-usage.sh      # Fetches Pro usage percentages + reset times
│   └── claude-statusline.omp.json  # oh-my-posh theme definition
├── tests/                      # bats-core test suite
│   ├── common.bats
│   ├── statusline.bats
│   ├── fetch-code-usage.bats
│   ├── fetch-pro-usage.bats
│   └── update-usage.bats
├── docs/                       # Documentation
├── install.sh
├── local-install.sh
├── run-tests.sh
├── bump-version.sh
├── VERSION                     # "1.9.2"
└── CHANGELOG.md

Installed Files (in ~/.claude/oh-my-claude/)

  • All scripts from src/
  • .usage_cache — auto-generated JSON cache

Required Dependencies

  • oh-my-posh — prompt rendering engine
  • jq — JSON parsing
  • git — git status
  • npx — (optional for some features)
  • macOS Keychain or ~/.claude/.credentials.json for Pro usage tracking

Data Flow

Claude Code (on every refresh)
  → calls statusline.sh
    → reads .usage_cache (instant, non-blocking)
    → if cache > 60s old: spawn update-usage.sh in background
    → exports env vars for oh-my-posh
    → oh-my-posh renders colored segments
03

Components

oh-my-claude (ssenart) — Components

Scripts (5)

Script Purpose
statusline.sh Main status line — called on every Claude Code refresh; extracts data, reads cache, exports env vars, calls oh-my-posh
common.sh Shared utility functions used by other scripts
update-usage.sh Background updater (every 60s) — calls fetch-code-usage.sh + fetch-pro-usage.sh, writes JSON cache
fetch-code-usage.sh Fetches current session token count from Claude Code
fetch-pro-usage.sh Fetches Pro usage percentages (5h and 7d) and reset times from macOS Keychain or credentials file

Theme File

  • claude-statusline.omp.json — oh-my-posh theme defining segment colors, icons, and layout

Status Segments (7)

Segment Color Data Source
Path Orange cwd from Claude Code JSON input
Git Yellow* Live git commands
Context Teal context_window.current_usage from Claude Code JSON
Code Cyan .usage_cache.code.session_tokens
Pro Pink .usage_cache.pro.five_hour_pct + .usage_cache.pro.seven_day_pct
Reset Purple .usage_cache.pro.five_hour_resets_at + .usage_cache.pro.seven_day_resets_at
Model Blue model.display_name from Claude Code JSON

Hooks

  • None: No Claude Code lifecycle hooks (PreToolUse/PostToolUse/etc.)
  • The statusline.sh is called by Claude Code's built-in status line mechanism, not via hooks.json

Commands / Skills / Agents

  • None: No commands, skills, or subagents
  • Pure observability tool

Tests

  • bats-core test suite covering all 5 scripts
  • run-tests.sh for local test execution

Versioning

  • VERSION file: 1.9.2
  • bump-version.sh script for releases
  • CHANGELOG.md with version history
05

Prompts

oh-my-claude (ssenart) — Prompt Excerpts

This framework contains no AI prompt files — it is a terminal status line tool, not an AI agent framework. The "prompts" it uses are shell scripts and a JSON theme configuration.

Excerpt 1: statusline.sh (src/statusline.sh) — Primary Script

Technique: Shell script consuming Claude Code's JSON input, outputting oh-my-posh environment variables

#!/bin/bash
# Status line command for Claude Code with oh-my-posh integration

source "$(dirname "${BASH_SOURCE[0]}")/common.sh"

# Read JSON input from stdin
input=$(cat)

# Extract values using jq
model=$(echo "$input" | jq -r '.model.display_name')
cwd=$(echo "$input" | jq -r '.workspace.current_dir')

# Calculate context percentage
usage=$(echo "$input" | jq '.context_window.current_usage')
if [ "$usage" != "null" ]; then
    input_tokens=$(echo "$usage" | jq '.input_tokens // 0')
    cache_creation=$(echo "$usage" | jq '.cache_creation_input_tokens // 0')
    cache_read=$(echo "$usage" | jq '.cache_read_input_tokens // 0')
    size=$(echo "$input" | jq '.context_window.context_window_size // 1')
    current=$(awk "BEGIN {print $input_tokens + $cache_creation + $cache_read}")
    if [ "$size" != "0" ]; then
        pct=$(awk "BEGIN {printf \"%.0f\", $current * 100 / $size}")
    else
        pct=0
    fi
    context_pct="${pct}%"
fi

# Fetch usage data with automatic updates from ccusage
cache_file="$script_dir/.usage_cache"
cache_timeout=60
if [ -f "$cache_file" ]; then
    cache_age=$(($(date +%s) - $(get_file_mtime "$cache_file")))
    [ "$cache_age" -ge "$cache_timeout" ] && bash "$update_script" &>/dev/null &
    cache_json=$(cat "$cache_file" 2>/dev/null)
    session_tokens=$(echo "$cache_json" | jq -r '.code.session_tokens // 0')
    pro_five_hour_usage=$(echo "$cache_json" | jq -r '.pro.five_hour_pct // empty')
fi

Analysis: Pure bash pipeline. No AI prompting — this is a data extraction and display script. The pattern is: read Claude Code's JSON stdin → parse fields → read JSON cache → render via oh-my-posh.


Excerpt 2: oh-my-posh Theme (src/claude-statusline.omp.json) — Theme Configuration

Technique: oh-my-posh JSON theme defining segment colors, icons, and layout

Not a prompt file but included here as the "configuration language" of this framework. The claude-statusline.omp.json file defines 7 powerline segments with colors (orange, yellow, teal, cyan, pink, purple, blue) and Nerd Font icons for path, git, context, code tokens, Pro usage, reset timer, and model display.

Note: This is the only framework in the batch where the primary "configuration" is a terminal prompt theme rather than markdown AI instructions or YAML hooks.

09

Uniqueness

oh-my-claude (ssenart) — Uniqueness

Differs from Seeds

None of the 11 seeds address terminal status line customization or Claude Code usage monitoring. The closest analogy is agent-os (bash scripts that modify ~/.claude/settings.json) but agent-os is about behavioral framework setup while ssenart's project is purely observability. This is genuinely unique in the seed catalog and in this batch: it addresses a different problem layer (developer observability) rather than agent behavior modification.

The only vague architectural overlap is with ccmemory (which also installs into ~/.claude/ and reads Claude Code state), but ccmemory is a memory persistence system, not a display tool.

Positioning

  • The only framework in the "oh-my-*" naming cluster that is NOT about multi-agent orchestration
  • Named after terminal customization tools (oh-my-zsh, oh-my-posh) not after the orchestration concept
  • Solves a real pain point: Claude Code Pro users need to track token usage (5h/7d rate limits) in real-time without manual checking
  • 14 stars with bats test suite suggests serious, practical tool despite small scope

What It Customizes

Unlike all other "oh-my-*" frameworks which customize Claude's behavior, ssenart customizes the developer's view of Claude — real-time visibility into context window saturation, session cost, Pro plan limits, and model in use.

Observable Failure Modes

  1. oh-my-posh dependency: If oh-my-posh is not installed, the status line renders as a blank or error — the entire framework fails silently
  2. Credentials file changes: If Anthropic changes .credentials.json format or macOS Keychain structure, fetch-pro-usage.sh silently returns empty values
  3. Background update race: If two update cycles overlap (e.g., slow network), the JSON cache may be partially written, causing jq parse errors in statusline.sh
  4. No Windows support: The installer and scripts use bash/macOS-specific constructs; Windows users have no path
  5. Cache staleness: 60-second TTL means usage data can be significantly stale during heavy use bursts near rate limit boundaries
04

Workflow

oh-my-claude (ssenart) — Workflow

Runtime Data Flow

There is no AI workflow — this is a status line rendering system:

1. Claude Code calls statusline.sh with JSON input on every refresh
2. statusline.sh extracts: model, cwd, context usage
3. statusline.sh reads .usage_cache (instant read, no blocking)
4. If cache > 60 seconds old: spawn update-usage.sh in background (non-blocking)
5. statusline.sh exports environment variables for oh-my-posh
6. oh-my-posh renders the 7-segment colored status line in terminal

Background Update Cycle

update-usage.sh (every 60s, background):
  1. Call fetch-code-usage.sh → session token count
  2. Call fetch-pro-usage.sh → Pro 5h/7d percentages + reset times
  3. Write JSON to ~/.claude/oh-my-claude/.usage_cache

Install Workflow

install.sh:
  1. Check dependencies (oh-my-posh, jq, git, npx)
  2. Download all scripts to ~/.claude/oh-my-claude/
  3. Backup ~/.claude/settings.json
  4. Update settings.json with status line configuration
  5. Make all scripts executable

Customization Workflow

Users edit files in ~/.claude/oh-my-claude/ directly:

  • Colors: edit background in claude-statusline.omp.json
  • Icons: edit template values in theme file
  • Segment order: rearrange segments array
  • Cache frequency: edit cache_timeout=60 in statusline.sh

No Approval Gates

This tool has no AI agent workflow and therefore no approval gates.

06

Memory Context

oh-my-claude (ssenart) — Memory & Context

State Storage

  • Type: File-based JSON cache
  • Location: ~/.claude/oh-my-claude/.usage_cache
  • Format: JSON with timestamps

Cache Structure

{
  "code": {
    "session_tokens": 14300000,
    "timestamp": "..."
  },
  "pro": {
    "five_hour_pct": 90,
    "seven_day_pct": 27,
    "five_hour_resets_at": "2h1min",
    "seven_day_resets_at": "Thu09:59",
    "timestamp": "..."
  }
}

Cache TTL

  • 60 seconds (configurable via cache_timeout=60 in statusline.sh)
  • If cache is stale, background update is triggered; stale data is shown until fresh data arrives

Credential Storage

Pro usage data is read from:

  1. macOS Keychain (preferred)
  2. ~/.claude/.credentials.json (fallback)

Cross-Session Persistence

  • The .usage_cache file persists across Claude Code sessions
  • Session token count is accumulated across the session lifetime
  • Pro usage percentages reflect account-level cumulative usage

No AI Memory

This framework has no AI memory, no vector database, no knowledge graph, and no session handoff mechanism. It is purely a display layer for existing Claude Code telemetry.

07

Orchestration

oh-my-claude (ssenart) — Orchestration

Multi-Agent Pattern

None — this is not an orchestration framework.

There are no agents, no orchestration, no delegation, no task decomposition.

What It Does Instead

The "orchestration" in this project is a data pipeline between:

  1. Claude Code (provides JSON input to statusline.sh)
  2. statusline.sh (orchestrates data extraction and cache reads)
  3. update-usage.sh (background job for usage data)
  4. oh-my-posh (renders the status line)

Execution Model

  • Event-driven: statusline.sh is called by Claude Code on every status line refresh
  • Background daemon-like: update-usage.sh spawned as background process every 60s
  • Non-blocking: Cache reads are instant; updates happen asynchronously

Multi-Model

  • No: No model selection or routing

Isolation

  • None: No worktrees, containers, or sandboxes

Concurrency

  • update-usage.sh runs in background (&>dev/null &) — genuinely concurrent with the main status line render
  • fetch-code-usage.sh and fetch-pro-usage.sh called sequentially within update-usage.sh
08

Ui Cli Surface

oh-my-claude (ssenart) — UI/CLI Surface

The Primary Surface IS the Status Line

This entire framework exists to provide a visual status line. The "UI" is the terminal output rendered by oh-my-posh.

Status Line Segments

[current-dir] [git-branch ±↑↓] [24.7%] [# 14.3M] [5h:90% 7d:27%] [5h:2h1min 7d:Thu09:59] [Sonnet 4.5]

Displayed in powerline style with colored segments and Nerd Font icons.

CLI Interface

# Test the status line
echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"'"$PWD"'"},...}' | bash ~/.claude/oh-my-claude/statusline.sh

# Check version
bash ~/.claude/oh-my-claude/statusline.sh --version

# Update usage data manually
bash ~/.claude/oh-my-claude/update-usage.sh

# View current cache
cat ~/.claude/oh-my-claude/.usage_cache | jq .

# Debug Pro usage fetcher
bash ~/.claude/oh-my-claude/fetch-pro-usage.sh --debug

# Debug code usage fetcher
bash ~/.claude/oh-my-claude/fetch-code-usage.sh --debug

Customization

  • Colors: Edit background values in claude-statusline.omp.json
  • Icons: Edit template values (requires Nerd Font)
  • Segments: Rearrange the segments array
  • Cache interval: Change cache_timeout=60 in statusline.sh

Dependencies Required

  • oh-my-posh: Core rendering engine (must be installed separately)
  • jq: JSON parsing in shell
  • git: Git status commands
  • Nerd Font: For icon display

Tests

Full bats-core test suite:

  • tests/statusline.bats
  • tests/common.bats
  • tests/fetch-code-usage.bats
  • tests/fetch-pro-usage.bats
  • tests/update-usage.bats

Run with bash run-tests.sh

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…