pokegent 2.0.1 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +109 -101
  2. package/dist/index.js +542 -467
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -5,163 +5,171 @@
5
5
 
6
6
  [![Node.js](https://img.shields.io/badge/node-18%2B-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
7
7
  [![Ink](https://img.shields.io/badge/ink-5.0%2B-ff7700?style=flat-square)](https://github.com/vadimdemedes/ink)
8
- [![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
9
8
  <br>
10
9
  [![GitHub release](https://img.shields.io/github/v/release/shafiqimtiaz/pokegent?style=flat-square&logo=github)](https://github.com/shafiqimtiaz/pokegent/releases)
11
10
  [![GitHub stars](https://img.shields.io/github/stars/shafiqimtiaz/pokegent?style=flat-square)](https://github.com/shafiqimtiaz/pokegent)
12
11
 
13
- Terminal dashboard that shows what's running in your Pokémon AI coding ecosystem — 16 Pokémon species (CLI) detectors, TMs/HMs (MCP) discovery, movepool usage charts, PP burn metrics, and a shareable HTML Trainer Card with animated sprites.
12
+ Terminal dashboard that scans and monitors your Pokémon AI coding ecosystem — 16 Pokémon species (CLI) detectors, TMs/HMs (MCP) discovery, movepool usage charts, PP burn metrics, and a shareable HTML Trainer Card.
14
13
 
15
- [Features](#features) • [Installation](#installation) • [Usage](#usage) • [Share](#share-your-setup)
14
+ [Features](#features) • [Installation](#installation) • [Usage](#usage) • [Scoring](#scoring) • [Privacy](#privacy)
16
15
 
17
16
  </div>
18
17
 
19
- Pokégent is a Node.js TUI that scans your local machine to give you a live picture of your Pokémon AI tooling landscape. It detects running AI processes as Pokémon, finds TMs/HMs (installed MCP servers), tallies movepool (model) usage from shell history and log files, and estimates PP burn rates (tokens) — all without ever making a network request.
18
+ Pokégent is a Node.js TUI that scans your local machine to give you a live picture of your Pokémon AI tooling landscape. It detects running AI processes as active Pokémon, discovers installed TMs/HMs (MCP servers), tallies movepool (model) usage from history, and measures PP burn rates (tokens) — all locally, with zero outbound network requests.
20
19
 
21
20
  > [!NOTE]
22
- > Pokégent runs entirely locally. No telemetry, no outbound calls, no external services. It reads the process table, configuration directories, and log files on your machine and renders the results in your terminal.
21
+ > Pokégent runs entirely locally. It reads the process table, configuration directories, and local log files on your machine to render the results in your terminal. No telemetry, no network calls.
22
+
23
+ ---
23
24
 
24
25
  ## Features
25
26
 
26
- - **16 Pokémon species detectors** — Scans for Mewtwo, Venusaur, Blastoise, Pikachu, Eevee, Charizard, Charmander, Gengar, Snorlax, Zubat, Jigglypuff, Ditto, Machamp, Rayquaza, Lapras, and Dragonite
27
- - **TM/HM (MCP) discovery** — Aggregates tool servers from `~/.claude`, `~/.cursor`, `~/.opencode`, `~/.n8n` and other standard config paths
28
- - **Movepool (Model) frequency charts** — Parses terminal history and log files for model mentions, renders horizontal ASCII bars
29
- - **PP (Token) burn analytics** — Battles (sessions), PP velocity, input/output splits, and estimated cost from local logs
30
- - **Trainer scoring system** — 0-1000 points across Pokémon, TMs/HMs, movepool, and PP burn metrics
31
- - **7 Trainer badges** — 🏆 Pokédex Master, 🦄 Legendary Trainer, 🧬 Hybrid Evolution, 🔥 Blast Burn, 💎 Elite Four, ⚡ Thunder Shock, 🌐 Safari Zone Master
32
- - **Shareable HTML Trainer Card** — Generate a beautiful, self-contained HTML Trainer Card featuring animated showdown sprites for active Pokémon
33
- - **2-second auto-refresh** — Live updates so you can watch your ecosystem change as you work
34
- - **Demo mode** — Built-in realistic mock data for previews, screenshots, or evaluation
27
+ - **16 Pokémon Species Detectors** — Scans for running AI platforms represented as Pokémon (Mewtwo, Pikachu, Eevee, Gengar, Snorlax, Charizard, etc.).
28
+ - **TM/HM (MCP) Discovery** — Aggregates installed tool servers from standard config paths (Claude, Cursor, OpenCode, n8n, etc.).
29
+ - **Movepool Frequency Charts** — Analyzes shell history and log files for model name patterns, rendering horizontal ASCII bars.
30
+ - **PP Burn Analytics** — Measures battles (sessions), PP velocity (tokens/min), input/output splits, and estimated token costs.
31
+ - **Trainer Level Scoring** — Calculates a score from 0-1000 across your active roster, moves, and items.
32
+ - **7 Trainer Badges** — Earn badges like `Pokédex Master`, `Blast Burn`, or `Thunder Shock` based on your setup.
33
+ - **HTML Trainer Card** — Generates a self-contained, GameBoy-style HTML card featuring animated showdown sprites for active Pokémon.
34
+
35
+ ---
35
36
 
36
37
  ## Installation
37
38
 
39
+ You can run and install Pokégent using the following methods:
40
+
41
+ ### 1. Run directly (Zero Install)
42
+ The quickest way to run Pokégent is using `npx`:
38
43
  ```bash
39
- # Run directly with npx (zero install)
40
44
  npx pokegent
45
+ ```
41
46
 
42
- # Or install globally
47
+ ### 2. Global Installation
48
+ To install Pokégent globally on your system:
49
+ ```bash
43
50
  npm install -g pokegent
44
51
  ```
52
+ Once installed, you can start the TUI dashboard by typing:
53
+ ```bash
54
+ pokegent
55
+ ```
45
56
 
46
- ## Usage
47
-
57
+ ### 3. Build & Run from Source (Local Development)
58
+ If you want to run or modify the code locally:
48
59
  ```bash
49
- # Live TUI dashboard
50
- npx pokegent
60
+ # Clone the repository
61
+ git clone https://github.com/shafiqimtiaz/pokegent.git
62
+ cd pokegent
51
63
 
52
- # Demo mode with mock data
53
- npx pokegent --demo
64
+ # Install dependencies
65
+ npm install
54
66
 
55
- # Generate shareable card + copy markdown to clipboard
56
- npx pokegent --share
67
+ # Build the project (compiles TypeScript to dist/index.js)
68
+ npm run build
57
69
 
58
- # Generate HTML card file
59
- npx pokegent --html
70
+ # Start the dashboard
71
+ npm start
60
72
 
61
- # Export raw JSON data
62
- npx pokegent --json
73
+ # Run with demo mock data
74
+ node dist/index.js --demo
63
75
  ```
64
76
 
65
- ### Keyboard shortcuts (TUI mode)
77
+ ---
66
78
 
67
- | Key | Action |
68
- |-----|--------|
69
- | `q` | Quit the application |
70
- | `r` | Force an immediate refresh |
71
- | `s` | Share card (copy markdown to clipboard) |
72
- | `h` | Generate HTML card |
73
-
74
- ## Share your setup
75
-
76
- The viral mechanic: **press `s` to copy a markdown card to clipboard, or `h` to generate an HTML file.**
79
+ ## Usage
77
80
 
78
- ### Markdown card (for Discord, GitHub, Slack)
81
+ Run Pokégent with optional flags to generate reports or export data:
79
82
 
80
83
  ```bash
81
- npx pokegent --share
82
- ```
84
+ # Start TUI dashboard with live local scans
85
+ pokegent
83
86
 
84
- This prints the terminal card AND copies a markdown version to your clipboard. Paste it anywhere.
87
+ # Start TUI dashboard in demo mode (with realistic mock data)
88
+ pokegent --demo
85
89
 
86
- ### HTML Trainer Card (for GitHub Pages, Twitter, anywhere)
90
+ # Generate a markdown Trainer Card and copy it to the clipboard
91
+ pokegent --share
87
92
 
88
- ```bash
89
- npx pokegent --html
93
+ # Export stats as a GameBoy-style HTML card file (pokegent.html)
94
+ pokegent --html
95
+
96
+ # Export scanned data in raw JSON format
97
+ pokegent --json
90
98
  ```
91
99
 
92
- This generates `pokegent.html` — a self-contained, dark-red/black themed, animated card featuring dynamic Pokémon gifs and OpenGraph meta tags for beautiful link previews. Drop it in a repo, open it in a browser, or share the raw link.
100
+ ### Keyboard Shortcuts (TUI Mode)
101
+
102
+ | Key | Action |
103
+ |-----|--------|
104
+ | `q` | Quit Pokégent |
105
+ | `r` | Force an immediate scan refresh |
106
+ | `s` | Share setup (copies markdown card to clipboard) |
107
+ | `h` | Generate HTML Trainer Card (`pokegent.html`) |
108
+
109
+ ---
93
110
 
94
111
  ## Scoring
95
112
 
96
- Your setup gets scored 0-1000 points:
113
+ Your roster, moves, and items get scored up to 1000 points:
97
114
 
98
115
  | Dimension | Max Points | How |
99
116
  |-----------|-----------|-----|
100
- | Pokémon running | 350 | 75 per running Pokémon (cap 4) + 50 bonus for 3+ simultaneous |
101
- | TMs & HMs (MCP) | 200 | 10 per server (cap 15) + 1 per tool (cap 50) |
102
- | Movepool diversity | 200 | 30 per unique model (cap 5) + 50 for using 3+ providers |
103
- | PP velocity + battles | 250 | PP velocity tiers + battle count |
104
-
105
- ### Rarity tiers
106
-
107
- | Score | Tier |
108
- |-------|------|
109
- | 900+ | 🌟 MYTHICAL CHAMPION — Top 1% |
110
- | 750+ | 💎 SHINY LEGENDARY — Top 5% |
111
- | 600+ | 🥇 POKÉMON MASTER — Top 15% |
112
- | 400+ | 🥈 GYM LEADER — Top 35% |
113
- | 200+ | 🥉 ELITE TRAINER — Top 60% |
114
- | <200 | 🌱 BEGINNER TRAINER — everyone starts here |
117
+ | **Pokémon Running** | 350 pts | 75 pts per active Pokémon (cap 4) + 50 pts bonus for 3+ simultaneous |
118
+ | **TMs & HMs (MCP)** | 200 pts | 10 pts per server (cap 15) + 1 pt per tool/move (cap 50) |
119
+ | **Movepool Diversity** | 200 pts | 30 pts per unique model (cap 5) + 50 pts for using 3+ providers |
120
+ | **PP Velocity + Battles** | 250 pts | Velocity levels + session/battle count |
121
+
122
+ ### Rarity Tiers
123
+
124
+ Based on your score, you are assigned a Trainer Tier:
125
+ - **900+** — 🌟 MYTHICAL CHAMPION (Top 1%)
126
+ - **750+** — 💎 SHINY LEGENDARY (Top 5%)
127
+ - **600+** — 🥇 POKÉMON MASTER (Top 15%)
128
+ - **400+** — 🥈 GYM LEADER (Top 35%)
129
+ - **200+** — 🥉 ELITE TRAINER (Top 60%)
130
+ - **<200** — 🌱 BEGINNER TRAINER (Rookie level)
131
+
132
+ ---
115
133
 
116
134
  ## What gets scanned
117
135
 
118
136
  <details>
119
- <summary><strong>16 Pokémon species and their detection signals</strong></summary>
120
-
121
- | Pokémon | CLI Platform | Process match | Config path |
122
- |---------|--------------|---------------|-------------|
123
- | Mewtwo | Claude Code | `claude*` | `~/.claude` |
124
- | Venusaur | Codex | `codex*` | `~/.codex` |
125
- | Blastoise | GitHub Copilot CLI | `copilot*` | `~/.copilot` |
126
- | Pikachu | Gemini CLI | `gemini*` | `~/.gemini` |
127
- | Eevee | Cursor | `cursor` | `~/.cursor` |
128
- | Charizard | Amp | `amp*` | `~/.amp` |
129
- | Charmander | Cline | — | `~/.cline`, VS Code ext |
130
- | Gengar | Roo Code | `roo*` | `~/.roo` |
131
- | Snorlax | Kilo Code | `kilo*` | `~/.kilo` |
132
- | Zubat | Kiro | `kiro` | `~/.kiro` |
133
- | Jigglypuff | Crush | — | `~/.crush` |
134
- | Ditto | OpenCode | `opencode` | `~/.opencode` |
135
- | Machamp | Factory Droid | `factory-droid` | `~/.factory-droid` |
136
- | Rayquaza | Antigravity | `antigravity*` | `~/.antigravity` |
137
- | Lapras | Kimi CLI | `kimi*` | `~/.kimi` |
138
- | Dragonite | Qwen Code | `qwen*` | `~/.qwen` |
137
+ <summary><strong>16 Pokémon Species & CLI Mappings</strong></summary>
138
+
139
+ | Pokémon | CLI Platform | Process keyword | Config path |
140
+ |---------|--------------|-----------------|-------------|
141
+ | **Mewtwo** | Claude Code | `claude*` | `~/.claude` |
142
+ | **Venusaur** | Codex | `codex*` | `~/.codex` |
143
+ | **Blastoise** | GitHub Copilot CLI | `copilot*` | `~/.copilot` |
144
+ | **Pikachu** | Gemini CLI | `gemini*` | `~/.gemini` |
145
+ | **Eevee** | Cursor | `cursor` | `~/.cursor` |
146
+ | **Charizard** | Amp | `amp*` | `~/.amp` |
147
+ | **Charmander** | Cline | — | `~/.cline` |
148
+ | **Gengar** | Roo Code | `roo*` | `~/.roo` |
149
+ | **Snorlax** | Kilo Code | `kilo*` | `~/.kilo` |
150
+ | **Zubat** | Kiro | `kiro` | `~/.kiro` |
151
+ | **Jigglypuff** | Crush | — | `~/.crush` |
152
+ | **Ditto** | OpenCode | `opencode` | `~/.opencode` |
153
+ | **Machamp** | Factory Droid | `factory-droid` | `~/.factory-droid` |
154
+ | **Rayquaza** | Antigravity | `antigravity*` | `~/.antigravity` |
155
+ | **Lapras** | Kimi CLI | `kimi*` | `~/.kimi` |
156
+ | **Dragonite** | Qwen Code | `qwen*` | `~/.qwen` |
139
157
 
140
158
  </details>
141
159
 
142
160
  <details>
143
- <summary><strong>Scanned moves / models (19 patterns)</strong></summary>
161
+ <summary><strong>Scanned Moves & Models (19 patterns)</strong></summary>
144
162
 
145
- claude-4-opus, claude-4-sonnet, claude-3.7-sonnet, claude-3.5-sonnet, claude-3-haiku, gpt-4.1, gpt-4o, gpt-4-turbo, o4-mini, o3, o3-mini, o3-pro, gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash, deepseek-v3, deepseek-r1, qwen-3, llama-4
163
+ Scans for occurrences of the following model families in your local history and logs:
164
+ - `claude-4-opus`, `claude-4-sonnet`, `claude-3.7-sonnet`, `claude-3.5-sonnet`, `claude-3-haiku`
165
+ - `gpt-4.1`, `gpt-4o`, `gpt-4-turbo`, `o4-mini`, `o3`, `o3-mini`, `o3-pro`
166
+ - `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.0-flash`
167
+ - `deepseek-v3`, `deepseek-r1`, `qwen-3`, `llama-4`
146
168
 
147
169
  </details>
148
170
 
149
- ## Tech stack
150
-
151
- - **[Ink](https://github.com/vadimdemedes/ink)** — React for CLI. Provides the TUI framework.
152
- - **[ps-list](https://github.com/sindresorhus/ps-list)** — Cross-platform process listing.
153
- - **Node.js 18+** — All scanning logic uses built-in modules (`fs`, `path`, `child_process`).
154
-
155
- ## Running from source
156
-
157
- ```bash
158
- git clone https://github.com/shafiqimtiaz/pokegent.git
159
- cd pokegent
160
- npm install
161
- npx tsx src/index.ts --demo
162
- npx tsx src/index.ts
163
- ```
171
+ ---
164
172
 
165
173
  ## Privacy
166
174
 
167
- Pokégent runs 100% locally. No data leaves your machine. No telemetry. No analytics. No network requests. Your AI tooling data stays on your computer.
175
+ Pokégent runs 100% locally. No data leaves your machine. No telemetry. No analytics. No outbound network requests are made during scanning. All log file parsing, process checking, and configuration scans happen entirely on your computer.