# Claude Statusline
Real-time session tracking and analytics for Claude Code, displaying usage metrics in a compact statusline format.
## Features
- 📊 **Real-time Monitoring** - Track active sessions with live updates
- 💰 **Cost Tracking** - Accurate cost calculation based on official pricing
- 📈 **Analytics** - Detailed reports on usage patterns and trends
- 🤖 **Multi-Model Support** - Track Opus, Sonnet, and Haiku models
- 🎨 **20+ Display Templates** - Choose from various statusline formats
- ⚡ **Lightweight** - Minimal dependencies (only psutil)
- 📦 **Easy Installation** - Available as a Python package
- 🎯 **Unified CLI** - Single command interface for all features
## Quick Start
### Install from Package
```bash
# Install the package
pip install claude-statusline
# View current status
claude-status
# Use the CLI
claude-statusline --help
```
### Install from Source
```bash
# Clone repository
git clone https://github.com/ersinkoc/claude-statusline.git
cd claude-statusline
# Install in development mode
pip install -e .
# Or build and install the package
python -m build
pip install dist/claude_statusline-*.whl
```
**Example Outputs:**
```
[Opus 4.1] LIVE ~17:00 | 727msg 65.9M $139 # Compact (default)
O4.1 456m $90 # Minimal
claude@O4.1:~$ 456 msgs | $89.99 # Terminal
--INSERT-- O4.1 456L $90.0 [utf-8] # Vim style
```
📖 **[See all 20+ templates](TEMPLATES.md)** - Choose your favorite style!
## Installation
### Prerequisites
- Python 3.8+
- Claude Code installed
- Access to `~/.claude` directory
### Package Installation
```bash
# Install from PyPI (when published)
pip install claude-statusline
# Install from local wheel
pip install dist/claude_statusline-1.3.0-py3-none-any.whl
# Development installation
git clone https://github.com/ersinkoc/claude-statusline.git
cd claude-statusline
pip install -e .
```
### Claude Code Integration
Add to your Claude Code `settings.json`:
```json
{
"statusline": {
"command": "claude-status"
}
}
```
Or if using from source:
```json
{
"statusline": {
"command": "python",
"args": ["path/to/claude-statusline/statusline.py"]
}
}
```
## Usage
### Command Line Interface
```bash
# Main CLI
claude-statusline <command> [options]
# Direct statusline display
claude-status
```
### Common Commands
```bash
# Core functionality
claude-statusline status # Current session status
claude-statusline daemon # Manage background daemon
claude-statusline rebuild # Rebuild database
# Analytics
claude-statusline costs # Cost analysis
claude-statusline daily # Daily report
claude-statusline sessions # Session details
claude-statusline heatmap # Activity heatmap
claude-statusline summary # Summary statistics
# Configuration
claude-statusline template # Select display template
claude-statusline update-prices # Update model prices
claude-statusline rotate # Toggle statusline rotation
```
📖 **[Full CLI Documentation](CLI.md)** - Complete command reference with all options and examples
## How It Works
1. **Data Collection**: Reads Claude Code's JSONL conversation logs
2. **Processing**: Background daemon processes and aggregates data
3. **Storage**: Maintains a local database of sessions and metrics
4. **Display**: Formats data into a compact, readable statusline
```
Claude Code → JSONL Files → Daemon → Database → Statusline
```
## Configuration
### Basic Settings (`config.json`)
```json
{
"display": {
"template": "compact", // Choose from 20+ templates
"enable_rotation": false,
"status_format": "compact"
},
"monitoring": {
"session_duration_hours": 5
}
}
```
### Template Selection
```bash
# Interactive template selector with preview
claude-statusline template
# Quick template change
claude-statusline template minimal
claude-statusline template vim
```
📖 **[Template Gallery](TEMPLATES.md)** - Preview all available statusline formats
### Pricing Updates
Model prices are automatically updated from the official repository:
```bash
claude-statusline update-prices
```
## Project Structure
```
claude-statusline/
├── claude_statusline/ # Package directory
│ ├── __init__.py # Package initialization
│ ├── cli.py # Main CLI interface
│ ├── statusline.py # Core statusline display
│ ├── daemon.py # Background processor
│ ├── templates.py # Template definitions
│ ├── config.json # Configuration
│ └── prices.json # Model pricing
├── tests/ # Test suite
├── docs/ # Documentation
├── setup.py # Package setup
├── pyproject.toml # Modern package config
└── README.md # This file
```
## Data Files
- **Source**: `~/.claude/projects/*/` - Claude Code JSONL files
- **Database**: `~/.claude/data-statusline/` - Processed data
- `smart_sessions_db.json` - Session database
- `live_session.json` - Current session
- `daemon_status.json` - Daemon status
## Development
### Setup Development Environment
```bash
# Clone repository
git clone https://github.com/ersinkoc/claude-statusline.git
cd claude-statusline
# Install in development mode
pip install -e .
# Install development dependencies
pip install -e ".[dev]"
```
### Running Tests
```bash
# Run test suite
pytest
# Run with coverage
pytest --cov=claude_statusline
# Run specific test
pytest tests/test_statusline.py
```
### Building the Package
```bash
# Install build tools
pip install build twine
# Build package
python -m build
# Check package
twine check dist/*
# Upload to PyPI (when ready)
twine upload dist/*
```
## Troubleshooting
### No Data Showing
```bash
# Check Claude Code data exists
ls ~/.claude/projects/
# Rebuild database
claude-statusline rebuild
# Ensure daemon is running
claude-statusline daemon --status
```
### Incorrect Costs
```bash
# Update prices
claude-statusline update-prices
# Verify calculations
claude-statusline verify
```
### Package Issues
```bash
# Reinstall package
pip uninstall claude-statusline
pip install dist/claude_statusline-*.whl
# Check installation
pip show claude-statusline
```
### More Help
- Run `claude-statusline --help` for command help
- See [CLI.md](CLI.md) for detailed documentation
- Check [CLAUDE_CODE_SETUP.md](CLAUDE_CODE_SETUP.md) for Claude Code integration
- Report issues on [GitHub](https://github.com/ersinkoc/claude-statusline/issues)
## Documentation
- [CLI Reference](CLI.md) - Complete command documentation
- [Template Gallery](TEMPLATES.md) - All 20+ statusline formats
- [Architecture](ARCHITECTURE.md) - System design and data flow
- [Claude Code Setup](CLAUDE_CODE_SETUP.md) - Integration guide
- [Contributing](CONTRIBUTING.md) - Contribution guidelines
- [Changelog](CHANGELOG.md) - Version history
- [Security](SECURITY.md) - Security policy
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
- Claude Code team for the excellent development environment
- Contributors and testers from the community
- Built with ❤️ for the Claude Code community
## Support
- **Issues**: [GitHub Issues](https://github.com/ersinkoc/claude-statusline/issues)
- **Discussions**: [GitHub Discussions](https://github.com/ersinkoc/claude-statusline/discussions)
- **Documentation**: [Full CLI Reference](CLI.md)
---
**Current Version**: 1.3.3 | **Last Updated**: 2025-08-14 | **Package**: `claude-statusline`
Raw data
{
"_id": null,
"home_page": "https://github.com/ersinkoc/claude-statusline",
"name": "claude-statusline",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "claude, claude-code, statusline, monitoring, analytics, ai, anthropic, session-tracking, cost-tracking, developer-tools",
"author": "Ersin Ko\u00e7",
"author_email": "Ersin Ko\u00e7 <ersinkoc@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9d/cf/1231a554a1ef6f457ce787a7e3b7ca9961f7c639518c8bb055350ca83d4f/claude_statusline-1.3.3.tar.gz",
"platform": null,
"description": "# Claude Statusline\r\n\r\nReal-time session tracking and analytics for Claude Code, displaying usage metrics in a compact statusline format.\r\n\r\n\r\n\r\n\r\n\r\n\r\n## Features\r\n\r\n- \ud83d\udcca **Real-time Monitoring** - Track active sessions with live updates\r\n- \ud83d\udcb0 **Cost Tracking** - Accurate cost calculation based on official pricing\r\n- \ud83d\udcc8 **Analytics** - Detailed reports on usage patterns and trends\r\n- \ud83e\udd16 **Multi-Model Support** - Track Opus, Sonnet, and Haiku models\r\n- \ud83c\udfa8 **20+ Display Templates** - Choose from various statusline formats\r\n- \u26a1 **Lightweight** - Minimal dependencies (only psutil)\r\n- \ud83d\udce6 **Easy Installation** - Available as a Python package\r\n- \ud83c\udfaf **Unified CLI** - Single command interface for all features\r\n\r\n## Quick Start\r\n\r\n### Install from Package\r\n\r\n```bash\r\n# Install the package\r\npip install claude-statusline\r\n\r\n# View current status\r\nclaude-status\r\n\r\n# Use the CLI\r\nclaude-statusline --help\r\n```\r\n\r\n### Install from Source\r\n\r\n```bash\r\n# Clone repository\r\ngit clone https://github.com/ersinkoc/claude-statusline.git\r\ncd claude-statusline\r\n\r\n# Install in development mode\r\npip install -e .\r\n\r\n# Or build and install the package\r\npython -m build\r\npip install dist/claude_statusline-*.whl\r\n```\r\n\r\n**Example Outputs:**\r\n```\r\n[Opus 4.1] LIVE ~17:00 | 727msg 65.9M $139 # Compact (default)\r\nO4.1 456m $90 # Minimal\r\nclaude@O4.1:~$ 456 msgs | $89.99 # Terminal\r\n--INSERT-- O4.1 456L $90.0 [utf-8] # Vim style\r\n```\r\n\r\n\ud83d\udcd6 **[See all 20+ templates](TEMPLATES.md)** - Choose your favorite style!\r\n\r\n## Installation\r\n\r\n### Prerequisites\r\n- Python 3.8+\r\n- Claude Code installed\r\n- Access to `~/.claude` directory\r\n\r\n### Package Installation\r\n\r\n```bash\r\n# Install from PyPI (when published)\r\npip install claude-statusline\r\n\r\n# Install from local wheel\r\npip install dist/claude_statusline-1.3.0-py3-none-any.whl\r\n\r\n# Development installation\r\ngit clone https://github.com/ersinkoc/claude-statusline.git\r\ncd claude-statusline\r\npip install -e .\r\n```\r\n\r\n### Claude Code Integration\r\n\r\nAdd to your Claude Code `settings.json`:\r\n\r\n```json\r\n{\r\n \"statusline\": {\r\n \"command\": \"claude-status\"\r\n }\r\n}\r\n```\r\n\r\nOr if using from source:\r\n\r\n```json\r\n{\r\n \"statusline\": {\r\n \"command\": \"python\",\r\n \"args\": [\"path/to/claude-statusline/statusline.py\"]\r\n }\r\n}\r\n```\r\n\r\n## Usage\r\n\r\n### Command Line Interface\r\n\r\n```bash\r\n# Main CLI\r\nclaude-statusline <command> [options]\r\n\r\n# Direct statusline display\r\nclaude-status\r\n```\r\n\r\n### Common Commands\r\n\r\n```bash\r\n# Core functionality\r\nclaude-statusline status # Current session status\r\nclaude-statusline daemon # Manage background daemon\r\nclaude-statusline rebuild # Rebuild database\r\n\r\n# Analytics\r\nclaude-statusline costs # Cost analysis\r\nclaude-statusline daily # Daily report\r\nclaude-statusline sessions # Session details\r\nclaude-statusline heatmap # Activity heatmap\r\nclaude-statusline summary # Summary statistics\r\n\r\n# Configuration\r\nclaude-statusline template # Select display template\r\nclaude-statusline update-prices # Update model prices\r\nclaude-statusline rotate # Toggle statusline rotation\r\n```\r\n\r\n\ud83d\udcd6 **[Full CLI Documentation](CLI.md)** - Complete command reference with all options and examples\r\n\r\n## How It Works\r\n\r\n1. **Data Collection**: Reads Claude Code's JSONL conversation logs\r\n2. **Processing**: Background daemon processes and aggregates data\r\n3. **Storage**: Maintains a local database of sessions and metrics\r\n4. **Display**: Formats data into a compact, readable statusline\r\n\r\n```\r\nClaude Code \u2192 JSONL Files \u2192 Daemon \u2192 Database \u2192 Statusline\r\n```\r\n\r\n## Configuration\r\n\r\n### Basic Settings (`config.json`)\r\n\r\n```json\r\n{\r\n \"display\": {\r\n \"template\": \"compact\", // Choose from 20+ templates\r\n \"enable_rotation\": false,\r\n \"status_format\": \"compact\"\r\n },\r\n \"monitoring\": {\r\n \"session_duration_hours\": 5\r\n }\r\n}\r\n```\r\n\r\n### Template Selection\r\n\r\n```bash\r\n# Interactive template selector with preview\r\nclaude-statusline template\r\n\r\n# Quick template change\r\nclaude-statusline template minimal\r\nclaude-statusline template vim\r\n```\r\n\r\n\ud83d\udcd6 **[Template Gallery](TEMPLATES.md)** - Preview all available statusline formats\r\n\r\n### Pricing Updates\r\n\r\nModel prices are automatically updated from the official repository:\r\n\r\n```bash\r\nclaude-statusline update-prices\r\n```\r\n\r\n## Project Structure\r\n\r\n```\r\nclaude-statusline/\r\n\u251c\u2500\u2500 claude_statusline/ # Package directory\r\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\r\n\u2502 \u251c\u2500\u2500 cli.py # Main CLI interface\r\n\u2502 \u251c\u2500\u2500 statusline.py # Core statusline display\r\n\u2502 \u251c\u2500\u2500 daemon.py # Background processor\r\n\u2502 \u251c\u2500\u2500 templates.py # Template definitions\r\n\u2502 \u251c\u2500\u2500 config.json # Configuration\r\n\u2502 \u2514\u2500\u2500 prices.json # Model pricing\r\n\u251c\u2500\u2500 tests/ # Test suite\r\n\u251c\u2500\u2500 docs/ # Documentation\r\n\u251c\u2500\u2500 setup.py # Package setup\r\n\u251c\u2500\u2500 pyproject.toml # Modern package config\r\n\u2514\u2500\u2500 README.md # This file\r\n```\r\n\r\n## Data Files\r\n\r\n- **Source**: `~/.claude/projects/*/` - Claude Code JSONL files\r\n- **Database**: `~/.claude/data-statusline/` - Processed data\r\n - `smart_sessions_db.json` - Session database\r\n - `live_session.json` - Current session\r\n - `daemon_status.json` - Daemon status\r\n\r\n## Development\r\n\r\n### Setup Development Environment\r\n\r\n```bash\r\n# Clone repository\r\ngit clone https://github.com/ersinkoc/claude-statusline.git\r\ncd claude-statusline\r\n\r\n# Install in development mode\r\npip install -e .\r\n\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\n# Run test suite\r\npytest\r\n\r\n# Run with coverage\r\npytest --cov=claude_statusline\r\n\r\n# Run specific test\r\npytest tests/test_statusline.py\r\n```\r\n\r\n### Building the Package\r\n\r\n```bash\r\n# Install build tools\r\npip install build twine\r\n\r\n# Build package\r\npython -m build\r\n\r\n# Check package\r\ntwine check dist/*\r\n\r\n# Upload to PyPI (when ready)\r\ntwine upload dist/*\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### No Data Showing\r\n```bash\r\n# Check Claude Code data exists\r\nls ~/.claude/projects/\r\n\r\n# Rebuild database\r\nclaude-statusline rebuild\r\n\r\n# Ensure daemon is running\r\nclaude-statusline daemon --status\r\n```\r\n\r\n### Incorrect Costs\r\n```bash\r\n# Update prices\r\nclaude-statusline update-prices\r\n\r\n# Verify calculations\r\nclaude-statusline verify\r\n```\r\n\r\n### Package Issues\r\n```bash\r\n# Reinstall package\r\npip uninstall claude-statusline\r\npip install dist/claude_statusline-*.whl\r\n\r\n# Check installation\r\npip show claude-statusline\r\n```\r\n\r\n### More Help\r\n- Run `claude-statusline --help` for command help\r\n- See [CLI.md](CLI.md) for detailed documentation\r\n- Check [CLAUDE_CODE_SETUP.md](CLAUDE_CODE_SETUP.md) for Claude Code integration\r\n- Report issues on [GitHub](https://github.com/ersinkoc/claude-statusline/issues)\r\n\r\n## Documentation\r\n\r\n- [CLI Reference](CLI.md) - Complete command documentation\r\n- [Template Gallery](TEMPLATES.md) - All 20+ statusline formats\r\n- [Architecture](ARCHITECTURE.md) - System design and data flow\r\n- [Claude Code Setup](CLAUDE_CODE_SETUP.md) - Integration guide\r\n- [Contributing](CONTRIBUTING.md) - Contribution guidelines\r\n- [Changelog](CHANGELOG.md) - Version history\r\n- [Security](SECURITY.md) - Security policy\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details.\r\n\r\n## Acknowledgments\r\n\r\n- Claude Code team for the excellent development environment\r\n- Contributors and testers from the community\r\n- Built with \u2764\ufe0f for the Claude Code community\r\n\r\n## Support\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/ersinkoc/claude-statusline/issues)\r\n- **Discussions**: [GitHub Discussions](https://github.com/ersinkoc/claude-statusline/discussions)\r\n- **Documentation**: [Full CLI Reference](CLI.md)\r\n\r\n---\r\n\r\n**Current Version**: 1.3.3 | **Last Updated**: 2025-08-14 | **Package**: `claude-statusline`\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Real-time session tracking and analytics for Claude Code",
"version": "1.3.3",
"project_urls": {
"Bug Tracker": "https://github.com/ersinkoc/claude-statusline/issues",
"Changelog": "https://github.com/ersinkoc/claude-statusline/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/ersinkoc/claude-statusline/blob/main/README.md",
"Homepage": "https://github.com/ersinkoc/claude-statusline",
"Repository": "https://github.com/ersinkoc/claude-statusline"
},
"split_keywords": [
"claude",
" claude-code",
" statusline",
" monitoring",
" analytics",
" ai",
" anthropic",
" session-tracking",
" cost-tracking",
" developer-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "94235223480842b4e4acb4442f047eb635c4c69fbbf3dd418e1097ba6300aeec",
"md5": "b207d5b9fcc1da52625a5204290435e7",
"sha256": "bcff8facf44640366aafd80e87fb0a26d1713fe08623167af105061c2e8a02f2"
},
"downloads": -1,
"filename": "claude_statusline-1.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b207d5b9fcc1da52625a5204290435e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 73227,
"upload_time": "2025-08-14T17:59:33",
"upload_time_iso_8601": "2025-08-14T17:59:33.705927Z",
"url": "https://files.pythonhosted.org/packages/94/23/5223480842b4e4acb4442f047eb635c4c69fbbf3dd418e1097ba6300aeec/claude_statusline-1.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9dcf1231a554a1ef6f457ce787a7e3b7ca9961f7c639518c8bb055350ca83d4f",
"md5": "7dfbdbf0c67a01ff4ebcacbc97b7d8ed",
"sha256": "a108b7daffcef9aa8dcb7f874d767d795f8b0922321212d081ddae59e5e60b63"
},
"downloads": -1,
"filename": "claude_statusline-1.3.3.tar.gz",
"has_sig": false,
"md5_digest": "7dfbdbf0c67a01ff4ebcacbc97b7d8ed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 80713,
"upload_time": "2025-08-14T17:59:35",
"upload_time_iso_8601": "2025-08-14T17:59:35.448547Z",
"url": "https://files.pythonhosted.org/packages/9d/cf/1231a554a1ef6f457ce787a7e3b7ca9961f7c639518c8bb055350ca83d4f/claude_statusline-1.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 17:59:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ersinkoc",
"github_project": "claude-statusline",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "psutil",
"specs": [
[
">=",
"5.9.0"
]
]
}
],
"lcname": "claude-statusline"
}
JSON
