dashboard-for-claude-code 0.1.0__tar.gz

dashboard_for_claude_code-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Something is broken or behaving unexpectedly
+labels: bug
+---
+
+## What happened
+
+<!-- A clear description of the bug. -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+## Environment
+
+- OS:
+- Python version (`python3 --version`):
+- Install method (clone + uv / pipx / uvx):
+- Claude Code version (from a session, or `claude --version`):
+
+## Logs / JSONL snippet (optional)
+
+<!--
+If the bug involves parsing, a REDACTED snippet of the relevant session JSONL
+helps a lot. Remove file paths, prompt text, and anything personal first —
+see CONTRIBUTING.md.
+-->

dashboard_for_claude_code-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/heyuehuan/dashboard-for-claude-code/security/advisories/new
+    about: Please report security issues privately — do not open a public issue.

dashboard_for_claude_code-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+labels: enhancement
+---
+
+## Problem
+
+<!-- What are you trying to do that the dashboard doesn't support today? -->
+
+## Proposed solution
+
+<!-- What would you like to happen? Sketches/mockups welcome. -->
+
+## Alternatives considered
+
+## Notes
+
+<!--
+Keep in mind the project's constraints: local-first, read-only over
+~/.claude/projects, no external network calls by default, vanilla JS UI
+with no build step.
+-->

dashboard_for_claude_code-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## What & why
+
+<!-- Summary of the change and the motivation. Link related issues. -->
+
+## Checklist
+
+- [ ] `uv run --group dev pytest` passes
+- [ ] `uv run --group dev ruff check .` passes
+- [ ] Stays local-first and read-only (no writes to `~/.claude`, no network
+      calls that aren't strictly opt-in)
+- [ ] No personal data in the diff (paths, prompts, real project names)
+- [ ] Tests added/adjusted for parsing, pricing, or export changes

dashboard_for_claude_code-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      # init and analyze must run the same version, so bump them in one PR.
+      # Split across two PRs, each fails: "Loaded a configuration file for
+      # version 'X', but running version 'Y'".
+      codeql-action:
+        patterns:
+          - "github/codeql-action*"
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly

dashboard_for_claude_code-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Check lockfile is up to date
+        run: uv lock --check
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Ruff lint
+        run: uv run --group dev ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }} --group dev
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} --group dev pytest -q

dashboard_for_claude_code-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,100 @@
+name: Publish
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no API token is stored.
+# The pending publisher registered on PyPI must match this file's name
+# (publish.yml), the environment below (pypi), and this repository.
+#
+# To cut a release: bump `version` in pyproject.toml, merge to main, then
+#   git tag v0.1.0 && git push origin v0.1.0
+# PyPI versions are immutable — a tag can never be republished.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  # Re-run the full test matrix against the exact tagged commit. CI on main is
+  # not enough: the tag is what ships, and an unpublishable build is far cheaper
+  # to catch here than after a version number is permanently burned.
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }} --group dev
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} --group dev pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      # A tag that disagrees with pyproject.toml would publish a version nobody
+      # asked for, under a number that can never be reused. Fail before building.
+      - name: Check tag matches pyproject version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          project="$(uv version --short)"
+          if [ "$tag" != "$project" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME implies version '$tag' but pyproject.toml declares '$project'."
+            exit 1
+          fi
+          echo "Publishing version $project"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Verify artifact metadata
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Must match the environment name on the PyPI pending publisher. Also a
+    # useful place to hang a required reviewer if you ever want manual sign-off.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dashboard-for-claude-code
+
+    # id-token lets the runner mint the short-lived OIDC token PyPI trades for
+    # an upload grant. This is the whole reason no secret needs to exist.
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dashboard_for_claude_code-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,61 @@
+name: Security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Mondays 04:27 UTC — re-scan against newly disclosed patterns/CVEs.
+    - cron: "27 4 * * 1"
+
+# Least privilege by default; only the job that needs more opts in below.
+permissions:
+  contents: read
+
+concurrency:
+  group: security-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  secret-scan:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    steps:
+      # Full history so gitleaks scans every commit, not just the tip.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  bandit:
+    name: Python SAST (bandit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --group security
+      # bandit is pinned + hash-verified via uv.lock (security group).
+      - name: Run bandit
+        run: uv run --group security bandit -c pyproject.toml -r src/claude_dashboard scripts
+
+  codeql:
+    name: CodeQL (SAST)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write # required to upload results to the Security tab
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
+        with:
+          languages: python
+          queries: security-extended
+      - name: Analyze
+        uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3

dashboard_for_claude_code-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Runtime data — contains personal metadata (project paths, session timestamps, usage stats)
+data/
+
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Test coverage artifacts (regenerated by coverage.py / pytest-cov)
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Claude Code local state (memory, settings, plans)
+.claude/
+
+# Remote publish — generated by scripts/export.py, not source-controlled
+remote_public/data/
+remote_public/src/
+remote_public/index.html
+
+# Refresh state
+logs/
+.last_data_hash
+
+# Local deploy config & personal launch agent — keep only the .example templates
+scripts/deploy.env
+scripts/*.plist
+!scripts/*.plist.example
+
+# OS
+.DS_Store
+
+# Local-only maintainer / agent notes (migration logs, origin pointer, review
+# notes) — never published to the public repo
+CLAUDE/
+CLAUDE_REVIEW/
+
+# AI assistant local files — instruction/rule files and chat history from coding
+# assistants. Kept local so the public repo carries no assistant scaffolding.
+# (The .claude/ state dir is already ignored above.)
+CLAUDE.md
+CLAUDE.local.md
+GEMINI.md
+# AGENTS.md is sometimes intentionally shared — un-ignore it if you want to publish it
+AGENTS.md
+.cursor/
+.cursorrules
+.cursorignore
+.windsurf/
+.windsurfrules
+.aider*
+.continue/
+.clinerules
+.roo/
+.github/copilot-instructions.md

dashboard_for_claude_code-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## [0.1.0] — 2026-07-08
+
+### Added
+- Initial release.
+- CLI flags on the entrypoint: `--help`, `--version`, and `--host`/`--port`
+  (which take precedence over `DASHBOARD_HOST`/`DASHBOARD_PORT`). Previously
+  any argument was silently ignored and the server just started.
+- Read-only local dashboard for browsing Claude Code usage: projects, sessions,
+  cost/token breakdowns, tool-use stats, and per-session timelines.
+- SQLite-backed scan cache (`data/usage.db`); rescans on startup and on-demand
+  via `POST /api/refresh`.
+- Optional token auth (`DASHBOARD_AUTH_TOKEN`) with `HttpOnly`+`SameSite=strict`
+  cookie and constant-time comparison.
+- Binds to `127.0.0.1` by default; set `DASHBOARD_HOST=0.0.0.0` to expose on the LAN.
+- DNS-rebinding protection: Host-header allowlist when bound to loopback.
+- Cookie `secure` flag enabled automatically for non-localhost deployments.
+- CI on Python 3.11–3.13, plus ruff lint and lockfile checks.
+- Security scanning in CI: gitleaks (secret scanning), bandit (Python SAST),
+  and CodeQL. Dev/security tooling lives in opt-in dependency groups, so a plain
+  `uv sync` installs runtime dependencies only.
+- Demo data generator (`scripts/demo_data.py`) for screenshots and UI exploration.
+- Optional prune on refresh (`POST /api/refresh?prune=true`) to drop sessions
+  whose transcript was deleted from disk; by default history is kept.
+- Community files: code of conduct, issue/PR templates, dependabot config.
+
+### Fixed
+- Static export now redacts home-directory paths in dict keys too —
+  `settings.json` previously leaked absolute paths even with
+  `DASHBOARD_REDACT_HOME=1` (this also fixes settings lookups in remote mode).
+- A transcript deleted mid-scan no longer aborts the background refresh.
+- Default DB path for installed (pipx/uvx) packages now uses a per-user data
+  dir instead of a directory inside the virtualenv.
+- Host-header guard now parses bracketed IPv6 hosts correctly and rejects
+  empty `Host` headers.
+- SQLite cache uses WAL mode and a busy timeout for safer concurrent
+  reads during background scans.
+- Future Opus model ids no longer silently match legacy (3×) pricing; unmatched
+  models are surfaced as unknown instead.
+- `scripts/set_summaries.py` and `scripts/session_digest.py` follow
+  `DASHBOARD_DB` so summaries land next to the database actually in use.
+- Hidden projects remain reachable via a direct detail link.

dashboard_for_claude_code-0.1.0/CLAUDE_README.md

@@ -0,0 +1,136 @@
+# Claude Instructions — Dashboard for Claude Code
+
+This file is written for Claude (AI assistant / Claude Code agent). Follow the steps below when a user asks you to set up, run, or configure this project. Do not skip steps or assume they have already been completed unless the user confirms.
+
+---
+
+## Step 1 — Install dependencies
+
+```bash
+uv sync
+```
+
+Confirm it exits without errors before proceeding.
+
+---
+
+## Step 2 — Start the dashboard locally
+
+```bash
+uv run python -m claude_dashboard
+```
+
+The server starts at **http://localhost:8042**. On first run, all sessions are parsed in the background — the UI appears immediately and fills in as scanning completes. Tell the user to open that URL and confirm they can see the dashboard before continuing.
+
+---
+
+## Step 3 — Ask the user about session summaries
+
+Once the dashboard is confirmed running, ask the user:
+
+> "The dashboard can show a one- or two-sentence summary on each session card. Would you like me to generate summaries for sessions that don't have one yet?"
+
+**Before they agree, state the following clearly:**
+
+- Generating summaries **uses your Claude Code agent tokens** — the same budget as any other Claude Code session.
+- Each batch reads session content (first prompt, last assistant response, tools used) and writes a short summary. This is done locally; no data leaves your machine.
+- If you have many unsummarized sessions this may take several rounds and could be **slow or cost more tokens than expected**. You can run it in batches and stop at any time.
+- Summaries are stored in `data/session_summary.json` and picked up on the next dashboard refresh — no server restart needed.
+
+If the user says no, stop here. If they say yes, continue to Step 4.
+
+---
+
+## Step 4 — Generate and apply session summaries
+
+### 4a. Check how many sessions need summaries
+
+```bash
+python scripts/session_digest.py 1 --offset 0
+```
+
+This prints the total count of sessions missing a summary. Show it to the user so they can decide how many to process at once. A reasonable batch size is 8 (the default).
+
+### 4b. Read the digests
+
+Run the digest script to see the batch:
+
+```bash
+python scripts/session_digest.py [N] [--offset M]
+```
+
+- `N` — number of sessions to summarize in this batch (default 8; use a smaller number like 3–5 if the sessions are long or you want to keep token use low)
+- `--offset M` — skip the first M sessions (use to process later batches)
+
+Read the printed output carefully. Each block contains:
+- `SESSION_ID` — the ID you must key the summary to
+- `FIRST_PROMPT` / `COMPACT_SUMMARY` / `LAST_ASSISTANT` — context for writing the summary
+- Project name, branch, cost, tools used, duration
+
+### 4c. Write the summaries
+
+For each session in the digest, write a **one- or two-sentence summary** that describes what the session accomplished. Be specific and factual — avoid generic phrases. Examples of good summaries:
+
+- "Refactored auth middleware to fix session token storage; added integration tests."
+- "Debugged a race condition in the job queue; traced to missing lock around queue.pop()."
+- "Added CSV export to the billing report page and wired it to the existing API endpoint."
+
+Produce a JSON object:
+
+```json
+{
+  "SESSION_ID_1": "Summary text here.",
+  "SESSION_ID_2": "Summary text here."
+}
+```
+
+### 4d. Apply the summaries
+
+Pipe the JSON to `set_summaries.py`:
+
+```bash
+echo '{"SESSION_ID_1": "...", "SESSION_ID_2": "..."}' | python scripts/set_summaries.py
+```
+
+Or write it to a temp file and pass it:
+
+```bash
+python scripts/set_summaries.py /tmp/summaries.json
+```
+
+The script prefixes each entry with `[Claude Summary]` (unless already present) and merges it into `data/session_summary.json`. It prints a confirmation line showing how many were merged.
+
+### 4e. Refresh the dashboard
+
+Tell the user to click **Refresh** in the dashboard header, or trigger it via the API:
+
+```bash
+curl -s -X POST http://localhost:8042/api/refresh
+```
+
+Summaries will now appear on the relevant session cards.
+
+### 4f. Repeat for more batches (if needed)
+
+The digest lists only sessions that are still **missing** a summary, so once a
+batch is applied those sessions drop out of the list. To process the next
+batch, run the same command again **without changing the offset**:
+
+```bash
+python scripts/session_digest.py 8    # next batch — offset stays 0
+```
+
+Do **not** increment `--offset` between applied batches — that would skip
+sessions that still need summaries. Use `--offset` only to peek ahead at later
+sessions without summarizing the earlier ones.
+
+Ask the user after each batch whether to continue.
+
+---
+
+## Notes
+
+- You can stop summarizing at any time — summaries already written are saved.
+- If `data/session_summary.json` does not exist yet, `set_summaries.py` creates it.
+- To override the summary file location: `DASHBOARD_SUMMARY_FILE=/path/to/file python scripts/set_summaries.py ...`
+- The dashboard never modifies `~/.claude/projects/` — all writes go to `data/`.

dashboard_for_claude_code-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in
+this project a harassment-free experience for everyone, regardless of age,
+body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community and the project
+- Showing empathy toward other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and unwelcome sexual attention
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening a GitHub issue or contacting the maintainers via the
+repository. All complaints will be reviewed and investigated promptly and
+fairly. Maintainers are obligated to respect the privacy and security of the
+reporter of any incident.
+
+Maintainers who do not follow or enforce the Code of Conduct may face
+temporary or permanent repercussions as determined by the project leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
+available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.

dashboard_for_claude_code-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Bug reports, docs fixes, and code changes are all welcome.
+
+## Getting started
+
+```bash
+uv sync --all-groups                     # runtime + dev tools (pytest, ruff) + security (bandit)
+uv run python -m claude_dashboard        # http://localhost:8042
+uv run --group dev pytest -v             # run the tests
+```
+
+> A plain `uv sync` installs runtime dependencies only (so end users who just want
+> to run the dashboard stay lean). Contributors need `--all-groups` to get the test,
+> lint, and security tooling.
+
+## Guidelines
+
+- **Stay local-first and read-only.** This tool must never modify a user's logs
+  or send data off their machine by default. Do not submit PRs that break this
+  rule without making it strictly opt-in.
+- **No personal or sensitive data in commits.** Don't commit anything from
+  `data/`, `logs/`, `remote_public/`, or a real `scripts/deploy.env` — these are
+  gitignored. Use the synthetic fixtures in `tests/fixtures/` for tests.
+- **Match the surrounding style.** The code favors small, dependency-light,
+  readable modules. The UI is intentionally vanilla JS + Chart.js — no build step.
+- **Add tests** for parsing and pricing changes; those are the parts most likely
+  to regress.
+
+## Pull requests
+
+1. Fork and create a feature branch.
+2. Make your change, add/adjust tests, and run `uv run --group dev pytest`.
+3. Open a PR describing the change and the motivation.
+
+## Reporting bugs
+
+Open an issue with steps to reproduce. If it involves parsing, a **redacted**
+snippet of the relevant JSONL (with paths and prompt text removed) is very helpful.
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).

dashboard_for_claude_code-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The dashboard-for-claude-code contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.