Add Docker support with workflows and Compose files

Introduced Docker configuration, including a Dockerfile, GitHub Action workflow for automatic builds and pushes, and Docker Compose files for running locally or with prebuilt images. Updated README to document Docker setup and usage options.

Author: alexjcoles

.github/workflows/docker.yml

@@ -0,0 +1,56 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches: [ main, docker ]
+  pull_request:
+    branches: [ main ]
+  release:
+    types: [ published ]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Extract metadata
+      id: meta
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+        tags: |
+          type=ref,event=branch
+          type=ref,event=pr
+          type=semver,pattern={{version}}
+          type=semver,pattern={{major}}.{{minor}}
+          type=raw,value=latest,enable={{is_default_branch}}
+
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        push: true
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max

Dockerfile

@@ -0,0 +1,33 @@
+# Use official Python runtime as base image
+FROM python:3.9-slim
+
+# Set working directory in the container
+WORKDIR /app
+
+# Install Node.js and npm for ccusage CLI tool
+RUN apt-get update && apt-get install -y \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Node.js 18.x
+RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+    && apt-get install -y nodejs
+
+# Install ccusage globally
+RUN npm install -g ccusage
+
+# Copy Python requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Create the directory structure that ccusage expects
+RUN mkdir -p "/root/.claude"
+
+# Copy the Python script
+COPY ccusage_monitor.py .
+
+# Make the script executable
+RUN chmod +x ccusage_monitor.py
+
+# Set the entrypoint to run the monitor
+ENTRYPOINT ["python", "./ccusage_monitor.py"]

README.md

@@ -55,8 +55,35 @@ A beautiful real-time terminal monitoring tool for Claude AI token usage. Track
 
 ## 🚀 Installation
 
-### Prerequisites
+### Method 1: Docker (Recommended for non-technical users)
 
+**Prerequisites:**
+- Docker and Docker Compose installed on your system
+
+**Super Simple Setup:**
+
+```bash
+# Clone the repository
+git clone https://github.com/amphora/Claude-Code-Usage-Monitor.git
+cd Claude-Code-Usage-Monitor
+
+# Run with pre-built image (no build time!)
+docker-compose up
+
+# Or run with custom options
+docker-compose run claude-monitor --plan max5 --timezone US/Eastern
+```
+
+**Development Setup (build locally):**
+
+```bash
+# Build and run locally
+docker-compose -f docker-compose.local.yml up --build
+```
+
+### Method 2: Local Installation
+
+**Prerequisites:**
 1. **Python 3.6+** installed on your system
 2. **pytz** Python package:
    ```bash
@@ -67,7 +94,7 @@ A beautiful real-time terminal monitoring tool for Claude AI token usage. Track
    npm install -g ccusage
    ```
 
-### Quick Setup
+**Quick Setup:**
 
 ```bash
 # Clone the repository

docker-compose.local.yml

@@ -0,0 +1,14 @@
+services:
+  claude-monitor:
+    build: .
+    container_name: claude-usage-monitor-local
+    stdin_open: true
+    tty: true
+    # Mount the host's Claude Code data directory (contains JSONL files)
+    volumes:
+      - "${HOME}/.claude:/root/.claude:ro"
+    environment:
+      - HOME=/root
+    # Default arguments - users can override with docker-compose run
+    command: ["--plan", "pro"]
+    # Example: docker-compose -f docker-compose.local.yml run claude-monitor --plan max5

docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  claude-monitor:
+    image: ghcr.io/amphora/claude-code-usage-monitor:latest
+    container_name: claude-usage-monitor
+    stdin_open: true
+    tty: true
+    # Mount the host's Claude Code data directory (contains JSONL files)
+    volumes:
+      - "${HOME}/.claude:/root/.claude:ro"
+    environment:
+      - HOME=/root
+    # Default arguments - users can override with docker-compose run
+    command: ["--plan", "pro"]
+    # Example: docker-compose run claude-monitor --plan max5 --timezone US/Eastern
+    # To build locally instead: docker-compose -f docker-compose.local.yml up

requirements.txt

@@ -0,0 +1 @@
+pytz>=2021.1