{"id":49537784,"url":"https://github.com/skyline69/agent-stats-fish","last_synced_at":"2026-05-02T12:31:06.481Z","repository":{"id":345975280,"uuid":"1188074340","full_name":"skyline69/agent-stats-fish","owner":"skyline69","description":"Fish shell plugin that shows Claude Code, Codex, and Gemini CLI usage stats in your prompt","archived":false,"fork":false,"pushed_at":"2026-03-22T00:34:57.000Z","size":465,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T06:33:26.971Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skyline69.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-21T15:29:07.000Z","updated_at":"2026-03-22T00:35:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/skyline69/agent-stats-fish","commit_stats":null,"previous_names":["skyline69/agent-stats-fish"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/skyline69/agent-stats-fish","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skyline69%2Fagent-stats-fish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skyline69%2Fagent-stats-fish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skyline69%2Fagent-stats-fish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skyline69%2Fagent-stats-fish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skyline69","download_url":"https://codeload.github.com/skyline69/agent-stats-fish/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skyline69%2Fagent-stats-fish/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32534964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-02T12:31:05.992Z","updated_at":"2026-05-02T12:31:06.466Z","avatar_url":"https://github.com/skyline69.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-stats\n\nA [Fish shell](https://fishshell.com) plugin that displays usage statistics for AI coding agents. Tracks Claude Code, OpenAI Codex, and Google Gemini CLI in your terminal -- as a right-prompt indicator, a compact summary, or a detailed daily breakdown.\n\n![demo](images/demo.png)\n\n## Features\n\n- **Right-prompt integration** -- live usage stats in your prompt (rate limit %, token counts)\n- **Three display modes** -- prompt (minimal), compact (one-line), and detailed (full breakdown)\n- **Multi-provider** -- enable any combination of Claude, Codex, and Gemini\n- **Background caching** -- non-blocking data refresh with configurable TTL\n- **Color-coded usage** -- green/yellow/red thresholds for rate limits\n\n## Requirements\n\n- [Fish shell](https://fishshell.com) 3.1+\n- [jq](https://jqlang.github.io/jq/) (JSON processor)\n- [Fisher](https://github.com/jorgebucaran/fisher) (plugin manager)\n\n## Installation\n\n```fish\nfisher install skyline69/agent-stats-fish\n```\n\nOr install from a local clone:\n\n```fish\nfisher install .\n```\n\n## Quick Start\n\nEnable the providers you use:\n\n```fish\nagent-stats enable claude\nagent-stats enable codex\nagent-stats enable gemini\n```\n\nThen run `agent-stats` for a compact summary, or `agent-stats -d` for a detailed breakdown.\n\nThe right prompt updates automatically with live stats for all enabled providers.\n\n## Usage\n\n```\nagent-stats                  # Compact stats for all enabled providers\nagent-stats -d, --detailed   # Detailed stats with daily breakdown and model usage\nagent-stats enable \u003cprovider\u003e # Enable a provider (claude, codex, gemini)\nagent-stats disable \u003cprovider\u003e # Disable a provider\nagent-stats providers        # List enabled providers\nagent-stats refresh          # Clear cache and re-fetch\nagent-stats cost             # Show estimated API costs for all providers\nagent-stats cost \u003cprovider\u003e  # Show costs for a specific provider\nagent-stats -h, --help       # Show help\n```\n\n## Display Modes\n\n### Right Prompt\n\nA minimal indicator in your right prompt showing usage at a glance:\n\n```\n 7%  ⬡ 0%  󰫣 8.1K\n```\n\n- Claude and Codex show rate limit percentages (color-coded by severity)\n- Gemini shows today's token count\n\n### Compact\n\nOne line per provider with progress bars and key metrics:\n\n```\nClaude (Max) ██░░░░░░░░ 7%/5h\nCodex (Premium) ░░░░░░░░░░ 0%/5h\nGemini: 8.1K tokens | 3 msg\n```\n\n### Detailed (`-d`)\n\nFull breakdown including:\n\n- Rate limit bars with reset countdowns\n- 7-day daily activity table (messages, sessions, tokens)\n- Per-model token/turn breakdown\n- All-time totals\n\n## Configuration\n\nAll settings are Fish universal variables that persist across sessions.\n\n| Variable | Default | Description |\n|---|---|---|\n| `agent_stats_providers` | *(empty)* | Enabled providers (managed by enable/disable) |\n| `agent_stats_cache_ttl` | `300` | Cache lifetime in seconds for compact/detailed modes |\n| `agent_stats_prompt_cache_ttl` | `30` | Cache lifetime in seconds for right-prompt |\n| `agent_stats_icons` | `claude= codex=⬡ gemini=󰫣` | Per-provider icons (Nerd Font glyphs) |\n| `agent_stats_cost_rates` | *(empty)* | Per-model token rates for cost estimation |\n| `agent_stats_cost_currency` | `USD` | Currency code for cost display |\n\n### Customizing Icons\n\n```fish\nset -U agent_stats_icons claude=C codex=X gemini=G\n```\n\nIcons use [Nerd Font](https://www.nerdfonts.com/) glyphs by default. Override with any character or string.\n\n### Starship Integration\n\nIf you use [Starship](https://starship.rs), it defines its own `fish_right_prompt` which overrides the built-in one from this plugin. To display agent-stats in your Starship prompt, add a custom module to `~/.config/starship.toml`:\n\n```toml\n[custom.agent_stats]\ncommand = \"fish -c '__agent_stats_prompt'\"\nwhen = \"fish -c 'test (count $agent_stats_providers) -gt 0'\"\nformat = \"$output\"\nshell = [\"bash\"]\n```\n\nThis calls the same `__agent_stats_prompt` function used by the built-in right prompt, so all formatting, icons, and color coding work identically. The `format = \"$output\"` setting passes through ANSI colors without Starship's default style wrapping.\n\nThen add `${custom.agent_stats}` wherever you want it in your `format` or `right_format`:\n\n```toml\nright_format = \"\"\"$custom\"\"\"\n```\n\nThe `agent-stats` and `agent-stats -d` commands work normally regardless of prompt framework.\n\n### Cost Estimation\n\nShow estimated API-equivalent costs with `agent-stats cost`. The plugin ships with default rates for common model families. Per-model token breakdowns and totals are shown.\n\n```\n$ agent-stats cost\nClaude (all time)\n  sonnet-4-5           in:  5.5M  out: 22.6K  cache: 31.4M   ~$26.13\n  opus-4-6             in:  4.7K  out:  194K   cache: 34.6M   ~$52.00\n  ──────────────────────────────────────────────────────────────────\n  Total                                                        ~$78.13\n```\n\nDefault rates use short prefixes (e.g., `claude:sonnet-4`) to match model families broadly via **prefix matching**. Override or extend with:\n\n```fish\nset -U agent_stats_cost_rates \\\n    claude:sonnet-4:in=3 claude:sonnet-4:out=15 claude:sonnet-4:cache=0.30 \\\n    claude:opus-4:in=15 claude:opus-4:out=75 claude:opus-4:cache=1.50 \\\n    claude:haiku-4:in=0.80 claude:haiku-4:out=4 claude:haiku-4:cache=0.08 \\\n    codex:gpt-5:in=2.50 codex:gpt-5:out=10 codex:gpt-5:think=10 \\\n    gemini:gemini-2:in=1.25 gemini:gemini-2:out=10 gemini:gemini-2:think=10\n```\n\nRates are per million tokens. Token types: `in`, `out`, `cache`, `think`. Check `agent-stats -d` for exact model names in your data.\n\nSet the currency with:\n\n```fish\nset -U agent_stats_cost_currency USD  # USD (default), EUR, GBP, JPY, or any string\n```\n\n### Adjusting Cache TTL\n\n```fish\nset -U agent_stats_cache_ttl 600       # 10 minutes for main display\nset -U agent_stats_prompt_cache_ttl 15  # 15 seconds for right prompt\n```\n\n## Data Sources\n\nThe plugin reads local data written by each agent -- no API keys or authentication needed (except Claude's optional OAuth fallback).\n\n| Provider | Location |\n|---|---|\n| Claude | `~/.claude/plugins/claude-hud/.usage-cache.json`, `~/.claude/projects/` |\n| Codex | `~/.codex/sessions/`, `~/.codex/history.jsonl` |\n| Gemini | `~/.gemini/tmp/session-*.json`, `~/.gemini/tmp/*/logs.json` |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskyline69%2Fagent-stats-fish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskyline69%2Fagent-stats-fish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskyline69%2Fagent-stats-fish/lists"}