claude-theater 0.1.0__tar.gz

claude_theater-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Internal launch/strategy/planning notes — kept local, not shipped.
+DISTRIBUTION.md
+UPGRADE-PLAN.md
+
+# VS Code extension build artifacts (the bundled server copy is generated at
+# package time by vscode:prepublish; the .vsix is a build output)
+vscode-extension/claude_theater.py
+vscode-extension/*.vsix

claude_theater-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims
+to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+SemVer policy for this tool:
+
+- **PATCH** — parser fixes / new Claude Code build adapters.
+- **MINOR** — new format adapters, themes, languages, dashboard additions.
+- **MAJOR** — breaking changes to the dashboard or the emitted API shape.
+
+## Tested against Claude Code
+
+| Claude Theater | Claude Code |
+| -------------- | ----------- |
+| 0.1.x          | 2.1.x       |
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-06
+
+### Added
+
+- Initial release: a single-file, pure-stdlib web app that visualizes Claude
+  Code subagents as a live office (one room per conversation), served on
+  `127.0.0.1:7333`.
+- Isolated parser `parse_agent_event(line) -> Event` — the only code that
+  touches the raw journal format — with degrade-not-crash handling.
+- Non-blocking version banner when journals come from an untested Claude Code
+  version.
+- Bilingual UI: English by default, Hebrew toggle (persisted, RTL-aware).
+- `--demo` mode: a synthetic, populated office (no real journals read) for a
+  zero-setup first run and for capturing screenshots / the Hero GIF.
+- `--version`, `--help`, `--no-browser` flags; the app opens the browser itself
+  once the port is bound.
+- Packaging for PyPI/pipx (`claude-theater` / `python -m claude_theater`) and
+  CI across Windows/macOS/Linux × Python 3.9–3.13.
+
+[Unreleased]: https://github.com/asafabram-ship-it/claude-theater/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/asafabram-ship-it/claude-theater/releases/tag/v0.1.0

claude_theater-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to Claude Theater
+
+Thanks for helping! The single most valuable contribution is a **journal sample
+from a Claude Code version we haven't tested** — that's what keeps the parser
+honest as the format evolves.
+
+## #1 contribution: a format-drift report
+
+If you see the yellow banner ("Tested up to Claude Code X · detected Y") or an
+agent renders oddly, please:
+
+1. Find a recent `agent-*.jsonl` under
+   `~/.claude/projects/<encoded-cwd>/<session-id>/subagents/`.
+2. **Scrub it.** These files contain real conversation content. Replace every
+   task/prompt and every result/text with synthetic placeholder text. Keep the
+   structure (the `type`, `message.content` block shapes, `tool_use` names,
+   `stop_reason`, `version`) — that's all the parser cares about.
+3. Drop it under `fixtures/cc-<major.minor>/` and open a PR (or attach it to an
+   issue). Mention the exact `claude --version`.
+
+A scrubbed fixture + the version string is enough for us to add an adapter case.
+**Never commit unscrubbed journal content.**
+
+## Adding a language
+
+The UI is bilingual (English/Hebrew) and the server is language-neutral. To add
+a language, edit the `I18N` table (and the `PERSONAS_*` / `TOOLS_*` tables) in
+`claude_theater.py` — one file, no Python logic changes. Keep the key set
+identical across languages (the tests and `t()` fallback assume parity).
+
+## Dev setup
+
+Pure standard library — nothing to install to run or test:
+
+```bash
+python -m claude_theater                 # run it
+python -m unittest discover -s tests -v  # golden parser + contract tests
+```
+
+Optional, matching CI:
+
+```bash
+pipx run ruff check .     # lint (real bugs only: pyflakes + syntax)
+pipx run build            # build sdist + wheel
+pipx run twine check dist/*
+```
+
+## Ground rules
+
+- **Privacy first.** Keep everything local; never add telemetry or outbound
+  calls. The server binds `127.0.0.1` only.
+- **No runtime dependencies.** The tool stays single-file stdlib.
+- **Keep the parser isolated.** `parse_agent_event(line) -> Event` is the only
+  code that touches raw JSONL; everything else consumes the stable `Event`.
+- Add or update a fixture + test when you change parsing or the emitted payload.

claude_theater-0.1.0/LICENSE

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

claude_theater-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: claude-theater
+Version: 0.1.0
+Summary: Watch your Claude Code subagents work — a live office for every conversation.
+Project-URL: Homepage, https://github.com/asafabram-ship-it/claude-theater
+Project-URL: Issues, https://github.com/asafabram-ship-it/claude-theater/issues
+Author-email: Asaf Abramzon <asafabram@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude,claude-code,dashboard,dev-tools,subagents,visualizer
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable MD033 MD041 -->
+<div align="center">
+
+# 🎭 Claude Theater
+
+**Watch your Claude Code conversations and subagents work — a live office, in real time.**
+
+[![CI](https://github.com/asafabram-ship-it/claude-theater/actions/workflows/ci.yml/badge.svg)](https://github.com/asafabram-ship-it/claude-theater/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/claude-theater.svg)](https://pypi.org/project/claude-theater/)
+[![Python](https://img.shields.io/pypi/pyversions/claude-theater.svg)](https://pypi.org/project/claude-theater/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+<!-- Absolute raw URL so the image renders on PyPI too (relative paths don't). -->
+<img src="https://raw.githubusercontent.com/asafabram-ship-it/claude-theater/main/docs/screenshot.png" alt="Claude Theater — a live office of Claude Code subagents at work" width="820">
+
+<sub>The demo office (`claude-theater --demo`): conversations and subagents at work, each agent walks in, sits, head-bobs while it types, then confetti on finish. A community visualizer **for Claude Code** — not affiliated with Anthropic.</sub>
+
+</div>
+
+Try it now, no Claude Code session required — `pipx run claude-theater --demo`
+spins up the office above with synthetic agents.
+
+---
+
+Claude Theater reads the journals Claude Code writes for your conversations and
+the subagents they spawn, and renders them as a live office: **every conversation
+is a room** (titled by its subject), and inside it the conversation itself plus
+each subagent is a little character at a desk — avatar, name, the tool it's using
+right now, and a timer. Click any character to read its full task and result.
+When an agent finishes: confetti, a chime, and it quietly steps off the floor —
+and each room has its own **show-finished** toggle, so you control the history
+per conversation.
+
+The UI is **bilingual** — English by default, Hebrew one click away (the choice
+is remembered, and the layout flips to RTL). Adding another language is a single
+edit to the `I18N` table in `claude_theater.py`; the server stays language-neutral.
+
+## Quick start
+
+Zero install — run it straight from PyPI with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx run claude-theater
+```
+
+Or install it:
+
+```bash
+pipx install claude-theater   # or: pip install claude-theater
+claude-theater
+```
+
+Or run from a clone (pure standard library, nothing to install):
+
+```bash
+python -m claude_theater
+```
+
+Then open **http://localhost:7333**. On Windows you can also just run
+`start.cmd`, which launches the server and opens your browser.
+
+> Requires Python 3.9+ and a Claude Code install that writes journals under
+> `~/.claude/projects/`.
+
+## VS Code extension
+
+Prefer it inside your editor? `vscode-extension/` packages Claude Theater as a
+VS Code extension: it runs the server in the background (start/stop it from a
+status-bar button) and opens the office in an interactive panel — no separate
+terminal. The server is bundled into the extension, so it works without a
+separate install. Build a `.vsix` with [`@vscode/vsce`](https://github.com/microsoft/vscode-vsce)
+(`cd vscode-extension && npx @vscode/vsce package`) and install it from the
+Extensions view.
+
+## How it works
+
+- Polls the journals Claude Code already writes — both the session files (your
+  conversations) and `**/subagents/agent-*.jsonl` (the subagents they spawn).
+  Claude Theater only reads them; it never starts or controls agents.
+- A single adapter, `parse_agent_event(line) -> Event`, is the **only** code
+  that touches the raw journal format. Everything else consumes the stable
+  `Event`, so a Claude Code format change is absorbed in one place.
+- **Degrades, never crashes:** corrupt lines are skipped (and counted), unknown
+  keys are ignored, and an agent missing fields still shows up instead of
+  vanishing.
+- A non-blocking **version banner** appears when a journal comes from a Claude
+  Code version this build hasn't been tested against — output may be partial,
+  but the office keeps running.
+
+## Privacy
+
+Your journals contain real conversation content, so Claude Theater is built to
+keep them on your machine:
+
+- Binds to **`127.0.0.1` only** — never reachable from the network.
+- **Never transmits** anything anywhere. No telemetry, no remote calls.
+- The committed `fixtures/` are 100% synthetic — no real prompts or results.
+
+## Development
+
+```bash
+python -m unittest discover -s tests   # golden parser tests, zero dependencies
+```
+
+The tests run synthetic journal fixtures through the adapter and fail loudly if
+the format drifts. Contributing a journal sample from a new Claude Code build is
+the most valuable contribution — **scrub every prompt and result first.**
+
+## Compatibility
+
+Tested against Claude Code **2.1.x**. Newer builds will trigger the version
+banner; please open a *format-drift report* with a scrubbed sample so we can add
+a fixture and an adapter case.
+
+## License
+
+[MIT](LICENSE) © 2026 Asaf Abramzon. "Claude" is a trademark of Anthropic;
+this is an independent, community project for Claude Code.

claude_theater-0.1.0/README.md

@@ -0,0 +1,118 @@
+<!-- markdownlint-disable MD033 MD041 -->
+<div align="center">
+
+# 🎭 Claude Theater
+
+**Watch your Claude Code conversations and subagents work — a live office, in real time.**
+
+[![CI](https://github.com/asafabram-ship-it/claude-theater/actions/workflows/ci.yml/badge.svg)](https://github.com/asafabram-ship-it/claude-theater/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/claude-theater.svg)](https://pypi.org/project/claude-theater/)
+[![Python](https://img.shields.io/pypi/pyversions/claude-theater.svg)](https://pypi.org/project/claude-theater/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+<!-- Absolute raw URL so the image renders on PyPI too (relative paths don't). -->
+<img src="https://raw.githubusercontent.com/asafabram-ship-it/claude-theater/main/docs/screenshot.png" alt="Claude Theater — a live office of Claude Code subagents at work" width="820">
+
+<sub>The demo office (`claude-theater --demo`): conversations and subagents at work, each agent walks in, sits, head-bobs while it types, then confetti on finish. A community visualizer **for Claude Code** — not affiliated with Anthropic.</sub>
+
+</div>
+
+Try it now, no Claude Code session required — `pipx run claude-theater --demo`
+spins up the office above with synthetic agents.
+
+---
+
+Claude Theater reads the journals Claude Code writes for your conversations and
+the subagents they spawn, and renders them as a live office: **every conversation
+is a room** (titled by its subject), and inside it the conversation itself plus
+each subagent is a little character at a desk — avatar, name, the tool it's using
+right now, and a timer. Click any character to read its full task and result.
+When an agent finishes: confetti, a chime, and it quietly steps off the floor —
+and each room has its own **show-finished** toggle, so you control the history
+per conversation.
+
+The UI is **bilingual** — English by default, Hebrew one click away (the choice
+is remembered, and the layout flips to RTL). Adding another language is a single
+edit to the `I18N` table in `claude_theater.py`; the server stays language-neutral.
+
+## Quick start
+
+Zero install — run it straight from PyPI with [pipx](https://pipx.pypa.io/):
+
+```bash
+pipx run claude-theater
+```
+
+Or install it:
+
+```bash
+pipx install claude-theater   # or: pip install claude-theater
+claude-theater
+```
+
+Or run from a clone (pure standard library, nothing to install):
+
+```bash
+python -m claude_theater
+```
+
+Then open **http://localhost:7333**. On Windows you can also just run
+`start.cmd`, which launches the server and opens your browser.
+
+> Requires Python 3.9+ and a Claude Code install that writes journals under
+> `~/.claude/projects/`.
+
+## VS Code extension
+
+Prefer it inside your editor? `vscode-extension/` packages Claude Theater as a
+VS Code extension: it runs the server in the background (start/stop it from a
+status-bar button) and opens the office in an interactive panel — no separate
+terminal. The server is bundled into the extension, so it works without a
+separate install. Build a `.vsix` with [`@vscode/vsce`](https://github.com/microsoft/vscode-vsce)
+(`cd vscode-extension && npx @vscode/vsce package`) and install it from the
+Extensions view.
+
+## How it works
+
+- Polls the journals Claude Code already writes — both the session files (your
+  conversations) and `**/subagents/agent-*.jsonl` (the subagents they spawn).
+  Claude Theater only reads them; it never starts or controls agents.
+- A single adapter, `parse_agent_event(line) -> Event`, is the **only** code
+  that touches the raw journal format. Everything else consumes the stable
+  `Event`, so a Claude Code format change is absorbed in one place.
+- **Degrades, never crashes:** corrupt lines are skipped (and counted), unknown
+  keys are ignored, and an agent missing fields still shows up instead of
+  vanishing.
+- A non-blocking **version banner** appears when a journal comes from a Claude
+  Code version this build hasn't been tested against — output may be partial,
+  but the office keeps running.
+
+## Privacy
+
+Your journals contain real conversation content, so Claude Theater is built to
+keep them on your machine:
+
+- Binds to **`127.0.0.1` only** — never reachable from the network.
+- **Never transmits** anything anywhere. No telemetry, no remote calls.
+- The committed `fixtures/` are 100% synthetic — no real prompts or results.
+
+## Development
+
+```bash
+python -m unittest discover -s tests   # golden parser tests, zero dependencies
+```
+
+The tests run synthetic journal fixtures through the adapter and fail loudly if
+the format drifts. Contributing a journal sample from a new Claude Code build is
+the most valuable contribution — **scrub every prompt and result first.**
+
+## Compatibility
+
+Tested against Claude Code **2.1.x**. Newer builds will trigger the version
+banner; please open a *format-drift report* with a scrubbed sample so we can add
+a fixture and an adapter case.
+
+## License
+
+[MIT](LICENSE) © 2026 Asaf Abramzon. "Claude" is a trademark of Anthropic;
+this is an independent, community project for Claude Code.

claude_theater-0.1.0/ROADMAP.md

@@ -0,0 +1,37 @@
+# Roadmap
+
+Directional, not a promise. Issues and PRs welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md). The guiding constraints don't change:
+**local-only, zero runtime dependencies, single-file stdlib, degrade-not-crash.**
+
+## Now — 0.1.x
+
+- Single-file, pure-stdlib web app; one room per conversation.
+- Isolated parser with degrade-not-crash and a version banner.
+- Bilingual UI (English / Hebrew), instant toggle, RTL-aware.
+- `--demo` office for screenshots and a zero-setup first run.
+- PyPI / pipx packaging; CI across Windows/macOS/Linux × Python 3.9–3.13.
+
+## Next
+
+- **Claude Code version adapters** as the format evolves — driven by
+  community format-drift reports (the #1 contribution).
+- **VS Code extension**: reuse the existing HTML/JS inside a `WebviewPanel`
+  (also mirrored to Open VSX for VSCodium / Cursor).
+- **npx** entry point for the Node-native crowd.
+- **More languages** — each is a single edit to the `I18N` table.
+- Labels for **tools** beyond the current set (broader MCP coverage).
+
+## Ideas (v2, unscheduled)
+
+- Native finish notifications (e.g. Windows toast via an optional, lazy import).
+- Themes / skins.
+- Friendly room labels derived from the conversation title instead of the cwd.
+- Per-agent timing stats (durations, tool histograms).
+
+## Non-goals
+
+- No telemetry, no network calls, nothing that leaves `127.0.0.1`.
+- No required runtime dependencies.
+- No control over agents — Claude Theater only *watches* the journals Claude
+  Code already writes.