claudepod 1.1.2 → 1.2.1

package/.devcontainer/features/ccusage/README.md

@@ -0,0 +1,205 @@
+# ccusage - Claude Code Usage Analyzer
+
+A DevContainer feature that installs the ccusage CLI tool for analyzing Claude Code and Codex token usage from local JSONL files.
+
+## Overview
+
+ccusage tracks token usage and costs across daily, monthly, and session-based reports with live monitoring capabilities. This feature configures shell aliases for easy access to the tool via `npx`.
+
+## Installation
+
+Add this feature to your `.devcontainer/devcontainer.json`:
+
+```json
+{
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {},
+    "./features/ccusage": {}
+  }
+}
+```
+
+### With Custom Options
+
+```json
+{
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {},
+    "./features/ccusage": {
+      "version": "latest",
+      "shells": "both",
+      "username": "automatic"
+    }
+  }
+}
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `version` | string | `latest` | ccusage version to use (e.g., 'latest', '1.0.0') |
+| `shells` | string | `both` | Which shells to configure: `bash`, `zsh`, or `both` |
+| `username` | string | `automatic` | Container user to install for (auto-detects vscode/node/codespace) |
+
+## Usage
+
+Once installed, use the `ccusage` command from any shell:
+
+### Daily Usage Report
+```bash
+ccusage --daily
+```
+Shows token usage and costs for today.
+
+### Monthly Report
+```bash
+ccusage --monthly
+```
+Displays monthly token consumption and costs.
+
+### Live Monitoring
+```bash
+ccusage --live
+```
+Real-time monitoring of your Claude Code usage.
+
+### JSON Output
+```bash
+ccusage --json
+```
+Output data in JSON format for scripting/integration.
+
+### Compact Display
+```bash
+ccusage --compact
+```
+Minimal output for quick checks.
+
+## Features
+
+- **Beautiful Tables**: Formatted output with clear cost breakdown
+- **Multiple Models**: Supports Claude Opus, Sonnet, and other models
+- **Timezone Support**: Customize timezone and locale settings
+- **Session Tracking**: View usage by individual sessions
+- **Cost Tracking**: Accurate pricing for different models
+
+## How It Works
+
+This feature creates a shell alias that points to `npx -y ccusage@<version>`, which automatically downloads and runs the latest version of ccusage without requiring a global installation.
+
+ccusage automatically reads from Claude Code's JSONL usage logs located in:
+- `~/.claude/` (default)
+- `$CLAUDE_CONFIG_DIR` (if customized)
+
+## Advanced Options
+
+For full list of ccusage command options:
+```bash
+ccusage --help
+```
+
+## Example Configurations
+
+### Install for Specific User (zsh only)
+```json
+{
+  "features": {
+    "./features/ccusage": {
+      "username": "vscode",
+      "shells": "zsh"
+    }
+  }
+}
+```
+
+### Pin to Specific Version
+```json
+{
+  "features": {
+    "./features/ccusage": {
+      "version": "1.0.0"
+    }
+  }
+}
+```
+
+### Bash Only Installation
+```json
+{
+  "features": {
+    "./features/ccusage": {
+      "shells": "bash"
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Command Not Found
+
+If `ccusage` is not found after installation:
+
+1. **Reload your shell**:
+   ```bash
+   source ~/.bashrc  # for bash
+   source ~/.zshrc   # for zsh
+   ```
+
+2. **Check if alias is configured**:
+   ```bash
+   grep ccusage ~/.bashrc  # for bash
+   grep ccusage ~/.zshrc   # for zsh
+   ```
+
+3. **Verify npx is available**:
+   ```bash
+   npx --version
+   ```
+
+### Permission Errors
+
+If you see permission errors:
+```bash
+sudo chown -R $(whoami):$(whoami) ~/.bashrc
+sudo chown -R $(whoami):$(whoami) ~/.zshrc
+```
+
+### Network Issues
+
+If ccusage fails to download:
+- Check your internet connection
+- The tool will be cached after first successful download
+- Try running manually: `npx -y ccusage@latest --version`
+
+## Dependencies
+
+This feature requires:
+- **Node.js**: Install the `node` feature first
+- The feature automatically declares this dependency via `installsAfter`
+
+## Integration with Other Tools
+
+This tool complements:
+- **splitrail**: Real-time monitoring during active sessions
+- **ccstatusline**: Visual status display in terminal
+
+## Links
+
+- **GitHub**: https://github.com/ryoppippi/ccusage
+- **NPM**: https://www.npmjs.com/package/ccusage
+- **DevContainer Features**: https://containers.dev/features
+
+## Version History
+
+### 1.0.0
+- Initial release as DevContainer feature
+- Automatic user detection
+- Configurable shell support (bash/zsh/both)
+- Version pinning support
+- Idempotent installation
+
+## License
+
+This feature wrapper follows the same license as the underlying ccusage tool.

package/.devcontainer/features/ccusage/devcontainer-feature.json

@@ -0,0 +1,38 @@
+{
+  "id": "ccusage",
+  "version": "1.0.0",
+  "name": "ccusage - Claude Code Usage Analyzer",
+  "description": "Installs ccusage CLI tool for analyzing Claude Code token usage",
+  "maintainer": "AnExiledDev",
+  "documentationURL": "https://github.com/ryoppippi/ccusage",
+  "options": {
+    "version": {
+      "type": "string",
+      "description": "ccusage version to use (e.g., 'latest', '1.0.0')",
+      "default": "latest"
+    },
+    "shells": {
+      "type": "string",
+      "description": "Which shells to configure (bash, zsh, or both)",
+      "default": "both",
+      "enum": [
+        "bash",
+        "zsh",
+        "both"
+      ],
+      "proposals": [
+        "bash",
+        "zsh",
+        "both"
+      ]
+    },
+    "username": {
+      "type": "string",
+      "description": "Container user to install for",
+      "default": "automatic"
+    }
+  },
+  "installsAfter": [
+    "ghcr.io/devcontainers/features/node:1"
+  ]
+}

package/.devcontainer/features/ccusage/install.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+set -euo pipefail
+
+# === SETUP ===
+cleanup() {
+    # No temp files needed for this simple feature
+    :
+}
+trap cleanup EXIT
+
+# === IMPORT OPTIONS ===
+# NOTE: DevContainer converts camelCase options to UPPERCASE without underscores
+# "version" → VERSION, "shells" → SHELLS, "username" → USERNAME
+CCUSAGE_VERSION="${VERSION:-latest}"
+SHELLS="${SHELLS:-both}"
+USERNAME="${USERNAME:-automatic}"
+
+echo "[ccusage] Starting ccusage installation..."
+
+# === SOURCE NVM ===
+# Node is installed via NVM by the node feature
+if [ -f /usr/local/share/nvm/nvm.sh ]; then
+    source /usr/local/share/nvm/nvm.sh
+fi
+
+# === VALIDATE DEPENDENCIES ===
+if ! command -v npx &>/dev/null; then
+    echo "[ccusage] ERROR: npx is not available"
+    echo "  Ensure node feature is installed first"
+    echo "  NVM path: /usr/local/share/nvm/nvm.sh"
+    exit 1
+fi
+
+# === VALIDATE INPUT ===
+# Validate shells parameter
+if [[ ! "${SHELLS}" =~ ^(bash|zsh|both)$ ]]; then
+    echo "[ccusage] ERROR: shells must be 'bash', 'zsh', or 'both'"
+    echo "  Provided: ${SHELLS}"
+    exit 1
+fi
+
+# Validate version format (basic check)
+if [[ ! "${CCUSAGE_VERSION}" =~ ^[a-zA-Z0-9.-]+$ ]]; then
+    echo "[ccusage] ERROR: version contains invalid characters"
+    echo "  Provided: ${CCUSAGE_VERSION}"
+    exit 1
+fi
+
+# === DETECT USER ===
+if [ "${USERNAME}" = "auto" ] || [ "${USERNAME}" = "automatic" ]; then
+    USERNAME=""
+    for CURRENT_USER in vscode node codespace; do
+        if id -u "${CURRENT_USER}" >/dev/null 2>&1; then
+            USERNAME=${CURRENT_USER}
+            break
+        fi
+    done
+    [ -z "${USERNAME}" ] && USERNAME=root
+elif [ "${USERNAME}" = "none" ] || ! id -u "${USERNAME}" >/dev/null 2>&1; then
+    USERNAME=root
+fi
+
+echo "[ccusage] Installing for user: ${USERNAME}"
+
+# === GET USER HOME ===
+USER_HOME=$(eval echo "~${USERNAME}")
+if [ ! -d "${USER_HOME}" ]; then
+    echo "[ccusage] ERROR: Home directory not found for user ${USERNAME}"
+    exit 1
+fi
+
+# === INSTALL (CREATE ALIASES) ===
+ALIAS_CMD="alias ccusage=\"npx -y ccusage@${CCUSAGE_VERSION}\""
+
+configure_shell() {
+    local shell_rc="$1"
+    local shell_name="$2"
+
+    if [ ! -f "${shell_rc}" ]; then
+        echo "[ccusage] Creating ${shell_name} config file: ${shell_rc}"
+        sudo -u "${USERNAME}" touch "${shell_rc}"
+    fi
+
+    if grep -q "alias ccusage=" "${shell_rc}"; then
+        echo "[ccusage] ${shell_name} alias already configured. Skipping..."
+    else
+        echo "[ccusage] Adding ccusage alias to ${shell_name}"
+        echo "${ALIAS_CMD}" >> "${shell_rc}"
+        if ! chown "${USERNAME}:${USERNAME}" "${shell_rc}" 2>/dev/null; then
+            echo "[ccusage] WARNING: Could not set ownership on ${shell_rc}"
+            echo "  Fix: sudo chown ${USERNAME}:${USERNAME} ${shell_rc}"
+        fi
+    fi
+}
+
+# Configure requested shells
+if [ "${SHELLS}" = "bash" ] || [ "${SHELLS}" = "both" ]; then
+    configure_shell "${USER_HOME}/.bashrc" "bash"
+fi
+
+if [ "${SHELLS}" = "zsh" ] || [ "${SHELLS}" = "both" ]; then
+    configure_shell "${USER_HOME}/.zshrc" "zsh"
+fi
+
+# === VERIFICATION ===
+echo "[ccusage] Verifying npx can access ccusage..."
+if sudo -u "${USERNAME}" bash -c "npx -y ccusage@${CCUSAGE_VERSION} --version" &>/dev/null; then
+    echo "[ccusage] ✓ ccusage is accessible"
+else
+    echo "[ccusage] WARNING: Could not verify ccusage installation"
+    echo "  This may be due to network connectivity"
+    echo "  The alias will still work once ccusage is available"
+fi
+
+# === SUMMARY ===
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "  ccusage Installation Complete"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Configuration:"
+echo "  • User: ${USERNAME}"
+echo "  • Version: ${CCUSAGE_VERSION}"
+echo "  • Shells: ${SHELLS}"
+echo ""
+echo "Usage:"
+echo "  ccusage --daily      # Daily usage report"
+echo "  ccusage --monthly    # Monthly report"
+echo "  ccusage --live       # Live monitoring"
+echo "  ccusage --help       # Full options"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"