agent-decoder 0.3.2__tar.gz

agent_decoder-0.3.2/.editorconfig

@@ -0,0 +1,30 @@
+# EditorConfig — https://editorconfig.org
+# Keeps indentation and line endings consistent across editors.
+# Soft style hint: aim for 80–100 char lines in prose and code where reasonable;
+# no hard max-line-length is enforced here (let ruff/prettier handle that).
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+# Python — 4-space indent per PEP 8
+[*.py]
+indent_size = 4
+
+# TypeScript / React / styles / JSON / YAML / Markdown — 2-space indent
+[*.{ts,tsx,js,jsx,css,scss,json,yml,yaml,md}]
+indent_size = 2
+
+# Markdown often relies on trailing whitespace for hard line breaks
+[*.md]
+trim_trailing_whitespace = false
+
+# Makefiles require literal tabs for recipe lines
+[Makefile]
+indent_style = tab

agent_decoder-0.3.2/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# CODEOWNERS for Clau-Decode
+#
+# GitHub uses this file to auto-request reviews on pull requests.
+# The last matching pattern for a given file wins, so order matters.
+# Docs: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-security/customizing-your-repository/about-code-owners
+
+* @Comradery64

agent_decoder-0.3.2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,20 @@
+name: Bug report
+description: Report something that's broken or behaving unexpectedly.
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Describe the bug. Steps to reproduce, expected behavior, and logs are helpful but optional.
+      placeholder: When I click X, the app does Y instead of Z.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs / output
+      description: Paste any tracebacks, console output, or errors (optional).
+      render: shell

agent_decoder-0.3.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions and general discussion
+    url: https://github.com/Comradery64/Clau-Decode/discussions
+    about: For usage questions, ideas in flux, or anything that isn't a clear bug or feature request, please use Discussions.

agent_decoder-0.3.2/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,13 @@
+name: Feature request
+description: Suggest a new feature, enhancement, or improvement.
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What do you want?
+      description: Describe the problem or feature. Don't worry about format — just explain what you're looking for.
+      placeholder: "It would be great if I could…"
+    validations:
+      required: true

agent_decoder-0.3.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,44 @@
+<!--
+Thanks for the PR! Fill out the sections below. Delete any that don't apply.
+Title should follow Conventional Commits (feat:, fix:, chore:, docs:, refactor:, test:, ci:).
+-->
+
+## Summary
+
+<!-- One or two sentences: what does this PR do? -->
+
+## Motivation
+
+<!-- Why are we making this change? Link the issue this PR closes:
+     Closes #123
+-->
+
+## Changes
+
+<!-- Bullet list of the meaningful changes. Avoid restating the diff line-by-line. -->
+
+-
+
+## Screenshots
+
+<!-- For UI changes, drop before/after screenshots or short clips here.
+     Delete this section if not applicable. -->
+
+## Testing
+
+<!-- What did you run, and what was the result?
+
+```
+make test
+cd frontend && npm test
+```
+-->
+
+## Checklist
+
+- [ ] Tests pass locally (`make test` and `cd frontend && npm test`)
+- [ ] `ruff` is clean (`uv run ruff check .` and `uv run ruff format --check .`)
+- [ ] TypeScript builds (`cd frontend && npm run build`)
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` if user-visible
+- [ ] Docs updated if behavior, CLI flags, or config changed
+- [ ] No telemetry, no remote network calls — data stays on the user's machine

agent_decoder-0.3.2/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+updates:
+  # Python dependencies (pyproject.toml at the repo root)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore"
+
+  # Frontend dependencies (frontend/package.json)
+  - package-ecosystem: "npm"
+    directory: "/frontend"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore"
+
+  # GitHub Actions workflow pins
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore"

agent_decoder-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    name: Python (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Install ruff
+        # Pinned (and kept in lockstep with .pre-commit-config.yaml's ruff rev) so
+        # CI lint/format results can't drift when a new ruff release changes default
+        # rules or formatting. Bump both together intentionally.
+        run: uv pip install ruff==0.15.12
+
+      - name: Lint (ruff check)
+        run: uv run ruff check .
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check .
+
+      - name: Tests (pytest with coverage)
+        # pyproject's [tool.pytest.ini_options] addopts already enables
+        # --cov=clau_decode; append an XML report for Codecov upload.
+        run: uv run pytest --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+  frontend:
+    name: Frontend
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type-check (tsc --noEmit)
+        run: npx tsc --noEmit
+
+      - name: Build (vite)
+        run: npm run build
+
+      - name: Tests (vitest)
+        run: npm test

agent_decoder-0.3.2/.github/workflows/publish.yml

@@ -0,0 +1,67 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches package version
+        # __init__.py is the single source of truth (see its own header
+        # comment). A mismatched tag would publish the wrong version to
+        # PyPI, where releases are immutable and can only be yanked, not
+        # deleted or overwritten.
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(grep -oP '(?<=^__version__ = ")[^"]+' src/clau_decode/__init__.py)"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag v$TAG_VERSION does not match __version__ ($PKG_VERSION)"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agent-decoder/
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC) — no stored API token
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

agent_decoder-0.3.2/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.venv*/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Databases / scratch
+*.db
+*.tmp
+
+# Node
+node_modules/
+frontend/node_modules/
+frontend/dist/
+
+# Worktrees
+.worktrees/
+
+# OS / editor cruft
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+.idea/
+.vscode/
+
+# Local secrets — never commit
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+secrets.*
+
+# Session-edit safety backups (created by --enable-edit before each write)
+*.bak.*.jsonl
+
+# Demo fixtures, --demo runtime state, and the VHS recording pipeline are
+# local-only — useful for producing screen recordings but not part of the
+# published source. Keep them on disk, just out of git.
+demo-data/
+demo-reel/
+
+# Keep the built static assets — they ship with the package
+!src/clau_decode/static/

agent_decoder-0.3.2/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# Pre-commit hooks for clau-decode.
+# Install once with `pre-commit install`; run on demand with `pre-commit run --all-files`.
+# pre-commit autoupdate will refresh these revs.
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        files: ^frontend/.*\.(ts|tsx|css|md|json)$

agent_decoder-0.3.2/ARCHITECTURE.md

@@ -0,0 +1,166 @@
+# Architecture
+
+This document describes the internal architecture of `clau-decode`. It
+complements [`README.md`](README.md) (user-facing) with the technical detail a
+contributor or reviewer needs to navigate the code.
+
+## Overview
+
+Clau-Decode is a single-process, local-first application. A FastAPI server
+(uvicorn, bound to `127.0.0.1:4242` by default) scans your AI coding
+assistant's JSONL session files into a SQLite index, exposes them through a
+JSON HTTP API plus a Server-Sent Events stream, and serves a pre-built React +
+TypeScript SPA from the same origin. A `watchfiles`-based watcher detects
+session-file changes in real time, and a PTY manager drives the local Claude
+CLI in interactive TUI mode through a hidden pseudo-terminal so users can send
+messages from the web UI with subscription-backed interactive behavior.
+Nothing leaves the machine — there is no remote
+backend, no telemetry, and no authentication layer.
+
+## Component diagram
+
+```mermaid
+flowchart LR
+  subgraph Browser
+    SPA[React + Vite SPA]
+  end
+
+  subgraph LocalMachine[Local machine]
+    Server[FastAPI / uvicorn<br/>127.0.0.1:4242]
+    DB[(SQLite index<br/>FTS5)]
+    Scanner[Scanner + Parser]
+    Watcher[watchfiles watcher]
+    PtyManager[PTY manager<br/>hidden TUI per chat]
+    Recap[Recap runner<br/>PTY fork-session]
+  end
+
+  subgraph Filesystem[Filesystem]
+    JSONL[~/.claude/projects/**/*.jsonl]
+    Cfg[~/.config/clau-decode/config.json]
+    Cache[~/.local/share/clau-decode/index.db]
+  end
+
+  SPA -->|fetch + EventSource| Server
+  Server --> DB
+  Server -->|scan + parse on startup| Scanner
+  Scanner --> JSONL
+  Scanner --> DB
+  Watcher -->|fsevents / inotify| JSONL
+  Watcher -->|asyncio.Queue| Server
+  Server -->|SSE /api/events| SPA
+  Server -->|focus/submit| PtyManager
+  PtyManager -->|hidden PTY| ClaudeTUI[claude TUI]
+  ClaudeTUI -->|appends turns| JSONL
+  Server -->|recap on demand| Recap
+  Recap -->|spawns claude --fork-session in hidden PTY| JSONL
+  Server --> Cfg
+  DB --- Cache
+```
+
+## Data flow: opening a session
+
+1. User clicks a session in the sidebar.
+2. The frontend router (`frontend/src/router.ts`) updates the URL hash to
+   `#/chat/<session_id>` and `App.tsx` reacts to the route change.
+3. `frontend/src/api/client.ts` issues `GET /api/sessions/<session_id>`.
+4. The FastAPI route (`src/clau_decode/server.py`) calls `Database.get_session_detail`
+   (`src/clau_decode/db.py`), which reads the session row and its messages
+   from SQLite.
+5. If the JSONL file's mtime has changed since the last index update, the
+   server re-parses the file via `parse_session` (`src/clau_decode/parser.py`)
+   and upserts the new messages back into SQLite before returning.
+6. The route returns a `SessionDetail` JSON document; the React `ChatView`
+   component renders markdown, tool-use, thinking, and sidechain blocks.
+7. While the session is open, `/api/events` (SSE) pushes `{"type": "refresh"}`
+   payloads whenever the watcher sees the underlying JSONL change. The
+   frontend re-fetches and updates in place.
+
+## Key directories
+
+### Backend — `src/clau_decode/`
+
+| Path | Role |
+|------|------|
+| `cli.py` | Argument parsing, subcommands (`dashboard`, `scan`, `today`, `stats`, `tips`), uvicorn launch |
+| `server.py` | FastAPI app: HTTP routes, SSE stream, static SPA mount |
+| `config.py` | XDG-aware config + DB path resolution, atomic config writes |
+| `models.py` | Pydantic models (`AppConfig`, `Project`, `Session`, `Message`, `ContentBlock`, ...) |
+| `scanner.py` | Walks `<root>/projects/*/` for JSONL session files |
+| `parser.py` | Parses JSONL into `Session` + `list[Message]`; builds message trees |
+| `db.py` | Async SQLite layer (`aiosqlite`) with FTS5 for search |
+| `watcher.py` | `watchfiles.awatch` wrapper that emits `WatchEvent`s |
+| `pty_runner.py` | PTY-attached interactive `claude` driver — canonical send path |
+| `recap_runner.py` | Fire-and-forget PTY-on-fork-session driver for inline recaps |
+| `editor.py` | Sandboxed file editing (used by `--enable-edit`) |
+| `reporter.py` | JSON / Markdown export of conversations |
+| `analytics/` | Token + cost engine, daily/weekly aggregators, tool/file/model stats, tip rules |
+| `static/` | Pre-built SPA assets (committed in the wheel; rebuilt by `make frontend`) |
+
+### Frontend — `frontend/src/`
+
+| Path | Role |
+|------|------|
+| `main.tsx` | React entry point |
+| `App.tsx` | Top-level layout, route-driven view selection, SSE wiring |
+| `router.ts` | Hash-based routing (`/`, `/analytics`, `/chat/<id>`) |
+| `api/` | Typed fetch client; `EventSource` helpers |
+| `store/` | Zustand state stores (selection, UI flags, sidebar) |
+| `components/Sidebar/` | Sidebar, search overlay, help, shortcuts |
+| `components/ChatView/` | Conversation viewer, message blocks, runner panel |
+| `components/Dashboard/` | Home dashboard (hero, heatmap, recap, projects) |
+| `components/Analytics/` | Analytics panel and charts (ECharts) |
+| `components/FileViewer/` | Split-pane file viewer + editor |
+| `components/Settings/` | Settings modal |
+
+## Storage
+
+Clau-Decode follows the [XDG Base Directory
+spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html):
+
+| Purpose | Path (default) | Notes |
+|---------|----------------|-------|
+| User config | `~/.config/clau-decode/config.json` (or `$XDG_CONFIG_HOME/clau-decode/config.json`) | Atomic writes (`*.tmp` → rename) |
+| Session index | `~/.local/share/clau-decode/index.db` (or `$XDG_DATA_HOME/clau-decode/index.db`) | SQLite + FTS5; durable (holds stars/archives/titles). Use `--force-refresh` to rescan rather than deleting |
+| Scanned sessions | `~/.claude/projects/**/*.jsonl` (configurable) | Read-only by default; written only via the runner or `--enable-edit` |
+
+No remote storage. No outbound network calls except optional pricing-table
+refresh in the analytics module.
+
+## Security model
+
+- **Bind address.** Defaults to `127.0.0.1`. `--expose` (or `--host 0.0.0.0`)
+  binds to all interfaces and prints a warning; intended for trusted networks
+  only. There is no authentication.
+- **File viewer.** Reads and (with `--enable-edit`) writes files. Access is
+  sandboxed to session-related directories; path traversal and symlink escapes
+  are explicitly defended against in `editor.py`. Binary and oversized writes
+  are refused. A backup is written next to the original before any edit.
+- **JSONL parsing.** Treated as untrusted input. Malformed lines are skipped
+  with a warning; the parser never `eval`s and does not follow URLs.
+- **PTY runner.** Spawns the local CLI binary on the user's behalf, attached
+  to a hidden pseudo-terminal. The binary name is derived from the session's
+  filesystem layout, not from user-supplied input; `shell=True` is never used.
+  `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` are stripped from the spawned
+  child's env (unless the active profile is API-key authenticated) so a user
+  with one of those exported in their shell doesn't accidentally bill against
+  the static API key.
+- **No telemetry.** No analytics, no error reporting, no remote logging. The
+  CI test suite asserts there are no outbound calls to remote services.
+
+See [`SECURITY.md`](SECURITY.md) for the disclosure process and full scope.
+
+## Performance notes
+
+- **Incremental scan.** Each session row stores the source JSONL's mtime;
+  files whose mtime is unchanged are skipped on rescan.
+- **In-memory session-detail cache.** Hot sessions stay in a small LRU on the
+  server so repeated fetches don't re-query SQLite.
+- **FTS5 search.** Full-text search uses SQLite's FTS5 virtual table, which
+  gives sub-millisecond query times across tens of thousands of messages.
+- **Streaming SSE.** Live updates use a single long-lived `EventSource`
+  connection per browser tab; payloads are tiny (`{"type": "refresh"}`).
+- **Lazy frontend chunks.** Heavy components (ChatView, Analytics, Dashboard,
+  FileViewer, SearchOverlay, SettingsModal) are `React.lazy`-loaded and
+  pre-warmed in the background after first paint.
+- **GZip middleware.** FastAPI compresses JSON responses over a few hundred
+  bytes, which keeps session-detail payloads small on large conversations.