ccgarden 0.1.0__tar.gz

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

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    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

ccgarden-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

ccgarden-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  # ruff and pytest live in git-a-grip so every repo shares one copy, rather
+  # than each keeping its own `bash -c '... && git add "$@"'` wrapper.
+  - repo: https://github.com/dannybrown37/git-a-grip
+    rev: v0.2.0
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+      - id: pytest
+        args: [-q]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks

ccgarden-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

ccgarden-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Brown
+
+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.

ccgarden-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: ccgarden
+Version: 0.1.0
+Summary: Grow a tree/garden visualization from ccstats.db session history
+Project-URL: Homepage, https://github.com/dannybrown37/ccgarden
+Project-URL: Repository, https://github.com/dannybrown37/ccgarden
+Project-URL: Issues, https://github.com/dannybrown37/ccgarden/issues
+Author-email: Danny Brown <dannybrown37@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,claude-code,stats,svg,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# ccgarden
+
+Grow a garden from your local Claude Code session history.
+
+`ccgarden` reads the JSONL transcripts under `~/.claude/projects`, rolls
+them up into a small sqlite history db, and renders the result as an SVG
+tree: one growing organism that represents everything you've built with
+Claude Code on this machine.
+
+![Example garden, rendered from synthetic sample data](docs/images/garden-example.png)
+
+*(This is a dummied-up example with a few months of synthetic data across
+five repos, several models, and a handful of tools — enough to show every
+shape the renderer draws. Your own garden will look sparser at first and
+fill in as you work.)*
+
+## What each shape means
+
+| Shape | Grows with |
+|---|---|
+| **Trunk** | Total sessions, across all repos |
+| **Rings** | One per day worked; bolder rings mean busier days |
+| **Branches** | One per repo — longer branches mean more lines changed, thicker branches mean more tokens |
+| **Leaves** | One per session; more leaves means a busier repo, bigger leaves mean deeper (more turns/session) sessions |
+| **Flowers** | One per whole ratio of cache reads to cache writes |
+| **Clouds** | One per model + reasoning-effort combination used; bigger and darker clouds mean more tokens and heavier thinking |
+| **Sun** | Rises and brightens with your all-in token total (output + input + cache read + cache write) |
+| **Bushes** | One per tool (Bash, Edit, Read, ...); bigger bushes mean more calls |
+| **Sunflowers** | One per repo; taller stalks mean more prompts |
+| **Birds** | One per `cartoon` adapter that saved tokens; bigger birds mean more tokens saved. Only appears if `cartoon` is installed |
+
+Hover (or tap, on mobile) any shape for the exact numbers behind it.
+
+## Install
+
+```sh
+uv tool install ccgarden
+```
+
+(or `pipx install ccgarden`). This installs two commands: `ccgarden` and
+`ccstats`.
+
+To hack on it instead, clone the repo and run `uv sync`, which puts the
+same two commands in the project's virtualenv.
+
+## Usage
+
+```sh
+uv run ccgarden
+```
+
+This will:
+
+1. Scan `~/.claude/projects` and record today's snapshot into
+   `~/.claude/ccstats.db` (same as running `ccstats` — see below).
+2. Replay the full day-by-day history from that db into an animated
+   SVG timelapse of the garden growing.
+3. Write it to `~/.claude/ccgarden.svg` and open it in your browser
+   (add `--no-open` to skip that last step).
+
+Run it again any day and the garden picks up where it left off — new
+rings, longer branches, bigger clouds, more leaves.
+
+### `ccstats`
+
+The underlying stats engine can also be run on its own, for a
+terminal-native usage report instead of (or before) rendering a garden:
+
+```sh
+uv run ccstats                       # summarize all local session logs
+uv run ccstats --since 2026-06-01    # limit the window
+uv run ccstats --json                # machine-readable output
+uv run ccstats --record --since 2026-01-01 --until 2026-07-01  # backfill history
+```
+
+Run `uv run ccstats --help` for the full list of flags.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ccgarden-0.1.0/README.md

@@ -0,0 +1,87 @@
+# ccgarden
+
+Grow a garden from your local Claude Code session history.
+
+`ccgarden` reads the JSONL transcripts under `~/.claude/projects`, rolls
+them up into a small sqlite history db, and renders the result as an SVG
+tree: one growing organism that represents everything you've built with
+Claude Code on this machine.
+
+![Example garden, rendered from synthetic sample data](docs/images/garden-example.png)
+
+*(This is a dummied-up example with a few months of synthetic data across
+five repos, several models, and a handful of tools — enough to show every
+shape the renderer draws. Your own garden will look sparser at first and
+fill in as you work.)*
+
+## What each shape means
+
+| Shape | Grows with |
+|---|---|
+| **Trunk** | Total sessions, across all repos |
+| **Rings** | One per day worked; bolder rings mean busier days |
+| **Branches** | One per repo — longer branches mean more lines changed, thicker branches mean more tokens |
+| **Leaves** | One per session; more leaves means a busier repo, bigger leaves mean deeper (more turns/session) sessions |
+| **Flowers** | One per whole ratio of cache reads to cache writes |
+| **Clouds** | One per model + reasoning-effort combination used; bigger and darker clouds mean more tokens and heavier thinking |
+| **Sun** | Rises and brightens with your all-in token total (output + input + cache read + cache write) |
+| **Bushes** | One per tool (Bash, Edit, Read, ...); bigger bushes mean more calls |
+| **Sunflowers** | One per repo; taller stalks mean more prompts |
+| **Birds** | One per `cartoon` adapter that saved tokens; bigger birds mean more tokens saved. Only appears if `cartoon` is installed |
+
+Hover (or tap, on mobile) any shape for the exact numbers behind it.
+
+## Install
+
+```sh
+uv tool install ccgarden
+```
+
+(or `pipx install ccgarden`). This installs two commands: `ccgarden` and
+`ccstats`.
+
+To hack on it instead, clone the repo and run `uv sync`, which puts the
+same two commands in the project's virtualenv.
+
+## Usage
+
+```sh
+uv run ccgarden
+```
+
+This will:
+
+1. Scan `~/.claude/projects` and record today's snapshot into
+   `~/.claude/ccstats.db` (same as running `ccstats` — see below).
+2. Replay the full day-by-day history from that db into an animated
+   SVG timelapse of the garden growing.
+3. Write it to `~/.claude/ccgarden.svg` and open it in your browser
+   (add `--no-open` to skip that last step).
+
+Run it again any day and the garden picks up where it left off — new
+rings, longer branches, bigger clouds, more leaves.
+
+### `ccstats`
+
+The underlying stats engine can also be run on its own, for a
+terminal-native usage report instead of (or before) rendering a garden:
+
+```sh
+uv run ccstats                       # summarize all local session logs
+uv run ccstats --since 2026-06-01    # limit the window
+uv run ccstats --json                # machine-readable output
+uv run ccstats --record --since 2026-01-01 --until 2026-07-01  # backfill history
+```
+
+Run `uv run ccstats --help` for the full list of flags.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ccgarden-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "ccgarden"
+version = "0.1.0"
+description = "Grow a tree/garden visualization from ccstats.db session history"
+authors = [
+    { name = "Danny Brown", email = "dannybrown37@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = []
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["claude", "claude-code", "visualization", "svg", "stats"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/dannybrown37/ccgarden"
+Repository = "https://github.com/dannybrown37/ccgarden"
+Issues = "https://github.com/dannybrown37/ccgarden/issues"
+
+[project.scripts]
+ccgarden = "ccgarden:main"
+ccstats = "ccgarden.claude_stats:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 79
+show-fixes = true
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+  "A", "ANN", "ARG", "B", "C4", "COM", "C90",
+  "D200", "D201", "D202", "D205", "D212",
+  "E", "EM", "ERA", "EXE", "F", "FBT", "G", "I", "ICN", "ISC", "N",
+  "PGH", "PIE", "PL", "PLE", "PLR", "PLW", "PT", "PTH", "PYI", "Q",
+  "RET", "RSE", "RUF", "S", "SLF", "SIM", "TCH", "TID", "TRY", "W",
+  "UP", "YTT",
+]
+ignore = [
+    "S311",
+    "S101",
+    "I001",
+    "S113",
+    "PLR0913",
+    "PLC0415",
+    "COM812",  # conflicts with formatter
+]
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "single"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN201", "PLR2004", "ANN001", "ANN003", "ARG002", "PT019"]
+
+[tool.ruff.format]
+quote-style = "single"
+docstring-code-format = true
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.0",
+]

ccgarden-0.1.0/src/ccgarden/__init__.py

@@ -0,0 +1,61 @@
+import argparse
+import subprocess
+import webbrowser
+from pathlib import Path
+
+from ccgarden.claude_stats import DEFAULT_LOG_ROOT, print_report
+from ccgarden.data import load_garden_timeline
+from ccgarden.render import render_timeline_svg
+
+DEFAULT_DB_PATH = Path.home() / '.claude' / 'ccstats.db'
+DEFAULT_OUTPUT_PATH = Path.home() / '.claude' / 'ccgarden.svg'
+
+
+def _is_wsl() -> bool:
+    try:
+        return 'microsoft' in Path('/proc/version').read_text().lower()
+    except OSError:
+        return False
+
+
+def _open_in_browser(path: Path) -> None:
+    if _is_wsl():
+        windows_path = subprocess.run(  # noqa: S603
+            ['wslpath', '-w', str(path)],  # noqa: S607
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        # explorer.exe always exits 1 on success, so don't check the code.
+        subprocess.run(  # noqa: S603
+            ['explorer.exe', windows_path],  # noqa: S607
+            check=False,
+        )
+    else:
+        webbrowser.open(path.as_uri())
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog='ccgarden',
+        description='Grow a garden from local Claude Code session history.',
+    )
+    parser.add_argument(
+        '--no-open',
+        action='store_true',
+        help='write the SVG without opening it in a browser',
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    # print_report also records today's snapshot -- must run before the
+    # timeline is loaded, or the garden it renders is one day stale.
+    print_report([DEFAULT_LOG_ROOT], db_path=DEFAULT_DB_PATH)
+    timeline = load_garden_timeline(str(DEFAULT_DB_PATH))
+    svg = render_timeline_svg(timeline)
+    DEFAULT_OUTPUT_PATH.write_text(svg)
+    if not args.no_open:
+        _open_in_browser(DEFAULT_OUTPUT_PATH)
+    print(f'wrote {DEFAULT_OUTPUT_PATH}')