@this-dot/claude-code-context-status-line/README.md

Custom Claude Code status line to restore context window visibility for AWS Bedrock users by displaying token usage.

# Claude Code Context Status Line for AWS Bedrock Users

Custom Claude Code status line to restore context window visibility for AWS Bedrock users by displaying token usage. **Specifically designed for AWS Bedrock users who have lost access to the `/context` command** in Claude Code and need to restore visibility into their context window usage.

## What It Does

**Problem Statement:** AWS Bedrock users in Claude Code lost access to the built-in `/context` command, making it impossible to see how much of the context window is being used during conversations.

**Solution:** This tool restores that visibility by parsing Claude Code's transcript files and displaying token usage directly in the status line.

**How It Works:** The tool reads JSONL transcript files generated by Claude Code, extracts token usage data (input + cache read + cache creation tokens), and formats it for display in the status line.

### Output Examples

**Normal Operation:**
- `Opus (125k)` - 125,000 total tokens with Claude 3.5 Opus
- `Sonnet 4 (1.2M)` - 1.2 million tokens with Claude 3.5 Sonnet
- `Claude (50.5k)` - 50,500 tokens with default model name

**Error States:**
- `- (-)` - Error reading transcript or no data available

## Quick Start

**Choose Method 1 if:** You want automatic updates and minimal maintenance
**Choose Method 2 if:** You need offline access or want to modify the script

### Method 1: NPX (Recommended)

Add this to your Claude Code settings (`~/.claude/settings.json`):

```json
{
  "statusLine": {
    "type": "command",
    "command": "npx -y @this-dot/claude-code-context-status-line"
  }
}
```

**Verification:**
```bash
# Test the installation
echo '{"transcript_path":"/tmp/test.jsonl","model":{"display_name":"Test"}}' | npx @this-dot/claude-code-context-status-line
# Expected output: Test (-)
```

### Method 2: Manual Installation

1. Download the script:
```bash
curl -o context-status.js https://raw.githubusercontent.com/thisdot/claude-code-context-status-line/main/src/context-status.js
chmod +x context-status.js
```

2. Add to your `~/.claude/settings.json`:
```json
{
  "statusLine": {
    "type": "command",
    "command": "node /absolute/path/to/context-status.js"
  }
}
```

### Settings File Location

**Finding your Claude Code settings:**
- **macOS**: `~/.claude/settings.json`
- **Linux**: `~/.claude/settings.json`
- **Windows**: `%USERPROFILE%\.claude\settings.json`

## Troubleshooting

### Common Issues

**Status line shows "- (-)" constantly:**
1. Check Claude Code version: `claude --version`
2. Verify settings.json syntax with a JSON validator
3. Test the script manually:
   ```bash
   echo '{"transcript_path":"/path/to/transcript.jsonl"}' | npx -p @this-dot/claude-code-context-status-line claude-code-context-status-line
   ```

**Node.js not found errors:**
- Ensure Node.js 18+ is installed: `node --version`
- Check PATH includes Node.js installation
- On macOS: Try `brew install node` if using Homebrew

**Permission denied errors:**
- Check Claude Code has access to the script location
- Use absolute paths in Claude Code configuration

**Status line doesn't update:**
- Claude Code caches status line output - restart Claude Code to see changes
- Verify your conversation is generating token usage data
- Check that transcript files are being created in the expected location

### Getting Help
1. Check the [Issues page](https://github.com/thisdot/claude-code-context-status-line/issues) for similar problems

## Security & Privacy

**Local Operation Only:**
- All processing happens locally on your machine
- No data is sent to external servers
- Transcript files are read with restricted access

**File Access:**
- Script only reads transcript files provided by Claude Code
- Path traversal protection prevents access outside project directories
- No modification of transcript files - read-only access

**Data Handling:**
- Token counts extracted from conversation metadata only
- No conversation content is processed or stored
- Minimal memory footprint with automatic cleanup

## Performance

**Designed for Efficiency:**
- Processes 10,000+ conversation entries in <100ms
- Memory usage stays under 10MB during processing
- Optimized for frequent status line updates

**Scaling Characteristics:**
- Small conversations (< 50 entries): >10 updates/second
- Large conversations (10,000+ entries): >1 update/second
- No performance degradation over time

**Resource Usage:**
- CPU: Minimal - optimized for quick parsing
- Memory: < 10MB peak usage
- Disk: Read-only access to transcript files

## Compatibility

**Node.js:**
- Minimum: Node.js 18.0.0
- Recommended: Node.js 20+ for optimal performance
- Tested on: 18.x, 20.x, 22.x

**Claude Code:**
- Minimum: Any version with status line support
- Tested with: Claude Code 1.0.80+
- Status line API: Stable across versions

**Operating Systems:**
- ✅ macOS (Intel & Apple Silicon)
- ✅ Linux (Ubuntu 20.04+, other distributions)
- ✅ Windows 10/11 with WSL or native Node.js

**Dependencies:**
- Zero runtime dependencies
- Built-in Node.js modules only

## Understanding Token Counts

**What tokens are counted:**
- **Input tokens**: Your messages and conversation context
- **Cache read tokens**: Previously cached content being reused
- **Cache creation tokens**: New content being cached for future use
- **Total**: Sum of all three token types

**Status Line Behavior:**
- Updates when Claude Code processes new messages
- Shows cumulative token count for entire conversation
- Reflects the most recent conversation state

## License

MIT License - see [LICENSE](LICENSE) file for details.