AI Workflower

Real-time usage monitoring for Claude Code

Stop guessing, start planning. Know exactly where you stand with your Claude Code usage — and get alerted before you hit limits.

Features

• Real-time Usage Dashboard — Visual progress bars showing session and weekly usage
• Auto-refresh — Configurable polling intervals (1, 5, or 15 minutes)
• Live Countdown Timers — See exactly when your limits reset
• Discord Alerts — Get notified at 50%, 75%, and 90% usage thresholds
• Alert Management — Snooze alerts, test webhooks, configure thresholds
• Usage History — Track daily usage trends over time
• Docker Deployment — Single command to run
• Linux-first — Built for Linux developers

Prerequisites

1. Claude Code Installed & Logged In

AI Workflower reads your Claude Code OAuth credentials to fetch usage data.

1. Install Claude Code — Follow the official installation guide
2. Log in to Claude Code — Run claude in your terminal and complete authentication
3. Verify credentials exist:

ls ~/.claude/.credentials.json

Note: AI Workflower does NOT store or transmit your credentials. It only reads the local OAuth token to fetch your usage data from Anthropic's API.

2. Docker (Recommended) OR Python 3.11+

Option A: Docker

• Docker Engine 20.10+
• Docker Compose V2

Option B: Local Development

• Python 3.11+
• Node.js 18+
• uv package manager

Quick Start

Docker (Recommended)

# Clone the repository
git clone https://github.com/StiensWout/AI-Workflower.git
cd AI-Workflower

# Copy and configure environment
cp .env.example .env

# Start the application
docker compose up -d

# Open http://localhost:8080

Local Development

# Clone the repository
git clone https://github.com/StiensWout/AI-Workflower.git
cd AI-Workflower

# Install dependencies
make install

# Start development servers
make dev

# Open http://localhost:5173

Docker Deployment

Linux Permission Setup

On Linux, set your user/group IDs for proper volume permissions:

echo "HOST_UID=$(id -u)" >> .env
echo "HOST_GID=$(id -g)" >> .env

Configuration

Variable	Default	Description
PORT	8080	Dashboard port
CLAUDE_LOGS_HOST	~/.claude	Path to Claude directory
HOST_UID / HOST_GID	1000	User/group ID for volumes
DISCORD_WEBHOOK_URL	—	Discord webhook for alerts
ALERT_INFO	50	Info threshold (%)
ALERT_WARNING	75	Warning threshold (%)
ALERT_CRITICAL	90	Critical threshold (%)

See .env.example for all options.

Management Commands

docker compose up -d       # Start in background
docker compose down        # Stop services
docker compose logs -f     # Follow logs
docker compose restart     # Restart services

Discord Alerts

Get notified on Discord when your usage approaches limits.

Setup

1. Create a Discord webhook:

   • Server Settings → Integrations → Webhooks → New Webhook
   • Copy the URL

2. Configure:

   • Add to .env: DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
   • Or use the "Alert Settings" panel in the dashboard

3. Test: Click "Send Test Alert" in the dashboard

Alert Levels

Level	Threshold	Color
Info	50%	Blue
Warning	75%	Yellow
Critical	90%	Red

CLI Usage

# View current usage
uv run ai-workflower

# Watch mode
uv run ai-workflower --watch

# JSON output
uv run ai-workflower --json

Troubleshooting

"Credentials not found"

Claude Code is not authenticated:

claude  # Follow prompts to log in

Permission denied (Docker on Linux)

echo "HOST_UID=$(id -u)" >> .env
echo "HOST_GID=$(id -g)" >> .env
docker compose down && docker compose up -d

No data displayed

# Verify Claude credentials exist
ls -la ~/.claude/.credentials.json

# Check Docker logs
docker compose logs backend

Privacy & Security

• Local only — Runs entirely on your machine
• No data collection — Nothing is sent anywhere except Anthropic's API
• Credentials stay local — OAuth tokens are never stored or transmitted

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

License

MIT

---