unwind-labs 0.1.0__tar.gz

unwind_labs-0.1.0/LICENSE

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

unwind_labs-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.3
+Name: unwind-labs
+Version: 0.1.0
+Summary: Outside-in web observer for Claude Code sessions and callstack call trees
+License: MIT License
+         
+         Copyright (c) 2026 unwind-labs
+         
+         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.
+Keywords: claude-code,agents,observability,callstack
+Author: Amol Kelkar
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Dist: fastapi (>=0.115)
+Requires-Dist: psutil (>=5.9)
+Requires-Dist: pydantic (>=2.7)
+Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: rich (>=13.7)
+Requires-Dist: typer (>=0.12)
+Requires-Dist: uvicorn[standard] (>=0.30)
+Requires-Dist: watchdog (>=4.0)
+Project-URL: Homepage, https://github.com/amolk/agent-callstack
+Project-URL: Repository, https://github.com/amolk/agent-callstack
+Description-Content-Type: text/markdown
+
+# unwind
+
+Local web observer for Claude Code sessions. Run `unwind` in a project folder; a browser tab opens showing every Claude Code session that has run there, the call tree between forked sessions, and a live-updating view of each session's conversation.
+
+`unwind` is an **outside-in observer**. It never wraps or intercepts Claude Code. It reads:
+
+- `~/.claude/projects/<slug>/*.jsonl` — Claude Code's own session logs
+- `<project>/.claude/callstack/log/` — [callstack](https://github.com/amolk/agent-callstack) plugin invocation reports
+
+…and renders them in a web UI. Claude Code itself keeps running in your terminal, untouched.
+
+## What you get
+
+- **Left pane** — every session in the project, newest first. Status dot (green = live, amber = idle, grey = done), title (first user prompt), relative time, message count, git branch.
+- **Middle pane** — the call tree rooted at the selected session. Nested rows for callstack forks. Chevrons collapse/expand; each row shows task label, status badge, duration, short session id.
+- **Right pane** — the thread for the selected session (or selected tree node). Markdown rendered, tool calls in collapsible cards pairing `tool_use` with its matching `tool_result`, meta events togglable.
+- **Live updates** — new sessions, new messages, and new callstack children appear without a refresh, driven by a WebSocket fed from a `watchdog` filesystem observer.
+- **Keyboard** — `j`/`k` step through sessions, `/` focuses search.
+- **`--all`** — project picker across every `~/.claude/projects/` entry.
+
+## Install
+
+```bash
+pip install unwind
+```
+
+From source:
+
+```bash
+git clone https://github.com/amolk/agent-callstack
+cd agent-callstack/unwind
+poetry install
+cd web && npm install && npm run build && cd ..
+poetry run unwind
+```
+
+## Usage
+
+```bash
+cd /any/claude-project
+unwind
+```
+
+A browser tab opens on an ephemeral `127.0.0.1` port with that project's sessions.
+
+Flags:
+
+| Flag | Purpose |
+| ---- | ------- |
+| `unwind [path]` | Serve a folder other than CWD. |
+| `unwind --port 8765` | Fix the port. |
+| `unwind --no-browser` | Print the URL, don't open. |
+| `unwind --all` | Project picker over every `~/.claude/projects/` dir. |
+| `unwind --host 0.0.0.0` | Bind beyond loopback (use with care — no auth). |
+
+## Dev loop
+
+Two terminals:
+
+```bash
+# terminal 1 — Python backend with autoreload
+poetry shell
+UNWIND_DEFAULT_PATH=/some/project \
+UNWIND_DEFAULT_SLUG=-some-project \
+  uvicorn unwind.server:create_app --factory --reload --port 8765
+
+# terminal 2 — Vite dev server (proxies /api + WebSocket to :8765)
+cd web && npm run dev
+# open http://localhost:5173
+```
+
+Smoke test:
+
+```bash
+./dev/smoke.sh
+```
+
+## Architecture
+
+See [dev/PRD.md](dev/PRD.md) and [dev/PLAN.md](dev/PLAN.md) for the full design. Short version:
+
+- **Backend** (`src/unwind/`): FastAPI app factory, per-project `SessionIndex` with mtime/size caching, `CallstackIndex` reading `report.yaml`, `ProjectWatcher` (watchdog) publishing typed events to a per-slug `EventBus`, WebSocket endpoint that fans out events to subscribers.
+- **Frontend** (`web/`): Vite + React 18 + TypeScript + Tailwind v3 + hand-written shadcn primitives. TanStack Query for REST; a reconnecting WebSocket client patches the query cache so panes update without polling. zustand for UI state.
+- **Packaging**: `npm run build` in `web/` emits directly into `src/unwind/static/`, which is included in the wheel automatically as package data. One `pip install` = full app.
+
+## Scope / non-goals
+
+unwind does **not**:
+- run or control Claude Code
+- send input to any session
+- modify or delete any JSONL or callstack data
+- talk to any remote service (binds to `127.0.0.1` by default)
+
+If you want compaction assist, session control, or forking UX, that belongs in Claude Code itself or in a plugin — unwind stays a read-only view.
+
+## Status
+
+Early alpha. Tested only on macOS / Python 3.12. Windows is out of scope for v1. Known rough edges:
+
+- `claude` process detection can't map a PID to a specific session id (Claude doesn't expose that), so status is scoped to the project. A session counts as "live" if its JSONL was modified in the last ~45s *and* any `claude` process is running in the project cwd.
+- Very large JSONLs (tens of MB) load the whole thread in one shot. Pagination is a Phase 7 item.
+

unwind_labs-0.1.0/README.md

@@ -0,0 +1,101 @@
+# unwind
+
+Local web observer for Claude Code sessions. Run `unwind` in a project folder; a browser tab opens showing every Claude Code session that has run there, the call tree between forked sessions, and a live-updating view of each session's conversation.
+
+`unwind` is an **outside-in observer**. It never wraps or intercepts Claude Code. It reads:
+
+- `~/.claude/projects/<slug>/*.jsonl` — Claude Code's own session logs
+- `<project>/.claude/callstack/log/` — [callstack](https://github.com/amolk/agent-callstack) plugin invocation reports
+
+…and renders them in a web UI. Claude Code itself keeps running in your terminal, untouched.
+
+## What you get
+
+- **Left pane** — every session in the project, newest first. Status dot (green = live, amber = idle, grey = done), title (first user prompt), relative time, message count, git branch.
+- **Middle pane** — the call tree rooted at the selected session. Nested rows for callstack forks. Chevrons collapse/expand; each row shows task label, status badge, duration, short session id.
+- **Right pane** — the thread for the selected session (or selected tree node). Markdown rendered, tool calls in collapsible cards pairing `tool_use` with its matching `tool_result`, meta events togglable.
+- **Live updates** — new sessions, new messages, and new callstack children appear without a refresh, driven by a WebSocket fed from a `watchdog` filesystem observer.
+- **Keyboard** — `j`/`k` step through sessions, `/` focuses search.
+- **`--all`** — project picker across every `~/.claude/projects/` entry.
+
+## Install
+
+```bash
+pip install unwind
+```
+
+From source:
+
+```bash
+git clone https://github.com/amolk/agent-callstack
+cd agent-callstack/unwind
+poetry install
+cd web && npm install && npm run build && cd ..
+poetry run unwind
+```
+
+## Usage
+
+```bash
+cd /any/claude-project
+unwind
+```
+
+A browser tab opens on an ephemeral `127.0.0.1` port with that project's sessions.
+
+Flags:
+
+| Flag | Purpose |
+| ---- | ------- |
+| `unwind [path]` | Serve a folder other than CWD. |
+| `unwind --port 8765` | Fix the port. |
+| `unwind --no-browser` | Print the URL, don't open. |
+| `unwind --all` | Project picker over every `~/.claude/projects/` dir. |
+| `unwind --host 0.0.0.0` | Bind beyond loopback (use with care — no auth). |
+
+## Dev loop
+
+Two terminals:
+
+```bash
+# terminal 1 — Python backend with autoreload
+poetry shell
+UNWIND_DEFAULT_PATH=/some/project \
+UNWIND_DEFAULT_SLUG=-some-project \
+  uvicorn unwind.server:create_app --factory --reload --port 8765
+
+# terminal 2 — Vite dev server (proxies /api + WebSocket to :8765)
+cd web && npm run dev
+# open http://localhost:5173
+```
+
+Smoke test:
+
+```bash
+./dev/smoke.sh
+```
+
+## Architecture
+
+See [dev/PRD.md](dev/PRD.md) and [dev/PLAN.md](dev/PLAN.md) for the full design. Short version:
+
+- **Backend** (`src/unwind/`): FastAPI app factory, per-project `SessionIndex` with mtime/size caching, `CallstackIndex` reading `report.yaml`, `ProjectWatcher` (watchdog) publishing typed events to a per-slug `EventBus`, WebSocket endpoint that fans out events to subscribers.
+- **Frontend** (`web/`): Vite + React 18 + TypeScript + Tailwind v3 + hand-written shadcn primitives. TanStack Query for REST; a reconnecting WebSocket client patches the query cache so panes update without polling. zustand for UI state.
+- **Packaging**: `npm run build` in `web/` emits directly into `src/unwind/static/`, which is included in the wheel automatically as package data. One `pip install` = full app.
+
+## Scope / non-goals
+
+unwind does **not**:
+- run or control Claude Code
+- send input to any session
+- modify or delete any JSONL or callstack data
+- talk to any remote service (binds to `127.0.0.1` by default)
+
+If you want compaction assist, session control, or forking UX, that belongs in Claude Code itself or in a plugin — unwind stays a read-only view.
+
+## Status
+
+Early alpha. Tested only on macOS / Python 3.12. Windows is out of scope for v1. Known rough edges:
+
+- `claude` process detection can't map a PID to a specific session id (Claude doesn't expose that), so status is scoped to the project. A session counts as "live" if its JSONL was modified in the last ~45s *and* any `claude` process is running in the project cwd.
+- Very large JSONLs (tens of MB) load the whole thread in one shot. Pagination is a Phase 7 item.

unwind_labs-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["poetry-core>=2.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "unwind-labs"
+version = "0.1.0"
+description = "Outside-in web observer for Claude Code sessions and callstack call trees"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "Amol Kelkar" }]
+keywords = ["claude-code", "agents", "observability", "callstack"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+    "watchdog>=4.0",
+    "pydantic>=2.7",
+    "typer>=0.12",
+    "pyyaml>=6.0",
+    "psutil>=5.9",
+    "rich>=13.7",
+]
+
+[project.scripts]
+unwind = "unwind.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/amolk/agent-callstack"
+Repository = "https://github.com/amolk/agent-callstack"
+
+[tool.poetry]
+packages = [{ include = "unwind", from = "src" }]
+include = [
+    { path = "src/unwind/static/**/*", format = ["sdist", "wheel"] },
+]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-asyncio = "^0.23"
+websockets = "^12.0"
+httpx = "^0.27"
+build = "^1.2"

unwind_labs-0.1.0/src/unwind/__init__.py

@@ -0,0 +1,3 @@
+"""unwind: outside-in web observer for Claude Code sessions."""
+
+__version__ = "0.1.0"

unwind_labs-0.1.0/src/unwind/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

unwind_labs-0.1.0/src/unwind/api/__init__.py

@@ -0,0 +1,10 @@
+"""FastAPI routers. Aggregated by ``routers()``."""
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from . import projects, sessions_api, ws
+
+
+def routers() -> list[APIRouter]:
+    return [projects.router, sessions_api.router, ws.router]

unwind_labs-0.1.0/src/unwind/api/projects.py

@@ -0,0 +1,106 @@
+"""Project endpoints: list projects, resolve a slug."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from ..dialog import pick_folder
+from ..projects import slug_for
+from ..registry import (
+    forget_slug,
+    index_for_slug,
+    last_activity_for,
+    list_known_projects,
+    register_default_project,
+)
+from ..server_state import default_source_path, default_slug
+from ..watcher import stop_watcher
+
+router = APIRouter(tags=["projects"])
+
+
+class ProjectSummary(BaseModel):
+    slug: str
+    source_path: str
+    last_activity: Optional[datetime]
+    session_count: int
+
+
+class DefaultProject(BaseModel):
+    slug: Optional[str]
+    source_path: Optional[str]
+
+
+class PickedFolder(BaseModel):
+    """Result of the system folder-picker dialog.
+
+    ``cancelled`` is ``True`` when the user dismissed the dialog; in that case
+    ``slug`` and ``source_path`` are ``None``.
+    """
+
+    cancelled: bool
+    slug: Optional[str] = None
+    source_path: Optional[str] = None
+
+
+@router.get("/projects", response_model=list[ProjectSummary])
+def list_projects() -> list[ProjectSummary]:
+    out: list[ProjectSummary] = []
+    for slug, source in list_known_projects():
+        index = index_for_slug(slug)
+        sessions = index.list_sessions()
+        last_ts = sessions[0].last_timestamp if sessions else None
+        if last_ts is None:
+            mtime = last_activity_for(slug)
+            if mtime is not None:
+                last_ts = datetime.fromtimestamp(mtime, tz=timezone.utc)
+        out.append(
+            ProjectSummary(
+                slug=slug,
+                source_path=str(source),
+                last_activity=last_ts,
+                session_count=len(sessions),
+            )
+        )
+    out.sort(
+        key=lambda p: p.last_activity or datetime.fromtimestamp(0, tz=timezone.utc),
+        reverse=True,
+    )
+    return out
+
+
+@router.get("/projects/default", response_model=DefaultProject)
+def get_default_project() -> DefaultProject:
+    path = default_source_path()
+    if path is not None:
+        register_default_project(path)
+    return DefaultProject(slug=default_slug(), source_path=path)
+
+
+@router.post("/projects/pick-folder", response_model=PickedFolder)
+def pick_folder_endpoint() -> PickedFolder:
+    """Open a native folder-picker on the host and register the result.
+
+    The dialog blocks the request until the user picks or cancels. On pick we
+    register the folder so future ``/api/projects`` calls surface its real
+    source path (not just a slug-derived synthetic one).
+    """
+    chosen = pick_folder()
+    if chosen is None:
+        return PickedFolder(cancelled=True)
+    # The slug may already have a cached index built from the synthetic
+    # ``for_slug`` fallback (the projects-list endpoint visits every directory
+    # under ``~/.claude/projects/``). Drop everything for this slug so the
+    # next request rebuilds against the real source path.
+    slug = slug_for(chosen)
+    stop_watcher(slug)
+    forget_slug(slug)
+    register_default_project(str(chosen))
+    return PickedFolder(
+        cancelled=False,
+        slug=slug,
+        source_path=str(chosen),
+    )