agent-decoder 0.3.2__tar.gz → 0.3.6__tar.gz

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/.github/CODEOWNERS

@@ -1,4 +1,4 @@
-# CODEOWNERS for Clau-Decode
+# CODEOWNERS for Agent Decoder
 #
 # GitHub uses this file to auto-request reviews on pull requests.
 # The last matching pattern for a given file wins, so order matters.

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: true
 contact_links:
   - name: Questions and general discussion
-    url: https://github.com/Comradery64/Clau-Decode/discussions
+    url: https://github.com/Comradery64/Agent-Decoder/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 → agent_decoder-0.3.6}/.github/workflows/ci.yml

@@ -48,7 +48,7 @@ jobs:
 
       - name: Tests (pytest with coverage)
         # pyproject's [tool.pytest.ini_options] addopts already enables
-        # --cov=clau_decode; append an XML report for Codecov upload.
+        # --cov=agent_decoder; append an XML report for Codecov upload.
         run: uv run pytest --cov-report=xml
 
       - name: Upload coverage to Codecov

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/.github/workflows/publish.yml

@@ -32,7 +32,7 @@ jobs:
         # deleted or overwritten.
         run: |
           TAG_VERSION="${GITHUB_REF_NAME#v}"
-          PKG_VERSION="$(grep -oP '(?<=^__version__ = ")[^"]+' src/clau_decode/__init__.py)"
+          PKG_VERSION="$(grep -oP '(?<=^__version__ = ")[^"]+' src/agent_decoder/__init__.py)"
           if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
             echo "::error::Tag v$TAG_VERSION does not match __version__ ($PKG_VERSION)"
             exit 1

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/.gitignore

@@ -50,4 +50,11 @@ demo-data/
 demo-reel/
 
 # Keep the built static assets — they ship with the package
-!src/clau_decode/static/
+!src/agent_decoder/static/
+
+# Local scratch/handoff docs and agent config — never published
+docs/archive/
+/.handoff/
+/.internal-archive/
+/.claude/
+/CLAUDE.md

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-# Pre-commit hooks for clau-decode.
+# Pre-commit hooks for agent-decoder.
 # Install once with `pre-commit install`; run on demand with `pre-commit run --all-files`.
 # pre-commit autoupdate will refresh these revs.
 

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/ARCHITECTURE.md

@@ -1,12 +1,12 @@
 # Architecture
 
-This document describes the internal architecture of `clau-decode`. It
+This document describes the internal architecture of `ring`. 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
+Agent Decoder 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 +
@@ -36,8 +36,8 @@ flowchart LR
 
   subgraph Filesystem[Filesystem]
     JSONL[~/.claude/projects/**/*.jsonl]
-    Cfg[~/.config/clau-decode/config.json]
-    Cache[~/.local/share/clau-decode/index.db]
+    Cfg[~/.config/agent-decoder/config.json]
+    Cache[~/.local/share/agent-decoder/index.db]
   end
 
   SPA -->|fetch + EventSource| Server
@@ -63,11 +63,11 @@ flowchart LR
 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
+4. The FastAPI route (`src/agent_decoder/server.py`) calls `Database.get_session_detail`
+   (`src/agent_decoder/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`)
+   server re-parses the file via `parse_session` (`src/agent_decoder/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.
@@ -77,7 +77,7 @@ flowchart LR
 
 ## Key directories
 
-### Backend — `src/clau_decode/`
+### Backend — `src/agent_decoder/`
 
 | Path | Role |
 |------|------|
@@ -114,13 +114,13 @@ flowchart LR
 
 ## Storage
 
-Clau-Decode follows the [XDG Base Directory
+Agent Decoder 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 |
+| User config | `~/.config/agent-decoder/config.json` (or `$XDG_CONFIG_HOME/agent-decoder/config.json`) | Atomic writes (`*.tmp` → rename) |
+| Session index | `~/.local/share/agent-decoder/index.db` (or `$XDG_DATA_HOME/agent-decoder/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
@@ -164,3 +164,55 @@ See [`SECURITY.md`](SECURITY.md) for the disclosure process and full scope.
   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.
+
+### Shared interactive execution
+
+`ExecutionManager` is the single server owner of Claude and Codex terminals.
+It shares the session lock table, active Native terminal, sizing configuration,
+and shutdown lifecycle. `pty_runner.PtyManager` supplies Claude's established
+input policy (ownership, input acknowledgments/watchdog, `/model`, permissions,
+and ephemeral `/btw` capture); `driver_manager.DriverSessionPolicy` supplies
+Codex's launch/resume, state polling, and rollout adoption. Neither policy is
+instantiated as another manager. The former `DriverManager` import resolves to
+`ExecutionManager` for compatibility. Native input, resize, snapshot, status,
+and termination routes all use the same owner. Provider capability checks still
+run before focus/submit; read-only providers cannot acquire a terminal.
+
+Both providers use the isolated `agent-decoder` tmux socket by default.
+`AGENT_DECODER_TMUX_SOCKET` overrides it for isolated installations/tests.
+Claude falls back to direct PTY when tmux is absent; internal consumers can
+explicitly request `terminal_backend="direct"`. Codex requires tmux and retains
+its runtime capability gate. Claude launch environments use a private temporary
+file consumed and unlinked before exec; secrets do not appear in launch argv or
+tmux metadata.
+
+Normal server shutdown **detaches** attach clients, stops local watchdogs and
+capture readers, releases server-owned Claude sidecars, and leaves tmux harnesses
+running. Browser disconnect/idle does not reap tmux harnesses. Explicit kill
+**terminates** the harness; kill also resolves a persistent terminal after a
+server restart without spawning or first focusing it. Direct PTY cannot detach
+and therefore terminates on shutdown. Claude reattachment checks session/cwd
+metadata against the pane PID plus the OS process start identity and executable.
+A changed process or a fresh foreign sidecar prevents adoption. Binary,
+permission, or model configuration changes require a verified owned respawn;
+live `/model` updates the persisted launch configuration. These checks coordinate
+same-user processes, not mutually untrusted users sharing a tmux server.
+
+Tmux redraws terminal output, which is suitable for Native hydration but changes
+the escape sequences Claude's `/btw` parser needs. Claude therefore also uses
+`pipe-pane` into a private Unix datagram receiver for the original byte stream.
+The relay drains without waiting for the application; datagrams and receiver
+work per loop turn are bounded. Sequence gaps or capture-buffer overflow fail
+the pending ephemeral response instead of persisting partial text. A capture
+owner token prevents an old client from stopping a replacement relay. Detach
+removes the local socket and stops its relay; after a crash an orphaned relay
+keeps draining/dropping until reattachment replaces it.
+
+Limitations: pending ephemeral `/btw` output is not recovered across a server
+crash/restart, and output during detach is not retained as a raw byte history;
+reattachment hydrates the tmux screen while JSONL remains the content source.
+A crashed process may leave a private temporary socket directory until OS temp
+cleanup. Deliberately replacing/execing a managed pane into a different executable
+requires explicit recovery rather than automatic ownership adoption. Real
+provider auth/network smoke tests remain opt-in; behavioral tests use synthetic
+CLIs and unique tmux sockets.

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/CHANGELOG.md

@@ -1,11 +1,45 @@
 # Changelog
 
-All notable changes to Clau-Decode will be documented in this file.
+All notable changes to Agent Decoder (formerly Clau-Decode) will be documented in this file.
 
 The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the project is in the 0.x series, breaking changes may land in any minor release; we'll call them out clearly.
 
 ## [Unreleased]
 
+## [0.3.6] - 2026-11-06
+
+### Added
+
+- **Durable agent runs and a cross-provider Runs screen** (#52). Each managed execution attempt is recorded in an `agent_runs` table that is independent of the rebuildable session index; no screen or exit code is treated as proof of completion. Read it at `GET /api/runs` and `GET /api/runs/{id}`.
+- **Unified Claude and Codex execution ownership** with persistent tmux terminals (#51), so both providers share one execution manager.
+- **Artifacts panel** listing a session's images and written files.
+
+### Changed
+
+- Share one syntax highlighter and cache rendered markdown, and toggle the artifacts panel without re-rendering the chat.
+- Local agent and handoff files (`.handoff/`, `.claude/`, `CLAUDE.md`, ...) are excluded from sdist builds and gitignored.
+
+### Fixed
+
+- **Periodic rescan no longer re-parses every Codex transcript each minute.** Codex rollouts are named `rollout-<timestamp>-<uuid>` but indexed under the session id inside the file, so the "has this file changed?" lookup by file name missed most of them and the server re-parsed gigabytes of unchanged transcripts on every pass (a ~14 s CPU spike every 60 s, plus `message_count` reset to 0 on large rollouts). Unchanged files are now skipped by path, including rollouts that share a session id.
+- Dangling symlinks under `~/.claude/projects` are skipped quietly instead of logging a "No such file" warning on every rescan.
+- Native terminal no longer snaps back to the bottom and wipes scrollback when a full-screen clear (`ESC[3J`) arrives while you are scrolled up. A real `/clear` at the bottom still clears. An ignored sequence is logged to the browser console (`agent-decoder: ignored ESC[3J …`) so the cause can be confirmed in real use.
+
+## [0.3.5] - 2026-10-24
+
+### Changed
+
+- **BREAKING: the `clau-decode` command is gone — launch with `ring`.** Renamed the project to **Agent Decoder R.I.N.G.** (Replay, Inspect, Navigate, Grep). The launcher is now `ring`; the Python module is now `agent_decoder`.
+- Config and index DB live in `agent-decoder/` dirs. Existing `clau-decode/` data is copied over on first run and left in place as a backup.
+
+### Fixed
+
+- Decoded view no longer snaps back to the bottom a few moments after you scroll up with the keyboard, touch, or scrollbar: a no-op follow-write at the bottom left an internal "programmatic scroll" flag stuck, so the next streamed update re-pinned you.
+
+### Added
+
+- Search query language: `"exact phrase"`, `-exclude`, `a OR b`, `prefix*`, and `role:` / `project:` / `session:` / `before:` / `after:` filters.
+
 ## [0.3.2] - 2026-09-07
 
 ### Added
@@ -238,10 +272,13 @@ Initial public release.
 
 - License changed from MIT to [FSL-1.1-Apache-2.0](LICENSE). All prior unreleased history was developed under MIT; the 0.1.0 release and everything after it ship under FSL-1.1-Apache-2.0, which converts to Apache 2.0 two years after each release.
 
-[0.3.2]: https://github.com/Comradery64/Clau-Decode/compare/v0.3.1.3...v0.3.2
-[0.3.1.2]: https://github.com/Comradery64/Clau-Decode/compare/v0.3.1.1...v0.3.1.2
-[0.3.1.1]: https://github.com/Comradery64/Clau-Decode/compare/v0.3.1...v0.3.1.1
-[0.3.1]: https://github.com/Comradery64/Clau-Decode/compare/v0.3.0...v0.3.1
-[0.3.0]: https://github.com/Comradery64/Clau-Decode/compare/v0.2.0...v0.3.0
-[0.2.0]: https://github.com/Comradery64/Clau-Decode/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/Comradery64/Clau-Decode/releases/tag/v0.1.0
+[Unreleased]: https://github.com/Comradery64/Agent-Decoder/compare/v0.3.6...HEAD
+[0.3.6]: https://github.com/Comradery64/Agent-Decoder/compare/v0.3.5...v0.3.6
+[0.3.5]: https://github.com/Comradery64/Agent-Decoder/compare/v0.3.2...v0.3.5
+[0.3.2]: https://github.com/Comradery64/Agent-Decoder/compare/v0.3.1.3...v0.3.2
+[0.3.1.2]: https://github.com/Comradery64/Agent-Decoder/compare/v0.3.1.1...v0.3.1.2
+[0.3.1.1]: https://github.com/Comradery64/Agent-Decoder/compare/v0.3.1...v0.3.1.1
+[0.3.1]: https://github.com/Comradery64/Agent-Decoder/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/Comradery64/Agent-Decoder/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/Comradery64/Agent-Decoder/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/Comradery64/Agent-Decoder/releases/tag/v0.1.0

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to Clau-Decode
+# Contributing to Agent Decoder
 
-Thanks for your interest in Clau-Decode! This project is a local, privacy-focused tool for browsing AI coding assistant chat history. Contributions of all kinds are welcome.
+Thanks for your interest in Agent Decoder! This project is a local, privacy-focused tool for browsing AI coding assistant chat history. Contributions of all kinds are welcome.
 
 ## Ways to contribute
 
@@ -13,11 +13,11 @@ If you're not sure whether something is in scope, open an issue first and we can
 
 ## Development setup
 
-Clau-Decode has a Python 3.10+ backend (FastAPI + SQLite, tested with pytest) and a TypeScript frontend (React 18 + Vite, tested with vitest). You'll need Python 3.10+, [`uv`](https://docs.astral.sh/uv/), and Node.js 20+.
+Agent Decoder has a Python 3.10+ backend (FastAPI + SQLite, tested with pytest) and a TypeScript frontend (React 18 + Vite, tested with vitest). You'll need Python 3.10+, [`uv`](https://docs.astral.sh/uv/), and Node.js 20+.
 
 ```bash
-git clone https://github.com/Comradery64/Clau-Decode
-cd Clau-Decode
+git clone https://github.com/Comradery64/Agent-Decoder
+cd Agent Decoder
 
 # Install backend deps + build the frontend
 make dev
@@ -73,7 +73,7 @@ Please confirm:
 
 ## Licensing
 
-Clau-Decode is released under the [Functional Source License, Version 1.1, with the Apache 2.0 Future License](LICENSE) (FSL-1.1-Apache-2.0). By submitting a contribution you agree that it is offered under those same terms. There is no CLA — your `git` authorship is sufficient attribution. Please don't paste in code you don't have the right to license under FSL-1.1-Apache-2.0.
+Agent Decoder is released under the [Functional Source License, Version 1.1, with the Apache 2.0 Future License](LICENSE) (FSL-1.1-Apache-2.0). By submitting a contribution you agree that it is offered under those same terms. There is no CLA — your `git` authorship is sufficient attribution. Please don't paste in code you don't have the right to license under FSL-1.1-Apache-2.0.
 
 ## Questions
 

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/LICENSE

@@ -9,7 +9,7 @@ FSL-1.1-Apache-2.0
 Copyright 2026 Comradery64
 
 Licensor: Comradery64
-Licensed Work: clau-decode. The Licensed Work is © 2026 Comradery64.
+Licensed Work: Agent Decoder R.I.N.G. (formerly clau-decode). The Licensed Work is © 2026 Comradery64.
 Effective Date: 2026-05-13
 Change Date: 2028-05-13
 Change License: Apache License, Version 2.0

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/Makefile

@@ -22,11 +22,11 @@ test:
 
 # Run the app from source
 run:
-	uv run clau-decode
+	uv run ring
 
 # Clean build artifacts
 clean:
 	rm -rf frontend/node_modules frontend/dist
-	rm -rf src/clau_decode/static/assets src/clau_decode/static/index.html
+	rm -rf src/agent_decoder/static/assets src/agent_decoder/static/index.html
 	rm -rf .pytest_cache
 	find . -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true

{agent_decoder-0.3.2 → agent_decoder-0.3.6}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: agent-decoder
-Version: 0.3.2
+Version: 0.3.6
 Summary: A local web UI for browsing and analyzing AI coding assistant chat history
-Project-URL: Homepage, https://github.com/Comradery64/Clau-Decode
-Project-URL: Repository, https://github.com/Comradery64/Clau-Decode
-Project-URL: Issues, https://github.com/Comradery64/Clau-Decode/issues
+Project-URL: Homepage, https://github.com/Comradery64/Agent-Decoder
+Project-URL: Repository, https://github.com/Comradery64/Agent-Decoder
+Project-URL: Issues, https://github.com/Comradery64/Agent-Decoder/issues
 License: FSL-1.1-Apache-2.0
 License-File: LICENSE
 Keywords: ai-chat,analytics,chat-history,viewer
@@ -31,17 +31,23 @@ Requires-Dist: httpx>=0.27.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff==0.15.12; extra == 'dev'
 Description-Content-Type: text/markdown
 
-<h1 align="center">Clau-Decode</h1>
+<h1 align="center">Agent Decoder R.I.N.G.</h1>
 
 <p align="center">
-  <em>Browse, search, and analyze your AI coding assistant chat history — entirely local, entirely private.</em>
+  <strong>Replay, Inspect, Navigate, Grep.</strong><br>
+  <em>Decode your agents' secret messages. "Send 10¢ and a box top!"</em>
 </p>
 
 <p align="center">
-  <a href="https://github.com/Comradery64/Clau-Decode/actions/workflows/ci.yml">
-    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Comradery64/Clau-Decode/ci.yml?branch=main&label=CI&style=flat-square">
+  Browse, search, and analyze your AI coding assistant chat history — entirely local, entirely private.
+</p>
+
+<p align="center">
+  <a href="https://github.com/Comradery64/Agent-Decoder/actions/workflows/ci.yml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Comradery64/Agent-Decoder/ci.yml?branch=main&label=CI&style=flat-square">
   </a>
   <a href="LICENSE">
     <img alt="License" src="https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-blue?style=flat-square">
@@ -49,32 +55,22 @@ Description-Content-Type: text/markdown
   <a href="pyproject.toml">
     <img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square">
   </a>
-  <a href="https://github.com/Comradery64/Clau-Decode/blob/main/CHANGELOG.md">
+  <a href="https://github.com/Comradery64/Agent-Decoder/blob/main/CHANGELOG.md">
     <img alt="Changelog" src="https://img.shields.io/badge/changelog-keep--a--changelog-orange?style=flat-square">
   </a>
 </p>
 
 <p align="center">
-  <video
-    src="https://github.com/user-attachments/assets/6f5a9a09-fbab-467f-82b1-c2e642dc8726"
-    poster="https://github.com/Comradery64/Clau-Decode/raw/main/docs/demo-poster.jpg"
-    controls
-    muted
-    playsinline
-    width="820">
-    <a href="https://github.com/user-attachments/assets/6f5a9a09-fbab-467f-82b1-c2e642dc8726">
-      <img src="https://github.com/Comradery64/Clau-Decode/raw/main/docs/demo-poster.jpg" alt="Clau-Decode demo — click to play" width="820">
-    </a>
-  </video>
+  <img src="docs/ad-poster.png" alt="Agent Decoder R.I.N.G. retro-futurist ad poster" width="360">
 </p>
 
 ---
 
-## Why Clau-Decode?
+## Why Agent Decoder?
 
 Your AI coding assistant writes a small mountain of JSONL session files into
 `~/.claude/projects/` — useful, but unreadable and impossible to search by hand.
-Clau-Decode reads those files locally, indexes them into SQLite, and serves a
+Agent Decoder reads those files locally, indexes them into SQLite, and serves a
 fast browser UI with full-text search, conversation rendering, analytics, and a
 recap engine.
 
@@ -83,22 +79,22 @@ recap engine.
 ```bash
 # Install as an isolated tool — its own virtualenv, on your PATH, nothing
 # touches your system Python. Use whichever you already have:
-uv tool install git+https://github.com/Comradery64/Clau-Decode.git
+uv tool install git+https://github.com/Comradery64/Agent-Decoder.git
 # or:
-pipx install git+https://github.com/Comradery64/Clau-Decode.git
+pipx install git+https://github.com/Comradery64/Agent-Decoder.git
 
-clau-decode                 # opens http://localhost:4242
+ring                 # opens http://localhost:4242
 
 # update later — re-pull the latest from main (git installs need --force;
 # plain `upgrade`/`reinstall` won't fetch new commits):
-uv tool install --force git+https://github.com/Comradery64/Clau-Decode.git
+uv tool install --force git+https://github.com/Comradery64/Agent-Decoder.git
 # or:
-pipx install --force git+https://github.com/Comradery64/Clau-Decode.git
+pipx install --force git+https://github.com/Comradery64/Agent-Decoder.git
 ```
 
 Requires Python 3.10+. The wheel ships the pre-built frontend, so **no Node.js is needed** — only for development. All data stays on your machine — no telemetry.
 
-> Just trying it out? Run without installing: `uvx --from git+https://github.com/Comradery64/Clau-Decode.git clau-decode`
+> Just trying it out? Run without installing: `uvx --from git+https://github.com/Comradery64/Agent-Decoder.git ring`
 > Prefer not to install? Run it straight from a clone — see [Development](#development).
 > Advanced: `pip install` works too, but only **inside an activated virtualenv** — never your system/Homebrew Python (PEP 668 will block it, and a global install can shadow other checkouts).
 
@@ -121,6 +117,22 @@ git fetch origin && git reset --hard origin/main
 - `Cmd+K` global search across every session — content, tool use, file paths, thinking blocks
 - Inline live-search bar on the home page for quick lookups
 - Results show highlighted excerpts and jump directly to the matching message
+- Query syntax (works in both search boxes):
+
+  | Type | Means |
+  |------|-------|
+  | `"exact phrase"` | match the words together, in order |
+  | `-word` / `-"a phrase"` | exclude messages containing it |
+  | `a OR b` | either term (plain spaces mean AND) |
+  | `deploy*` | prefix match |
+  | `role:user` / `-role:assistant` | only / not that role |
+  | `project:foo` / `-project:foo` | project id contains / doesn't contain `foo` |
+  | `session:<id>` | one session |
+  | `after:2026-01-01` `before:2026-02-01` | date range (ISO dates) |
+
+  Example: `"staging deploy" -rollback role:user after:2026-09-01`. A query needs at
+  least one positive term — `-word` or filters alone return nothing. Unknown
+  `key:` prefixes (like `http://x`) are searched as plain text.
 
 ### Conversation viewer
 - Rendered markdown with code syntax highlighting
@@ -207,11 +219,11 @@ git fetch origin && git reset --hard origin/main
 
 | Command | Description |
 |---------|-------------|
-| `clau-decode` | Launch the web UI (default) |
-| `clau-decode scan` | Rescan and print summary |
-| `clau-decode today` | Show today's token usage and cost |
-| `clau-decode stats` | Print statistical metrics |
-| `clau-decode tips` | Print optimization tips |
+| `ring` | Launch the web UI (default) |
+| `ring scan` | Rescan and print summary |
+| `ring today` | Show today's token usage and cost |
+| `ring stats` | Print statistical metrics |
+| `ring tips` | Print optimization tips |
 
 ### Keyboard shortcuts
 
@@ -229,7 +241,7 @@ git fetch origin && git reset --hard origin/main
 
 ## Configuration
 
-Settings are saved to `~/.config/clau-decode/config.json`. Edit them in the UI,
+Settings are saved to `~/.config/agent-decoder/config.json`. Edit them in the UI,
 or directly:
 
 ```json
@@ -242,14 +254,14 @@ or directly:
 }
 ```
 
-The session index lives at `~/.local/share/clau-decode/index.db` (durable, so it
-survives cache clears). To force a full rescan, run `clau-decode --force-refresh` —
+The session index lives at `~/.local/share/agent-decoder/index.db` (durable, so it
+survives cache clears). To force a full rescan, run `ring --force-refresh` —
 prefer this over deleting the DB, which also discards stars, archives, and custom
 titles.
 
 ## Architecture
 
-Clau-Decode is a local-first FastAPI server that scans your AI coding
+Agent Decoder is a local-first FastAPI server that scans your AI coding
 assistant's JSONL session files into a SQLite index, serves a React +
 TypeScript SPA, and drives the Claude CLI through a hidden PTY for in-app
 sessions.
@@ -259,17 +271,17 @@ See [`ARCHITECTURE.md`](ARCHITECTURE.md) for a system diagram and deeper notes.
 ## Development
 
 ```bash
-git clone https://github.com/Comradery64/Clau-Decode
-cd Clau-Decode
+git clone https://github.com/Comradery64/Agent-Decoder
+cd Agent Decoder
 
 # Install backend deps (into an isolated .venv) + build the frontend
 make dev                      # = uv sync && build frontend
 
 # Run the app from source — in the project venv, so it always runs THIS
 # checkout (no global install, no shadowing):
-uv run clau-decode --no-open
+uv run ring --no-open
 # equivalently, as a module from the checkout root:
-uv run python -m clau_decode --no-open
+uv run python -m agent_decoder --no-open
 # (make run wraps this)
 
 # Run tests
@@ -306,9 +318,9 @@ process in [`SECURITY.md`](SECURITY.md) — do **not** open a public issue.
 
 ## Acknowledgements
 
-Clau-Decode is **inspired by, and built around the file format of, [Claude](https://www.anthropic.com/claude) and Claude Code from [Anthropic](https://www.anthropic.com/)**. This project is not affiliated with, endorsed by, or sponsored by Anthropic, PBC. *Claude* and *Claude Code* are trademarks of Anthropic, PBC; all references in this project are nominative.
+Agent Decoder is **inspired by, and built around the file format of, [Claude](https://www.anthropic.com/claude) and Claude Code from [Anthropic](https://www.anthropic.com/)**. This project is not affiliated with, endorsed by, or sponsored by Anthropic, PBC. *Claude* and *Claude Code* are trademarks of Anthropic, PBC; all references in this project are nominative.
 
-> *A personal note from the author* — I didn't write the code in this repository or build any of the underlying tools. I sat at my computer, typed into it, and kept asking it for more. The actual line-by-line authoring was done by AI coding assistants — Anthropic's [Claude](https://www.anthropic.com/claude) (Sonnet and Opus) and [Z.ai](https://z.ai/)'s GLM-5.1, with the latter doing a substantial share of the heavy lifting alongside them. They aren't in the lists below because they're AI models rather than libraries, but they deserve named credit here. The projects, products, and people below did the rest of the real work that made Clau-Decode possible:
+> *A personal note from the author* — I didn't write the code in this repository or build any of the underlying tools. I sat at my computer, typed into it, and kept asking it for more. The actual line-by-line authoring was done by AI coding assistants — Anthropic's [Claude](https://www.anthropic.com/claude) (Sonnet and Opus) and [Z.ai](https://z.ai/)'s GLM-5.1, with the latter doing a substantial share of the heavy lifting alongside them. They aren't in the lists below because they're AI models rather than libraries, but they deserve named credit here. The projects, products, and people below did the rest of the real work that made Agent Decoder possible:
 
 **Backend (Python)**
 
@@ -370,7 +382,7 @@ The Native view ships these monospace fonts so the in-app font picker works on a
 - [Ruff](https://docs.astral.sh/ruff/) and [pre-commit](https://pre-commit.com/) — code style and pre-commit hooks
 - [Editorconfig](https://editorconfig.org/) — consistent indentation across editors
 
-Every project listed above is independently licensed by its respective authors; check each project's repository for terms. If we've missed an attribution, please [open an issue](https://github.com/Comradery64/Clau-Decode/issues).
+Every project listed above is independently licensed by its respective authors; check each project's repository for terms. If we've missed an attribution, please [open an issue](https://github.com/Comradery64/Agent-Decoder/issues).
 
 ## License