vibe-clock-setup

name	vibe-clock-setup
description	Set up vibe-clock to track AI coding agent usage (Claude Code, Codex, OpenCode) and display SVG stats on a GitHub profile README.
license	MIT
compatibility	["claude-code","codex-cli","opencode"]
metadata	{"version":"0.1.0","author":"dexhunter","repository":"https://github.com/dexhunter/vibe-clock"}
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep","WebFetch"]

vibe-clock Setup

You are setting up vibe-clock, a CLI tool that tracks AI coding agent usage across Claude Code, Codex, and OpenCode, then displays SVG visualizations on a GitHub profile README.

Architecture

Local machine                  GitHub
─────────────                  ──────
~/.claude/                     Gist (vibe-clock-data.json)
~/.codex/          ──push──▶        │
~/.local/share/opencode/       Actions (daily cron)
                                    │
                               fetch gist → generate SVGs → commit to profile repo

Two-stage pipeline:

1. Local: vibe-clock share previews a seven-complete-day allowlist, asks for explicit consent, and creates a public GitHub Gist. Later vibe-clock push runs update that share.
2. Remote: A GitHub Actions workflow in the user's <username>/<username> profile repo fetches the gist, generates SVGs via vibe-clock render --from-json, and commits them.

Prerequisites

• Python 3.10+
• A GitHub Classic Personal Access Token (PAT) with gist scope (fine-grained tokens do NOT support gists)
• At least one supported agent installed: Claude Code (~/.claude/), Codex (~/.codex/), or OpenCode (~/.local/share/opencode/)
• A GitHub profile repo (<username>/<username>) with a README.md

Step 1: Install vibe-clock

pip install git+https://github.com/dexhunter/vibe-clock.git

Or with uv:

uv tool install git+https://github.com/dexhunter/vibe-clock.git

Verify the installation:

vibe-clock --version

Step 2: Initialize configuration

vibe-clock init

This will:

• Auto-detect which agents are available on the machine
• Prompt for a GitHub PAT (Classic token with gist scope)
• Write config to ~/.config/vibe-clock/config.toml

If the user already has a GITHUB_TOKEN environment variable, note that the TOML config token takes precedence when set. If the env var token lacks gist scope, make sure to enter the correct token during init.

Step 3: Verify local data collection

vibe-clock summary

This shows a terminal table with session counts, total time, token usage, favorite model, and peak hour. If no data appears, check that agent data directories exist and contain session files.

Step 4: Explicitly share safe stats to GitHub Gist

First do a dry run to preview what will be pushed:

vibe-clock push --dry-run

Verify the output contains only session counts, active days, known agents, and normalized model families. Then opt in:

vibe-clock share

This previews the data again and asks for confirmation before creating a public gist named vibe-clock-data.json. Note the gist ID printed — it is automatically saved to the config file.

If an older release already configured a Gist, share fails closed. Run vibe-clock unshare to delete the legacy Gist and its revisions, then run share and update the repository secret with the new Gist ID.

Daily activity, message counts, token counts, time patterns, and anonymous project aliases are off by default. Enable only what the user requests, for example:

vibe-clock share --daily-activity --token-counts

To retrieve the gist ID later:

grep gist_id ~/.config/vibe-clock/config.toml

Step 5: Set up GitHub Actions in the profile repo

The user's profile repo is <username>/<username> (e.g., dexhunter/dexhunter).

5a: Add repository secret

Go to the profile repo → Settings → Secrets and variables → Actions → New repository secret:

• Name: VIBE_CLOCK_GIST_ID
• Value: the gist ID from Step 4

5b: Create the workflow file

Create .github/workflows/vibe-clock.yml in the profile repo:

name: Update Vibe Clock Stats

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dexhunter/vibe-clock@main
        with:
          gist_id: ${{ secrets.VIBE_CLOCK_GIST_ID }}

5c: Add SVGs to README.md

Add this section to the profile repo's README.md:

<h2 align="center"> Vibe Clock </h2>

<p align="center">
  <img src="images/vibe-clock-card.svg" alt="Vibe Clock Stats" />
</p>
<p align="center">
  <img src="images/vibe-clock-donut.svg" alt="Model Usage" />
</p>

Available chart types: card, heatmap, donut, bars, token_bars, hourly, weekly.

Step 6: Trigger the workflow

Go to the profile repo → Actions tab → "Update Vibe Clock Stats" → Run workflow.

Or if the user has a gh CLI token with workflow permissions:

gh workflow run vibe-clock.yml --repo <username>/<username>

Ongoing Usage

• Run vibe-clock push locally whenever you want to update stats (e.g., daily via cron or manually)
• The GitHub Actions workflow runs daily at midnight UTC and regenerates SVGs automatically
• To update stats on demand: push locally, then trigger the workflow
• Run vibe-clock unshare to delete the public Gist and disable future public updates. Existing SVG commits in the profile repository are separate and must be removed there if needed.

Configuration Reference

Config file: ~/.config/vibe-clock/config.toml

[general]
default_days = 30
theme = "dark"

[paths]
claude_code = "~/.claude"
codex = "~/.codex"
opencode = "~/.local/share/opencode"

[github]
token = ""
gist_id = ""

[agents]
enabled = ["claude_code", "codex", "opencode"]

[privacy]
exclude_projects = []
exclude_date_ranges = []
anonymize_projects = true
public_sharing_enabled = false
public_days = 7
share_daily_activity = false
share_message_counts = false
share_token_counts = false
share_time_patterns = false
share_project_aliases = false

Environment variable overrides (used when TOML value is empty): GITHUB_TOKEN, VIBE_CLOCK_GIST_ID, VIBE_CLOCK_DAYS.

Privacy

Nothing leaves the machine until vibe-clock share is confirmed. The default payload is allowlisted to sessions, active days, known agents, and normalized model families. Never pushed: paths, real project names, prompts, responses, code, git info, session IDs, host data, durations, raw timestamps, or exact model IDs. Use --dry-run to verify the exact payload before sharing.

Troubleshooting

• vibe-clock: command not found: Ensure pip/uv installed it globally. Try uv tool install --force git+https://github.com/dexhunter/vibe-clock.git.
• Push fails with 401: Token likely lacks gist scope. Must be a Classic PAT, not fine-grained.
• Push fails with connection error: If behind a SOCKS proxy (ALL_PROXY), vibe-clock already uses trust_env=False to bypass it.
• SVGs don't render in GitHub README: GitHub caches aggressively. Wait a few minutes or hard-refresh. Ensure SVGs use web-safe fonts (Arial, Helvetica).
• No sessions found: Check that agent data directories exist (~/.claude/projects/, ~/.codex/sessions/, ~/.local/share/opencode/storage/).