claude-stream 0.1.0__tar.gz

claude_stream-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

claude_stream-0.1.0/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

claude_stream-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: claude-stream
+Version: 0.1.0
+Summary: Parse and prettify Claude Code JSONL stream output
+Project-URL: Homepage, https://github.com/shitchell/claude-stream
+Project-URL: Repository, https://github.com/shitchell/claude-stream
+Project-URL: Issues, https://github.com/shitchell/claude-stream/issues
+Author: Shaun Mitchell
+License-Expression: WTFPL
+License-File: LICENSE
+Keywords: anthropic,claude,cli,jsonl,stream
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Public Domain
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: watch
+Requires-Dist: watchdog>=3.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# claude-stream
+
+Parse and prettify Claude Code JSONL stream output.
+
+## Installation
+
+```bash
+pip install claude-stream
+```
+
+For file watching support:
+
+```bash
+pip install "claude-stream[watch]"
+```
+
+## Usage
+
+```bash
+# Read from a file
+claude-stream session.jsonl
+
+# Show only last N lines
+claude-stream session.jsonl -n 20
+
+# Read from stdin
+cat session.jsonl | claude-stream
+
+# Parse the most recent session
+claude-stream --latest
+claude-stream --latest -n 50              # Last 50 lines
+
+# Find and parse a session by UUID
+claude-stream --session abc123
+```
+
+### Watch Mode
+
+Watch for new messages in real-time (like `tail -f`):
+
+```bash
+# Watch all Claude sessions
+claude-stream --watch ~/.claude/projects/
+
+# Watch from any project directory (auto-resolves to Claude path)
+claude-stream --watch .
+claude-stream --watch ~/myproject
+
+# Watch with initial context (last N lines)
+claude-stream --watch . -n 10
+```
+
+When given a directory outside `~/.claude`, the path is automatically
+converted to Claude's project format (e.g., `/home/user/project` becomes
+`~/.claude/projects/-home-user-project`).
+
+### Output Formats
+
+```bash
+# ANSI terminal colors (default)
+claude-stream --format ansi session.jsonl
+
+# Markdown
+claude-stream --format markdown session.jsonl > export.md
+
+# Plain text
+claude-stream --format plain session.jsonl
+```
+
+### Filtering
+
+```bash
+# Show only specific message types
+claude-stream --show-type assistant --show-type user session.jsonl
+
+# Show only messages with specific tools
+claude-stream --show-tool Bash --show-tool Read session.jsonl
+
+# Grep for patterns
+claude-stream --grep "error" session.jsonl
+
+# Exclude patterns
+claude-stream --exclude "thinking" session.jsonl
+```
+
+### Display Options
+
+```bash
+# Hide thinking blocks
+claude-stream --hide-thinking session.jsonl
+
+# Hide tool results
+claude-stream --hide-tool-results session.jsonl
+
+# Show metadata (UUIDs, timestamps)
+claude-stream --show-metadata session.jsonl
+
+# Compact mode (hide thinking, tool results, metadata)
+claude-stream --compact session.jsonl
+
+# Show line numbers
+claude-stream --line-numbers session.jsonl
+```
+
+## Architecture
+
+- **Pydantic models** parse JSON into typed message structures
+- **Messages** produce `RenderBlock` lists (flexible rendering primitives)
+- **Formatters** convert `RenderBlocks` to output formats (ANSI, Markdown, Plain)
+
+## License
+
+[WTFPL](http://www.wtfpl.net/)

claude_stream-0.1.0/README.md

@@ -0,0 +1,113 @@
+# claude-stream
+
+Parse and prettify Claude Code JSONL stream output.
+
+## Installation
+
+```bash
+pip install claude-stream
+```
+
+For file watching support:
+
+```bash
+pip install "claude-stream[watch]"
+```
+
+## Usage
+
+```bash
+# Read from a file
+claude-stream session.jsonl
+
+# Show only last N lines
+claude-stream session.jsonl -n 20
+
+# Read from stdin
+cat session.jsonl | claude-stream
+
+# Parse the most recent session
+claude-stream --latest
+claude-stream --latest -n 50              # Last 50 lines
+
+# Find and parse a session by UUID
+claude-stream --session abc123
+```
+
+### Watch Mode
+
+Watch for new messages in real-time (like `tail -f`):
+
+```bash
+# Watch all Claude sessions
+claude-stream --watch ~/.claude/projects/
+
+# Watch from any project directory (auto-resolves to Claude path)
+claude-stream --watch .
+claude-stream --watch ~/myproject
+
+# Watch with initial context (last N lines)
+claude-stream --watch . -n 10
+```
+
+When given a directory outside `~/.claude`, the path is automatically
+converted to Claude's project format (e.g., `/home/user/project` becomes
+`~/.claude/projects/-home-user-project`).
+
+### Output Formats
+
+```bash
+# ANSI terminal colors (default)
+claude-stream --format ansi session.jsonl
+
+# Markdown
+claude-stream --format markdown session.jsonl > export.md
+
+# Plain text
+claude-stream --format plain session.jsonl
+```
+
+### Filtering
+
+```bash
+# Show only specific message types
+claude-stream --show-type assistant --show-type user session.jsonl
+
+# Show only messages with specific tools
+claude-stream --show-tool Bash --show-tool Read session.jsonl
+
+# Grep for patterns
+claude-stream --grep "error" session.jsonl
+
+# Exclude patterns
+claude-stream --exclude "thinking" session.jsonl
+```
+
+### Display Options
+
+```bash
+# Hide thinking blocks
+claude-stream --hide-thinking session.jsonl
+
+# Hide tool results
+claude-stream --hide-tool-results session.jsonl
+
+# Show metadata (UUIDs, timestamps)
+claude-stream --show-metadata session.jsonl
+
+# Compact mode (hide thinking, tool results, metadata)
+claude-stream --compact session.jsonl
+
+# Show line numbers
+claude-stream --line-numbers session.jsonl
+```
+
+## Architecture
+
+- **Pydantic models** parse JSON into typed message structures
+- **Messages** produce `RenderBlock` lists (flexible rendering primitives)
+- **Formatters** convert `RenderBlocks` to output formats (ANSI, Markdown, Plain)
+
+## License
+
+[WTFPL](http://www.wtfpl.net/)

claude_stream-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "claude-stream"
+version = "0.1.0"
+description = "Parse and prettify Claude Code JSONL stream output"
+readme = "README.md"
+license = "WTFPL"
+requires-python = ">=3.10"
+authors = [
+    { name = "Shaun Mitchell" }
+]
+keywords = ["claude", "anthropic", "jsonl", "cli", "stream"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: Public Domain",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "typing_extensions>=4.0",
+]
+
+[project.optional-dependencies]
+watch = [
+    "watchdog>=3.0",
+]
+
+[project.scripts]
+claude-stream = "claude_stream.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/shitchell/claude-stream"
+Repository = "https://github.com/shitchell/claude-stream"
+Issues = "https://github.com/shitchell/claude-stream/issues"

claude_stream-0.1.0/src/claude_stream/__init__.py

@@ -0,0 +1,158 @@
+"""
+Parse and prettify Claude Code JSONL stream output.
+
+Architecture:
+- Pydantic models parse JSON into typed message structures
+- Messages produce RenderBlock lists (flexible rendering primitives)
+- Formatters convert RenderBlocks to output formats (ANSI, Markdown, Plain)
+"""
+
+from __future__ import annotations
+
+# Block types and Style enum
+from .blocks import (
+    AnyBlock,
+    CodeBlock,
+    DividerBlock,
+    HeaderBlock,
+    KeyValueBlock,
+    ListBlock,
+    NestedBlock,
+    RenderBlock,
+    SpacerBlock,
+    Style,
+    TextBlock,
+)
+
+# Formatters
+from .formatters import (
+    ANSIFormatter,
+    Formatter,
+    MarkdownFormatter,
+    PlainFormatter,
+)
+
+# Models, TypedDicts, and parse_message
+from .models import (
+    # TypedDicts
+    CompactMetadata,
+    ContentItem,
+    ImageContentItem,
+    ImageSourceInfo,
+    TextContentItem,
+    ThinkingContentItem,
+    ToolResultContentItem,
+    ToolResultContentValue,
+    ToolResultImageItem,
+    ToolResultTextItem,
+    ToolUseContentItem,
+    UsageInfo,
+    # Content block models
+    ContentBlock,
+    ImageContent,
+    TextContent,
+    ThinkingContent,
+    ToolResultContent,
+    ToolUseContent,
+    # Message models
+    AgentStyleMessage,
+    AssistantMessage,
+    BaseMessage,
+    FileHistorySnapshot,
+    QueueOperationMessage,
+    ResultMessage,
+    SummaryMessage,
+    SystemMessage,
+    SystemStyleMessage,
+    UserMessage,
+    # Discriminated union and parser
+    Message,
+    parse_message,
+    # Config
+    RenderConfig,
+    # Constants
+    TOOL_INPUT_TRUNCATE_LENGTH,
+    TOOL_RESULT_PREVIEW_LINES,
+)
+
+# Stream processing
+from .stream import (
+    process_stream,
+    should_show_message,
+)
+
+# File watching
+from .watcher import (
+    FileWatcher,
+    WATCHDOG_AVAILABLE,
+    watch_path,
+)
+
+# Conditionally export JSONLEventHandler if watchdog is available
+if WATCHDOG_AVAILABLE:
+    from .watcher import JSONLEventHandler
+
+__all__ = [
+    # Blocks
+    "AnyBlock",
+    "CodeBlock",
+    "DividerBlock",
+    "HeaderBlock",
+    "KeyValueBlock",
+    "ListBlock",
+    "NestedBlock",
+    "RenderBlock",
+    "SpacerBlock",
+    "Style",
+    "TextBlock",
+    # Formatters
+    "ANSIFormatter",
+    "Formatter",
+    "MarkdownFormatter",
+    "PlainFormatter",
+    # TypedDicts
+    "CompactMetadata",
+    "ContentItem",
+    "ImageContentItem",
+    "ImageSourceInfo",
+    "TextContentItem",
+    "ThinkingContentItem",
+    "ToolResultContentItem",
+    "ToolResultContentValue",
+    "ToolResultImageItem",
+    "ToolResultTextItem",
+    "ToolUseContentItem",
+    "UsageInfo",
+    # Content blocks
+    "ContentBlock",
+    "ImageContent",
+    "TextContent",
+    "ThinkingContent",
+    "ToolResultContent",
+    "ToolUseContent",
+    # Messages
+    "AgentStyleMessage",
+    "AssistantMessage",
+    "BaseMessage",
+    "FileHistorySnapshot",
+    "Message",
+    "QueueOperationMessage",
+    "ResultMessage",
+    "SummaryMessage",
+    "SystemMessage",
+    "SystemStyleMessage",
+    "UserMessage",
+    # Config and parsing
+    "RenderConfig",
+    "parse_message",
+    # Constants
+    "TOOL_INPUT_TRUNCATE_LENGTH",
+    "TOOL_RESULT_PREVIEW_LINES",
+    # Stream processing
+    "process_stream",
+    "should_show_message",
+    # Watcher
+    "FileWatcher",
+    "WATCHDOG_AVAILABLE",
+    "watch_path",
+]

claude_stream-0.1.0/src/claude_stream/__main__.py

@@ -0,0 +1,14 @@
+"""Allow running as `python -m claude_stream`."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    exit_code: int = 0
+    try:
+        exit_code = main()
+    except KeyboardInterrupt:
+        print("\nexiting", file=sys.stderr)
+
+    sys.exit(exit_code)

claude_stream-0.1.0/src/claude_stream/blocks.py

@@ -0,0 +1,115 @@
+"""Render block types for flexible output rendering.
+
+This module defines the Style enum and all RenderBlock dataclasses used
+as rendering primitives throughout the library.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Style(Enum):
+    """Style hints for rendering."""
+
+    # Text styles
+    BOLD = "bold"
+    DIM = "dim"
+    ITALIC = "italic"
+
+    # Semantic styles
+    ERROR = "error"
+    SUCCESS = "success"
+    WARNING = "warning"
+    INFO = "info"
+
+    # Role styles
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+    TOOL = "tool"
+    THINKING = "thinking"
+    METADATA = "metadata"
+
+
+@dataclass
+class RenderBlock:
+    """Base class for rendering primitives."""
+
+    styles: set[Style] = field(default_factory=set)
+
+
+@dataclass
+class HeaderBlock(RenderBlock):
+    """A header/title block."""
+
+    text: str = ""
+    level: int = 1  # 1 = top level, 2 = subheader, etc.
+    icon: str = ""  # Optional prefix icon
+    prefix: str = ""  # Optional prefix text (e.g., "Summary:", "Tool:")
+
+
+@dataclass
+class TextBlock(RenderBlock):
+    """Plain text content."""
+
+    text: str = ""
+    indent: int = 0  # Indentation level
+
+
+@dataclass
+class CodeBlock(RenderBlock):
+    """Code or preformatted content."""
+
+    content: str = ""
+    language: str = ""
+    indent: int = 0
+
+
+@dataclass
+class KeyValueBlock(RenderBlock):
+    """Key-value pair."""
+
+    key: str = ""
+    value: str = ""
+    indent: int = 0
+
+
+@dataclass
+class DividerBlock(RenderBlock):
+    """Visual separator."""
+
+    char: str = "─"
+    width: int = 40
+
+
+@dataclass
+class ListBlock(RenderBlock):
+    """A list of items."""
+
+    items: list[str] = field(default_factory=list)
+    indent: int = 0
+    bullet: str = "*"
+
+
+@dataclass
+class NestedBlock(RenderBlock):
+    """Container for nested blocks."""
+
+    children: list[RenderBlock] = field(default_factory=list)
+    indent: int = 0
+
+
+@dataclass
+class SpacerBlock(RenderBlock):
+    """Vertical space."""
+
+    lines: int = 1
+
+
+# Type alias for any render block
+AnyBlock = (
+    HeaderBlock | TextBlock | CodeBlock | KeyValueBlock |
+    DividerBlock | ListBlock | NestedBlock | SpacerBlock
+)