claude-chatter 0.2.1__tar.gz

claude_chatter-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 non7top
+
+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_chatter-0.2.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: claude-chatter
+Version: 0.2.1
+Summary: Claude Code peer messaging protocol and client library.
+Author: non7top
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/non7top/claude-chatter
+Project-URL: Issues, https://github.com/non7top/claude-chatter/issues
+Project-URL: Changelog, https://github.com/non7top/claude-chatter/blob/master/CHANGELOG.md
+Keywords: claude-code,ipc,unix-domain-sockets,peer-messaging
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# claude-chatter
+
+Claude Code peer messaging protocol and client library.
+
+`claude-chatter` provides a standalone Python implementation of the Claude Code peer-to-peer messaging protocol. It handles peer discovery via local session descriptors (`~/.claude/sessions/*.json`), background jobs inspection (`~/.claude/jobs`), UNIX domain socket IPC, NDJSON message framing, and local SQLite mailbox persistence.
+
+This library has no dependencies on FastMCP or Antigravity and can be used directly in any Python application or CLI workflow.
+
+## Installation
+
+```bash
+pip install claude-chatter
+```
+
+## Messaging tools
+
+The library implements the peer messaging tools that Claude Code exposes to its own agents (`SendMessage` and `ListAgents`), so any Python program can act as a peer:
+
+- `ClaudeClient.send_message(target_session, message_content, priority="next")` delivers a message to a live session over its UNIX socket. The target is resolved by name, PID, session id or a partial name match.
+- `ClaudeClient.list_sessions()` returns the live sessions found in `~/.claude/sessions`, with peer tokens redacted unless `redact_tokens=False`. `ClaudeWire.scan_sessions()` does the same without a client.
+
+Received messages are stored in the local mailbox and read with `get_unread_messages()` and `get_history()`. The CLI equivalents are `--send`, `--list`, `--inbox` and `--history`.
+
+## Quick Start
+
+### As a Library
+
+```python
+import asyncio
+from claude_chatter import ClaudeClient, ClaudeWire
+
+async def main():
+    # Stateless discovery
+    sessions = ClaudeWire.scan_sessions()
+    print("Discovered sessions:", sessions)
+
+    # Initialize client node
+    client = ClaudeClient(session_name="my-worker")
+
+    # Send message to an active session
+    res = await client.send_message(
+        target_session="other-session",
+        message_content="Hello from claude-chatter"
+    )
+    print("Send status:", res)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Inbound Message Callback
+
+```python
+async def on_message(event):
+    print(f"Received frame {event['msg_id']} from {event['sender']}: {event['content']}")
+
+client = ClaudeClient(session_name="listener", on_inbound_message=on_message)
+```
+
+### CLI Tool
+
+The package installs both `claude-chatter` and `chatter` CLI entry points:
+
+```bash
+# List all active Claude Code sessions
+claude-chatter --list
+
+# List Claude Code background jobs
+claude-chatter --jobs
+
+# Inspect unread messages from local mailbox
+claude-chatter --inbox
+
+# View full persisted message history
+claude-chatter --history
+
+# Send message to a target session
+claude-chatter --send target-session "Hello peer"
+
+# Run standalone daemon socket listener
+claude-chatter --standalone --name my-daemon
+
+# Proactively scan and purge dead session files
+claude-chatter --purge
+```
+
+## Provenance
+
+`claude-chatter` was extracted from [non7top/claude-chatter-mcp](https://github.com/non7top/claude-chatter-mcp) to provide a reusable, host-independent library for the Claude Code peer messaging protocol with zero MCP dependencies. Full commit history of the protocol core was preserved during the separation.
+
+## License
+
+MIT

claude_chatter-0.2.1/README.md

@@ -0,0 +1,93 @@
+# claude-chatter
+
+Claude Code peer messaging protocol and client library.
+
+`claude-chatter` provides a standalone Python implementation of the Claude Code peer-to-peer messaging protocol. It handles peer discovery via local session descriptors (`~/.claude/sessions/*.json`), background jobs inspection (`~/.claude/jobs`), UNIX domain socket IPC, NDJSON message framing, and local SQLite mailbox persistence.
+
+This library has no dependencies on FastMCP or Antigravity and can be used directly in any Python application or CLI workflow.
+
+## Installation
+
+```bash
+pip install claude-chatter
+```
+
+## Messaging tools
+
+The library implements the peer messaging tools that Claude Code exposes to its own agents (`SendMessage` and `ListAgents`), so any Python program can act as a peer:
+
+- `ClaudeClient.send_message(target_session, message_content, priority="next")` delivers a message to a live session over its UNIX socket. The target is resolved by name, PID, session id or a partial name match.
+- `ClaudeClient.list_sessions()` returns the live sessions found in `~/.claude/sessions`, with peer tokens redacted unless `redact_tokens=False`. `ClaudeWire.scan_sessions()` does the same without a client.
+
+Received messages are stored in the local mailbox and read with `get_unread_messages()` and `get_history()`. The CLI equivalents are `--send`, `--list`, `--inbox` and `--history`.
+
+## Quick Start
+
+### As a Library
+
+```python
+import asyncio
+from claude_chatter import ClaudeClient, ClaudeWire
+
+async def main():
+    # Stateless discovery
+    sessions = ClaudeWire.scan_sessions()
+    print("Discovered sessions:", sessions)
+
+    # Initialize client node
+    client = ClaudeClient(session_name="my-worker")
+
+    # Send message to an active session
+    res = await client.send_message(
+        target_session="other-session",
+        message_content="Hello from claude-chatter"
+    )
+    print("Send status:", res)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Inbound Message Callback
+
+```python
+async def on_message(event):
+    print(f"Received frame {event['msg_id']} from {event['sender']}: {event['content']}")
+
+client = ClaudeClient(session_name="listener", on_inbound_message=on_message)
+```
+
+### CLI Tool
+
+The package installs both `claude-chatter` and `chatter` CLI entry points:
+
+```bash
+# List all active Claude Code sessions
+claude-chatter --list
+
+# List Claude Code background jobs
+claude-chatter --jobs
+
+# Inspect unread messages from local mailbox
+claude-chatter --inbox
+
+# View full persisted message history
+claude-chatter --history
+
+# Send message to a target session
+claude-chatter --send target-session "Hello peer"
+
+# Run standalone daemon socket listener
+claude-chatter --standalone --name my-daemon
+
+# Proactively scan and purge dead session files
+claude-chatter --purge
+```
+
+## Provenance
+
+`claude-chatter` was extracted from [non7top/claude-chatter-mcp](https://github.com/non7top/claude-chatter-mcp) to provide a reusable, host-independent library for the Claude Code peer messaging protocol with zero MCP dependencies. Full commit history of the protocol core was preserved during the separation.
+
+## License
+
+MIT

claude_chatter-0.2.1/claude_chatter/__init__.py

@@ -0,0 +1,21 @@
+"""
+claude-chatter: Generic peer messaging and session protocol library for Claude Code.
+"""
+from .wire import ClaudeWire
+from .client import ClaudeClient
+from .protocol import ClaudeMessagingProtocol
+from .jobs import list_jobs
+from .storage import MessageStore, ResponseStore
+from .exceptions import ChatterError, SessionNameInUseError, StorageError
+
+__all__ = [
+    "ClaudeWire",
+    "ClaudeClient",
+    "ClaudeMessagingProtocol",
+    "list_jobs",
+    "MessageStore",
+    "ResponseStore",
+    "ChatterError",
+    "SessionNameInUseError",
+    "StorageError",
+]

claude_chatter-0.2.1/claude_chatter/cli.py

@@ -0,0 +1,155 @@
+"""
+CLI entry point for claude-chatter: argument parsing and mode dispatch.
+"""
+import os
+import sys
+import json
+import asyncio
+import logging
+import argparse
+from logging.handlers import RotatingFileHandler
+
+if __package__:
+    from .client import ClaudeClient
+    from .standalone import run_standalone
+else:
+    from pathlib import Path
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+    from claude_chatter.client import ClaudeClient
+    from claude_chatter.standalone import run_standalone
+
+_LOG_FORMAT = "%(asctime)s [%(levelname)s] [pid=%(process)d] %(message)s"
+_log_handlers = [logging.StreamHandler(sys.stderr)]
+try:
+    _log_dir = os.path.expanduser("~/.claude/logs")
+    os.makedirs(_log_dir, exist_ok=True)
+    _log_handlers.append(
+        RotatingFileHandler(
+            os.path.join(_log_dir, "claude-chatter.log"),
+            maxBytes=5 * 1024 * 1024,
+            backupCount=3
+        )
+    )
+except OSError:
+    pass
+
+logging.basicConfig(level=logging.INFO, format=_LOG_FORMAT, handlers=_log_handlers)
+logger = logging.getLogger("claude_chatter")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Claude Code peer messaging protocol and client CLI tool")
+    parser.add_argument("--socket", type=str, default=None, help="Path to bridge Unix socket")
+    parser.add_argument("--name", type=str, default=None, help="Session name announced to Claude Code (default: derived from cwd)")
+    parser.add_argument("--db", type=str, default=None, help="Path to SQLite database for message persistence")
+    parser.add_argument("--project-path", type=str, default=None, help="Explicit project directory path")
+
+    mode_group = parser.add_argument_group("Execution Modes")
+    mode_group.add_argument("--standalone", "--daemon", action="store_true", help="Run as standalone daemon listener")
+    mode_group.add_argument("--list", action="store_true", help="List all active Claude Code sessions")
+    mode_group.add_argument("--jobs", action="store_true", help="List Claude Code background jobs from ~/.claude/jobs")
+    mode_group.add_argument("--inbox", action="store_true", help="List unread inbound messages from persisted inbox")
+    mode_group.add_argument("--history", action="store_true", help="List full persisted message history")
+    mode_group.add_argument("--send", nargs=2, metavar=("SESSION", "MESSAGE"), help="Send message to target Claude Code session")
+    mode_group.add_argument("--purge", action="store_true", help="Proactively scan and purge dead session files")
+
+    args = parser.parse_args()
+
+    if args.list:
+        client = ClaudeClient(bridge_socket_path=args.socket, session_name=args.name, enable_storage=False, as_bridge=False, project_path=args.project_path)
+
+        async def _cmd_list():
+            peers = await client.verify_and_purge_sessions()
+            print(json.dumps(client.redact_peers(peers), indent=2))
+        asyncio.run(_cmd_list())
+        sys.exit(0)
+
+    elif args.jobs:
+        from .jobs import list_jobs
+        client = ClaudeClient(bridge_socket_path=args.socket, session_name=args.name, enable_storage=False, as_bridge=False, project_path=args.project_path)
+
+        async def _cmd_jobs():
+            peers = await client.verify_and_purge_sessions()
+            print(json.dumps(list_jobs(live_sessions=peers), indent=2))
+        asyncio.run(_cmd_jobs())
+        sys.exit(0)
+
+    elif args.inbox:
+        target_name = ClaudeClient.resolve_session_name(args.name, project_path=args.project_path, db_path=args.db)
+        if not target_name:
+            print(json.dumps({}, indent=2))
+            sys.exit(0)
+        db_file = args.db or os.environ.get("CHATTER_DB_PATH") or os.path.join(os.path.expanduser("~"), ".claude", "chatter-messages.db")
+        if not os.path.exists(db_file):
+            print(json.dumps({}, indent=2))
+            sys.exit(0)
+        from .storage import MessageStore
+        store = MessageStore(db_file, read_only=True)
+        all_msgs = store.load_session_messages(target_name)
+        unread = {
+            k: v for k, v in all_msgs.items()
+            if v.get("direction") == "inbound" and not v.get("read", False)
+        }
+        unread = dict(sorted(unread.items(), key=lambda kv: kv[1].get("timestamp", 0)))
+        print(json.dumps(unread, indent=2))
+        store.close()
+        sys.exit(0)
+
+    elif args.history:
+        target_name = ClaudeClient.resolve_session_name(args.name, project_path=args.project_path, db_path=args.db)
+        if not target_name:
+            print(json.dumps({}, indent=2))
+            sys.exit(0)
+        db_file = args.db or os.environ.get("CHATTER_DB_PATH") or os.path.join(os.path.expanduser("~"), ".claude", "chatter-messages.db")
+        if not os.path.exists(db_file):
+            print(json.dumps({}, indent=2))
+            sys.exit(0)
+        from .storage import MessageStore
+        store = MessageStore(db_file, read_only=True)
+        all_msgs = store.load_session_messages(target_name)
+        all_msgs = dict(sorted(all_msgs.items(), key=lambda kv: kv[1].get("timestamp", 0)))
+        print(json.dumps(all_msgs, indent=2))
+        store.close()
+        sys.exit(0)
+
+    elif args.purge:
+        client = ClaudeClient(bridge_socket_path=args.socket, session_name=args.name, enable_storage=False, as_bridge=False, project_path=args.project_path)
+
+        async def _cmd_purge():
+            peers = await client.verify_and_purge_sessions()
+            print(f"Purge scan completed. Active sessions remaining: {len(peers)}")
+        asyncio.run(_cmd_purge())
+        sys.exit(0)
+
+    elif args.send:
+        client = ClaudeClient(bridge_socket_path=args.socket, session_name=args.name, enable_storage=False, as_bridge=False, project_path=args.project_path)
+        target_session, message_text = args.send[0], args.send[1]
+
+        async def _cmd_send():
+            res = await client.send_message(
+                target_session=target_session,
+                message_content=message_text
+            )
+            print(json.dumps(res, indent=2))
+            if not res.get("success"):
+                sys.exit(1)
+        asyncio.run(_cmd_send())
+        sys.exit(0)
+
+    elif args.standalone:
+        client = ClaudeClient(bridge_socket_path=args.socket, session_name=args.name, db_path=args.db, as_bridge=True, project_path=args.project_path)
+        try:
+            asyncio.run(run_standalone(client))
+        except (KeyboardInterrupt, SystemExit):
+            logger.info("Shutting down standalone daemon gracefully.")
+        except Exception as e:
+            logger.error(f"Fatal standalone server error: {e}")
+            sys.exit(0)
+
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()