agent-status-tmux
Track AI token usage in tmux status bar
Open source Open in the app JSON README (API)
About
Track AI token usage in tmux status bar
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- jimmyliao
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Stars
- 8
- Last push
- 2026-04-12T17:25:59Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
jimmyliao/agent-status-tmux
README
# agent-status-tmux
Display AI coding agent usage (tokens, cost, duration) in your tmux status bar. Supports **Claude Code** and **Gemini CLI** simultaneously.
<!-- screenshot: replace with your own after install -->
```
◆ claude │ 8% │ 80k │ $3.50 │ 22m │ 5h:12% 7d:32% ◇ gemini │ 1% │ 9k │ ~$0.01 │ 2m
```
## Quick Start
**One-liner** (no git clone needed):
```bash
curl -fsSL tmux.jimmyliao.net/install | bash
```
Or manually:
```bash
git clone https://github.com/jimmyliao/agent-status-tmux.git
cd agent-status-tmux
./scripts/install.sh
```
That's it. Every tmux session (`tmux new -s xxx`) will automatically show AI status. Works whether your status bar is at the top or bottom.
Installs to `~/.agent-status-tmux` by default. Override with `AGENT_STATUS_TMUX_DIR=/your/path`.
## Requirements
- **tmux >= 3.2** (hex color `#[fg=#rrggbb]` support; tested on 3.4–3.6)
- **jq**
- Claude Code and/or Gemini CLI
## Features
- Real-time token usage, cost, and session duration in tmux status-right
- Claude Code: context %, tokens, actual cost, duration, rate limits (5h/7d)
- Gemini CLI: context %, tokens, estimated cost, duration
- Shows both providers simultaneously when both are active
- Process-aware: detects running AI sessions, not just stale cache files
- Gemini CLI Extension with AfterAgent/SessionStart hooks
- Fallback: direct-reads Gemini chat recordings when hooks are unavailable
- Tokyo Night color scheme (customizable)
## Installation Details
```bash
git clone https://github.com/jimmyliao/agent-status-tmux.git
cd agent-status-tmux
./scripts/install.sh
```
The install script will:
1. Create cache directory (`~/.cache/ai-usage/`)
2. Patch `~/.claude/statusline.sh` to write session data (with backup)
3. Update `~/.tmux.conf` to display AI status (with backup)
4. Link the Gemini CLI extension (if Gemini CLI is installed)
5. Reload tmux config
All modifications are idempotent and create timestamped backups.
Once installed, **every new tmux session** (`tmux new -s xxx`) automatically shows AI status — no extra setup needed. The config lives in `~/.tmux.conf` which tmux loads on startup.
> **Note:** You don't need to be inside tmux to run `install.sh`. The cache-writing patches (Claude statusline, Gemini hooks) work independently. You just need tmux running to see the display.
### Gemini CLI Extension
The installer automatically runs `gemini extensions link` to register the extension. If you installed Gemini CLI after running install.sh, link manually:
```bash
gemini extensions link /path/to/agent-status-tmux
```
Verify with:
```bash
gemini extensions list
```
The extension provides `AfterAgent` and `SessionStart` hooks that write token data to `~/.cache/ai-usage/gemini.json` after each turn.
## How It Works
```
Claude Code Gemini CLI
│ │
▼ ▼
statusline.sh AfterAgent hook
(patched, 3 lines) (or fallback reader)
│ │
▼ ▼
~/.cache/ai-usage/ ~/.cache/ai-usage/
claude.json gemini.json
│ │
└──────────┬───────────────────┘
▼
ai-tmux-status.sh
(called by tmux every 5s)
│
▼
tmux status-right
```
## Display Format
| Provider | Fields |
|----------|--------|
| Claude | context % ・ tokens ・ cost ・ duration ・ 5h rate ・ 7d rate |
| Gemini | context % ・ tokens ・ ~estimated cost ・ duration |
Active detection: process alive + cache exists, or cache mtime < 5 minutes after process exits.
## File Structure
```
agent-status-tmux/
├── gemini-extension.json # Gemini CLI extension manifest
├── hooks/
│ └── hooks.json # AfterAgent + SessionStart hooks
├── scripts/
│ ├── after-agent.sh # Gemini hook: extract tokens from transcript
│ ├── session-start.sh # Gemini hook: initialize session
│ ├── gemini-reader.sh # Fallback: read Gemini chat recordings
│ ├── ai-tmux-status.sh # tmux status-right script (core)
│ └── install.sh # One-command installer
├── LICENSE
├── PLAN.md
└── README.md
```
## Uninstall
Restore from backups created during installation:
```bash
# Check for backups
ls ~/.claude/statusline.sh.bak.*
ls ~/.tmux.conf.bak.*
# Restore
cp ~/.claude/statusline.sh.bak.<timestamp> ~/.claude/statusline.sh
cp ~/.tmux.conf.bak.<timestamp> ~/.tmux.conf
tmux source-file ~/.tmux.conf
```
## License
MIT
---
# agent-status-tmux（繁體中文）
在 tmux 狀態列顯示 AI 編程助手的使用量（tokens、費用、時間），同時支援 **Claude Code** 和 **Gemini CLI**。
<!-- 截圖：安裝後替換為你自己的 -->
```
◆ claude │ 8% │ 80k │ $3.50 │ 22m │ 5h:12% 7d:32% ◇ gemini │ 1% │ 9k │ ~$0.01 │ 2m
```
## 快速開始
**一行安裝**（不需要 git clone）：
```bash
curl -fsSL tmux.jimmyliao.net/install | bash
```
或手動：
```bash
git clone https://github.com/jimmyliao/agent-status-tmux.git
cd agent-status-tmux
./scripts/install.sh
```
就這樣。每個 tmux session（`tmux new -s xxx`）都會自動顯示 AI 狀態。不管 status bar 在上方或下方都能用。
預設安裝到 `~/.agent-status-tmux`。可用 `AGENT_STATUS_TMUX_DIR=/your/path` 自訂路徑。
## 需求
- **tmux >= 3.2**（hex 色碼支援；已測試 3.4–3.6）
- **jq**
- Claude Code 和/或 Gemini CLI
## 功能
- 即時顯示 token 用量、費用、Session 時長
- Claude Code：context %、tokens、實際費用、時長、頻率限制（5h/7d）
- Gemini CLI：context %、tokens、估算費用、時長
- 兩個 provider 可同時顯示
- 偵測 process 是否存活，非僅依賴快取時間
- Gemini CLI Extension 提供 AfterAgent/SessionStart hooks
- Fallback 機制：hooks 未安裝時直讀 Gemini chat recording 檔案
## 安裝詳情
```bash
git clone https://github.com/jimmyliao/agent-status-tmux.git
cd agent-status-tmux
./scripts/install.sh
```
安裝腳本會自動：
1. 建立快取目錄 `~/.cache/ai-usage/`
2. 修改 `~/.claude/statusline.sh`（寫入 session 資料，已備份）
3. 更新 `~/.tmux.conf`（顯示 AI 狀態，已備份）
4. 連結 Gemini CLI Extension（若已安裝 Gemini CLI）
5. 重新載入 tmux 設定
安裝後，**每個新的 tmux session**（`tmux new -s xxx`）都會自動顯示 AI 狀態，不需額外設定。
> **備註：** 不需要在 tmux 裡面執行 `install.sh`。快取寫入（Claude statusline、Gemini hooks）獨立運作，只有顯示需要 tmux。
### Gemini CLI Extension
安裝腳本會自動執行 `gemini extensions link`。若之後才安裝 Gemini CLI，手動連結：
```bash
gemini extensions link /path/to/agent-status-tmux
gemini extensions list # 驗證
```
## 授權
MIT