@ramtinj95/opencode-tokenscope 1.4.0 → 1.4.1

package/README.md

@@ -1,11 +1,54 @@
 # OpenCode-Tokenscope, Token Analyzer Plugin
 
+[![npm version](https://img.shields.io/npm/v/@ramtinj95/opencode-tokenscope.svg)](https://www.npmjs.com/package/@ramtinj95/opencode-tokenscope)
+
 > Comprehensive token usage analysis and cost tracking for OpenCode AI sessions
 
 Track and optimize your token usage across system prompts, user messages, tool outputs, and more. Get detailed breakdowns, accurate cost estimates, and visual insights for your AI development workflow.
 
 ## Installation
 
+### Option 1: npm (Recommended)
+
+1. **Install globally:**
+   ```bash
+   npm install -g @ramtinj95/opencode-tokenscope
+   ```
+
+2. **Add to your `opencode.json`** (create one in your project root or `~/.config/opencode/opencode.json` for global config):
+   ```json
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugin": ["@ramtinj95/opencode-tokenscope"]
+   }
+   ```
+
+3. **Create the `/tokenscope` command** by creating `~/.config/opencode/command/tokenscope.md`:
+   ```bash
+   mkdir -p ~/.config/opencode/command
+   cat > ~/.config/opencode/command/tokenscope.md << 'EOF'
+   ---
+   description: Analyze token usage across the current session with detailed breakdowns by category
+   ---
+
+   Call the tokenscope tool directly without delegating to other agents.
+   Then cat the token-usage-output.txt. DONT DO ANYTHING ELSE WITH THE OUTPUT.
+   • Call the two tools
+   • Not add any additional text or formatting after that
+   EOF
+   ```
+
+4. **Restart OpenCode** and run `/tokenscope`
+
+To always get the latest version automatically, use `@latest`:
+```json
+{
+  "plugin": ["@ramtinj95/opencode-tokenscope@latest"]
+}
+```
+
+### Option 2: Install Script
+
 ```bash
 curl -sSL https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/install.sh | bash
 ```
@@ -14,6 +57,23 @@ Then restart OpenCode and run `/tokenscope`
 
 ## Updating
 
+### If installed via npm:
+
+| Config in `opencode.json` | Behavior |
+|---------------------------|----------|
+| `"@ramtinj95/opencode-tokenscope"` | Uses the version installed at install time. **Never auto-updates.** |
+| `"@ramtinj95/opencode-tokenscope@latest"` | Fetches latest version **every time OpenCode starts**. |
+| `"@ramtinj95/opencode-tokenscope@1.4.0"` | Pins to exact version 1.4.0. Never updates. |
+
+To manually update:
+```bash
+npm update -g @ramtinj95/opencode-tokenscope
+```
+
+Or use `@latest` in your `opencode.json` to auto-update on OpenCode restart.
+
+### If installed via script:
+
 **Option 1: Local script** (if you have the plugin installed)
 ```bash
 bash ~/.config/opencode/plugin/install.sh --update
@@ -273,32 +333,9 @@ SUMMARY
 
 **Free/Open models** are marked with zero pricing.
 
-## Customization
-
-### Add New Model Pricing
-
-Edit `~/.config/opencode/plugin/models.json`:
-
-```json
-{
-  "your-model-name": {
-    "input": 1.50,
-    "output": 5.00,
-    "cacheWrite": 0.50,
-    "cacheRead": 0.10
-  }
-}
-```
-
-Save the file and restart OpenCode. The plugin will automatically use the new pricing.
-
-### Update Existing Model Pricing
-
-Simply edit the values in `models.json` and restart OpenCode. No code changes needed!
-
-### Configure Analysis Features
+## Configuration
 
-Edit `~/.config/opencode/plugin/tokenscope-config.json` to enable/disable sections:
+The plugin includes a `tokenscope-config.json` file with these defaults:
 
 ```json
 {
@@ -309,205 +346,30 @@ Edit `~/.config/opencode/plugin/tokenscope-config.json` to enable/disable sectio
 }
 ```
 
-Set any option to `false` to hide that section from the output. All features are enabled by default.
-
-## How It Works
-
-### System Prompt Inference
-OpenCode doesn't expose system prompts in the session messages API. The plugin intelligently infers them using:
-
-```
-System Tokens = (API Input + Cache Read) - (User Tokens + Tool Tokens)
-```
-
-This works because the API input includes everything sent to the model.
-
-### Dual Tracking
-- **Current Context**: Uses the most recent API call with non-zero tokens (matches TUI)
-- **Session Total**: Aggregates all API calls for accurate billing
-
-### Subagent Analysis
-The plugin uses OpenCode's session API to:
-1. Fetch all child sessions spawned by the Task tool
-2. Recursively analyze nested subagents (subagents can spawn their own subagents)
-3. Aggregate tokens, costs, and API call counts
-4. Calculate estimated costs using the same pricing as the main session
-
-### Model Name Normalization
-Automatically handles `provider/model` format (e.g., `qwen/qwen3-coder` → `qwen3-coder`)
-
-## Understanding the Numbers
-
-### Current Context vs Session Total
-
-- **Current Context**: What's in your context window right now
-  - Based on most recent API call
-  - Used to understand current memory usage
-
-- **Session Total**: All tokens processed in this session
-  - Sum of all API calls in the main session
-  - What you're billed for (main session only)
-  - Used for cost calculation
-
-### Subagent Totals
-
-When using the Task tool, OpenCode spawns subagent sessions. These are tracked separately:
-
-- **Subagent Tokens**: Combined tokens from all child sessions
-- **Subagent API Calls**: Total API calls made by all subagents
-- **Grand Total**: Main session + all subagents combined
-
-### Cache Tokens
-
-- **Cache Read**: Tokens retrieved from cache (discounted rate ~90% off)
-- **Cache Write**: Tokens written to cache (slight premium ~25% more)
-- **Note**: Cache write is a billing charge, not additional context tokens
+Set any option to `false` to hide that section from the output.
 
 ## Troubleshooting
 
-### "Dependencies missing" Error
-
-Run the installer:
-```bash
-curl -sSL https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/install.sh | bash
-```
-
-### Command Not Appearing
+### Command `/tokenscope` Not Appearing
 
 1. Verify `tokenscope.md` exists:
    ```bash
    ls ~/.config/opencode/command/tokenscope.md
    ```
-2. Restart OpenCode completely
-3. Check OpenCode logs for plugin errors
+2. If missing, create it (see Installation step 3)
+3. Restart OpenCode completely
 
 ### Wrong Token Counts
 
 The plugin uses API telemetry (ground truth). If counts seem off:
 - **Expected ~2K difference from TUI**: Plugin analyzes before its own response is added
 - **Model detection**: Check that the model name is recognized in the output
-- **Tokenizer not installed**: Re-run the installer
-
-### New Model Not Showing Correct Pricing
-
-1. Check if model exists in `models.json`
-2. Try exact match or prefix match (e.g., `claude-sonnet-4` matches `claude-sonnet-4-20250514`)
-3. Add entry to `models.json` if missing
-4. Restart OpenCode after editing `models.json`
-
-### Plugin Fails to Load
-
-1. Validate JSON syntax:
-   ```bash
-   cd ~/.config/opencode/plugin
-   node -e "JSON.parse(require('fs').readFileSync('models.json', 'utf8'))"
-   ```
-2. Check for trailing commas or syntax errors
-3. Plugin falls back to default pricing if file is invalid
-
-## Architecture
-
-### File Structure
-
-```
-plugin/
-├── tokenscope.ts           # Main entry point - Plugin export
-├── tokenscope-lib/
-│   ├── types.ts            # All interfaces and type definitions
-│   ├── config.ts           # Constants, model maps, pricing loader
-│   ├── tokenizer.ts        # TokenizerManager class
-│   ├── analyzer.ts         # ModelResolver, ContentCollector, TokenAnalysisEngine
-│   ├── cost.ts             # CostCalculator class
-│   ├── subagent.ts         # SubagentAnalyzer class
-│   ├── formatter.ts        # OutputFormatter class
-│   └── context.ts          # ContextAnalyzer class (context breakdown, tool estimates, cache efficiency)
-├── models.json             # Pricing data for 41+ models
-├── tokenscope-config.json  # Feature toggles configuration
-├── package.json            # Plugin metadata
-└── install.sh              # Installation script
-```
-
-### Core Components
-
-1. **TokenizerManager** (`tokenscope-lib/tokenizer.ts`): Loads and caches tokenizers (tiktoken, transformers)
-2. **ModelResolver** (`tokenscope-lib/analyzer.ts`): Detects model and selects appropriate tokenizer
-3. **ContentCollector** (`tokenscope-lib/analyzer.ts`): Extracts content from session messages, including tool call counts
-4. **TokenAnalysisEngine** (`tokenscope-lib/analyzer.ts`): Counts tokens and applies API telemetry adjustments
-5. **CostCalculator** (`tokenscope-lib/cost.ts`): Calculates costs from pricing database with cache-aware pricing
-6. **SubagentAnalyzer** (`tokenscope-lib/subagent.ts`): Recursively fetches and analyzes child sessions from Task tool calls
-7. **ContextAnalyzer** (`tokenscope-lib/context.ts`): Analyzes context breakdown, tool schema estimates, and cache efficiency
-8. **OutputFormatter** (`tokenscope-lib/formatter.ts`): Generates visual reports with charts and summaries
 
 ## Privacy & Security
 
 - **All processing is local**: No session data sent to external services
-- **Tokenizers from official sources**:
-  - OpenAI tokenizers: npm registry
-  - Transformers: Hugging Face Hub
 - **Open source**: Audit the code yourself
 
-## Performance
-
-- **Fast**: Tokenizers cached after first load
-- **Parallel**: Categories processed concurrently
-- **Efficient**: Only analyzes on demand
-- **First-run download**: Transformers models download on demand (5-50MB per model)
-- **Subsequent runs**: Instant (uses cache)
-
-## Manual Installation
-
-<details>
-<summary>Click to expand manual installation steps</summary>
-
-### Requirements
-- OpenCode installed (`~/.config/opencode` directory exists)
-- npm (for tokenizer dependencies)
-- ~50MB disk space (for tokenizer models)
-
-### Installation Steps
-
-1. **Navigate to OpenCode config**:
-   ```bash
-   cd ~/.config/opencode
-   ```
-
-2. **Download plugin files**:
-   ```bash
-   mkdir -p plugin/tokenscope-lib
-   cd plugin
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope.ts
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/models.json
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/package.json
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope-config.json
-   cd tokenscope-lib
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope-lib/types.ts
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope-lib/config.ts
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope-lib/tokenizer.ts
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope-lib/analyzer.ts
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope-lib/cost.ts
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope-lib/subagent.ts
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope-lib/formatter.ts
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/plugin/tokenscope-lib/context.ts
-   ```
-
-3. **Download command file**:
-   ```bash
-   cd ../../command
-   curl -O https://raw.githubusercontent.com/ramtinJ95/opencode-tokenscope/main/command/tokenscope.md
-   ```
-
-4. **Install dependencies**:
-   ```bash
-   cd ../plugin
-   npm install js-tiktoken@1.0.15 @huggingface/transformers@3.1.2
-   ```
-
-5. **Restart OpenCode**
-
-6. **Test**: Run `/tokenscope` in any session
-
-</details>
-
 ## Contributing
 
 Contributions welcome! Ideas for enhancement:

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@ramtinj95/opencode-tokenscope",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "OpenCode plugin for detailed token usage analysis with breakdowns by category, visual charts, and subagent cost tracking",
   "type": "module",
   "main": "./dist/tokenscope.js",