mixhub-cli 0.1.0__tar.gz

mixhub_cli-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Runtime & user session state (never committed)
+data/
+screenshots/
+*.log
+.hub.pid
+.hub.lock
+hub_state.json
+ACCEPTANCE.md
+
+# Python & OS caches
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store

mixhub_cli-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: mixhub-cli
+Version: 0.1.0
+Summary: MixHub: Cross-agent coding session multiplexer, lossless 10-section handoff engine, SSoT rules compiler, and universal mobile control bus for Claude Code, Gemini, and OpenAI Codex.
+Project-URL: Homepage, https://github.com/ShinoKana/mixhub
+Project-URL: Repository, https://github.com/ShinoKana/mixhub.git
+Author: Kana
+License: MIT
+Keywords: ai-agents,claude-code,codex,gemini,handoff,multiplexer,tmux
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# MixHub (Agent Session Hub)
+
+> *"Runners change. The task runs on. — High-ROI daily workhorses meet top-tier masterminds, with lossless cross-agent handoff and universal mobile control."*
+
+A zero-dependency cross-agent workspace, lossless handoff engine, SSoT rules compiler, and universal mobile control bus (`tmux` + `curses` + local HTTP/Web UI) for **Claude Code**, **Google Gemini (`agy`)**, **OpenAI Codex**, and **DeepSeek**.
+
+## Key Features
+
+- **Dual-Pane In-Place Live Workspace (`mixhub` / `hub` / `hub workspace`)**
+  - **Left 32-Column Sidebar**: Displays all live and archived sessions with brand-colored state dots (`★` pinned, `●` live, `·` dormant; `●●` dual brand dots for cross-agent relay sessions) and draggable split border (`⋮`).
+  - **Right 80% Dynamic Pane (`tmux -L hubpool`)**:
+    - **Dormant sessions** open instantaneously in a zero-RAM archive reader (`--reader`) with sticky prompt headers, `[` / `]` user-turn jumping, and a right-edge turn minimap rail.
+    - **Pressing `Enter` or `→`** automatically releases any idle external session lock and attaches the live interactive CLI in-place inside the right pane.
+- **Cross-Agent 10-Section + `handoff.yaml` Directional Handoff & Write Fence (`hub handoff <id> --to claude|agy|codex|deepseek [--mode auto|escalate|delegate|review]`)**
+  - Enforces a SQLite WAL `QUIESCING -> SOURCE_FENCED` write-lease fence (`tasks`, `handoff_bundles`, `write_leases`) with `workspace_epoch` tracking before starting a new writer.
+  - Deterministically extracts both a structured `data/handoffs/<id>.yaml` contract (`task`, `status`, `mode`, `repository`, `verified`, `unverified`, `failed_attempts`) and a `<2000 tokens` 10-section Handoff Bundle (`data/handoffs/<id>.md`).
+  - **3-Mode Directional Filtering**:
+    - `escalate` (Weak/Daily -> Strong Mastermind): strips predecessor subjective narrative (`de_anchored: true`) to prevent anchoring on flawed paths.
+    - `delegate` (Mastermind -> Workhorse / Quota Relay): preserves `decisions_rationale`, `rejected_approaches`, `interface_contracts`, and `acceptance_criteria`.
+    - `review` (Cross-Vendor Blind Review): strips developer self-justification (`blind_review: true`, `status: ready_for_review`) to prevent correlated blindness.
+  - Native `--provider deepseek` support via `codex --no-daemon -c model_provider="deepseek"`.
+- **`AGENTS.md` Single Source of Truth Bidirectional Compiler (`hub sync-rules [dir]`)**
+  - Compiles project root `AGENTS.md` into `CLAUDE.md` (with `@AGENTS.md` + managed block) and `.gemini/GEMINI.md` (`<!-- BEGIN HUB SYNC -->...<!-- END HUB SYNC -->`) with `--dry-run` unified diff preview, SHA-256 tamper detection, and `hub-policy` digest approval guard.
+- **Agent-Agnostic Two-Way Bridge & Task-Level Topic Continuity (`hub notify`)**
+  - **Inbound (`send_to_session` / `handle_inbound_message`)**: Routes messages and local multimodal image paths from Telegram Topics / Discord Threads / Slack `thread_ts` (`/bind <id>`, `/use claude|codex|agy`) to controlled `tmux` panes (`tmux send-keys`) or headless session resume (`claude --resume <id> -p`, `codex exec resume <id>`).
+  - **Outbound (`poll_outbound_replies`)**: Monitors bound `.jsonl` transcripts (`claude`, `codex`, `agy`) with SQLite watermarks; replies exceeding 80 lines are automatically saved as `.md` files and dispatched as document attachments (`--file`).
+  - **Cross-Agent Topic Continuity**: Topic / Thread bindings attach to the task (`task_id`); when handing off across agents (`claude -> codex -> agy`), the new session automatically inherits the bound Telegram Topic / Slack `thread_ts` / Discord `thread_id` without dropping the conversation thread.
+- **100% ToS-Compliant Two-Tier Remote Architecture**
+  - **Zero OAuth Token Extraction**: MixHub never reads, extracts, or proxies any third-party cloud OAuth token or subscription credential.
+  - **Tier 1 (First-Party Native Remote Apps)**: Prioritizes Anthropic's official `claude --resume <id> --remote-control` (Claude iOS App / `claude.ai/code`) and OpenAI's official `ChatGPT.app` / ChatGPT Mobile App (`hub codex-release-lock <id>`).
+  - **Tier 2 (Official Hooks & Local Personal Bridge)**: Integrates via Claude Code's documented `Stop` / `Notification` hooks (`~/.claude/settings.json`) and Codex's `notify` hook (`~/.codex/config.toml`), with optional strict notify-only guard (`enable_local_pty_input=False`).
+- **Fable 5.1 Modular Protocols & Health Check (`protocols.py` / `hub doctor`)**
+  - Defines the 4 narrow-waist `@runtime_checkable` protocols (`Provider`, `Channel`, `Quirk`, `Theme`) with `safe()` fault isolation (3 consecutive plugin failures auto-degrade without crashing the kernel) and 90-day `sunset` / `evaporate_when` Quirk audits.
+- **Hybrid-Brain Cost & ROI Report Calculator (`cost_report.py` / `hub report`)**
+  - Quantifies token and USD savings across local sessions using authoritative binary pricing tiers (`Claude Fable 5.1`, `Claude Opus 5.5`, `Gemini 4 Argon`, `GPT-6 Astra`, `GPT-6.1 Sol`, `DeepSeek V4 Pro`), cumulative multi-turn context growth, and 5-minute active Cache TTL window refreshes (`$5.00/1M` on Opus 5.5).
+  - **Practical 85/15 Hybrid Sizing Guidance**: By routing `85%` of high-frequency file reading, iteration, and test execution to daily workhorses (`Argon`, `Sol`, `DeepSeek`) and invoking top-tier masterminds (`Opus 5.5`, `Fable 5.1`, `Astra`) for the `15%` critical architecture and blind-review checkpoints via `<2k` `handoff.yaml` bundles, high-intensity developers typically require only **`~$15–$30/month`** in top-tier API quota (or a base tier subscription) for full-month coverage.
+  - Includes a restrained Claude Code-style 5-second ephemeral toast (`✦ Handoff 84.2k → 1.2k ctx (-83.0k tokens · ~$2.40 saved) · How was this handoff? [1] Great  [2] Fine  [3] Dismiss`) and a reproducible 60-turn A/B benchmark (`tests/test_handoff_ab.py`).
+- **5 Unified Semantic Channel Primitives Across Telegram, Discord, Slack & Feishu/Lark (`channels.py`)**
+  - Exposes 5 cohesive cross-platform methods (`thinking`, `progress`, `brief`, `ask`, `handoff_notice`) + first-class `typing_context` breathing indicator (`sendChatAction("typing")` / `assistant.threads.setStatus`), `<blockquote expandable>` / CardKit 2.0 `collapsible_panel` collapsible blocks, `copy_text` one-tap clipboard buttons, OpenAI Opus voice notes (`sendVoice`), and Slack Canvas sync.
+- **Official Brand Vector SVGs & PUA Font Generator (`hub install-icons`)**
+  - Web UI (`http://127.0.0.1:8765`) renders authentic vector SVGs for Anthropic Claude, Google Gemini, and OpenAI Codex with stacked avatar badges for cross-agent relays and local time-of-day greetings.
+  - `hub install-icons` generates `~/Library/Fonts/HubIcons.ttf` (`\uE900-\uE902`) when `fontTools` is available and gracefully falls back to brand-colored `●`.
+
+## Quick Start
+
+```bash
+ln -sf ~/.gemini/session-hub/bin/hub ~/.local/bin/hub
+ln -sf ~/.gemini/session-hub/bin/mixhub ~/.local/bin/mixhub
+```
+
+### Commands
+
+| Command | Description |
+| :--- | :--- |
+| `mixhub` / `hub` / `hub workspace` | Open the dual-pane in-place workspace (32-col left sidebar + right live/reader pane) |
+| `hub tui` | Open the single-window TUI browser |
+| `hub handoff <id> --to <agent>` | Fence source session and generate 10-section `<2000 tok` handoff bundle (`claude\|agy\|codex\|deepseek`) |
+| `hub sync-rules [dir] [--dry-run]` | Synchronize `AGENTS.md` (SSoT) with `CLAUDE.md` and `.gemini/GEMINI.md` |
+| `hub notify [options] <message>` | Send plain-text notifications / mobile cards to Telegram, Discord, or Slack |
+| `hub codex-release-lock <id>` | Release terminal Codex writer lock for instant `ChatGPT.app` / mobile takeover |
+| `hub mobile-handoff <id>` | Switch session to `NATIVE_EXTERNAL` mobile control mode |
+| `hub install-icons` | Generate `HubIcons.ttf` PUA vector font (`\uE900-\uE902`) or verify `●` fallback |
+| `hub doctor [--json]` | Run Fable 5.1 modular health check across Providers, Channels, Locks, and Quirks |
+| `hub report [--format terminal\|mobile\|markdown\|json]` | Calculate High-Low Brain Hybrid token & USD savings report |
+| `hub anchor [id]` | Generate zero-token Markdown fact anchors from raw JSONL transcripts |
+| `hub slim [--dry-run]` | Strip historical base64 screenshots (>7d) and expired subagent logs (>1d) |
+| `hub web` | Open the local MixHub web workspace (`http://127.0.0.1:8765`) |
+
+## Running Tests
+
+```bash
+python3 -m unittest discover -s tests -v
+```

mixhub_cli-0.1.0/README.md

@@ -0,0 +1,73 @@
+# MixHub (Agent Session Hub)
+
+> *"Runners change. The task runs on. — High-ROI daily workhorses meet top-tier masterminds, with lossless cross-agent handoff and universal mobile control."*
+
+A zero-dependency cross-agent workspace, lossless handoff engine, SSoT rules compiler, and universal mobile control bus (`tmux` + `curses` + local HTTP/Web UI) for **Claude Code**, **Google Gemini (`agy`)**, **OpenAI Codex**, and **DeepSeek**.
+
+## Key Features
+
+- **Dual-Pane In-Place Live Workspace (`mixhub` / `hub` / `hub workspace`)**
+  - **Left 32-Column Sidebar**: Displays all live and archived sessions with brand-colored state dots (`★` pinned, `●` live, `·` dormant; `●●` dual brand dots for cross-agent relay sessions) and draggable split border (`⋮`).
+  - **Right 80% Dynamic Pane (`tmux -L hubpool`)**:
+    - **Dormant sessions** open instantaneously in a zero-RAM archive reader (`--reader`) with sticky prompt headers, `[` / `]` user-turn jumping, and a right-edge turn minimap rail.
+    - **Pressing `Enter` or `→`** automatically releases any idle external session lock and attaches the live interactive CLI in-place inside the right pane.
+- **Cross-Agent 10-Section + `handoff.yaml` Directional Handoff & Write Fence (`hub handoff <id> --to claude|agy|codex|deepseek [--mode auto|escalate|delegate|review]`)**
+  - Enforces a SQLite WAL `QUIESCING -> SOURCE_FENCED` write-lease fence (`tasks`, `handoff_bundles`, `write_leases`) with `workspace_epoch` tracking before starting a new writer.
+  - Deterministically extracts both a structured `data/handoffs/<id>.yaml` contract (`task`, `status`, `mode`, `repository`, `verified`, `unverified`, `failed_attempts`) and a `<2000 tokens` 10-section Handoff Bundle (`data/handoffs/<id>.md`).
+  - **3-Mode Directional Filtering**:
+    - `escalate` (Weak/Daily -> Strong Mastermind): strips predecessor subjective narrative (`de_anchored: true`) to prevent anchoring on flawed paths.
+    - `delegate` (Mastermind -> Workhorse / Quota Relay): preserves `decisions_rationale`, `rejected_approaches`, `interface_contracts`, and `acceptance_criteria`.
+    - `review` (Cross-Vendor Blind Review): strips developer self-justification (`blind_review: true`, `status: ready_for_review`) to prevent correlated blindness.
+  - Native `--provider deepseek` support via `codex --no-daemon -c model_provider="deepseek"`.
+- **`AGENTS.md` Single Source of Truth Bidirectional Compiler (`hub sync-rules [dir]`)**
+  - Compiles project root `AGENTS.md` into `CLAUDE.md` (with `@AGENTS.md` + managed block) and `.gemini/GEMINI.md` (`<!-- BEGIN HUB SYNC -->...<!-- END HUB SYNC -->`) with `--dry-run` unified diff preview, SHA-256 tamper detection, and `hub-policy` digest approval guard.
+- **Agent-Agnostic Two-Way Bridge & Task-Level Topic Continuity (`hub notify`)**
+  - **Inbound (`send_to_session` / `handle_inbound_message`)**: Routes messages and local multimodal image paths from Telegram Topics / Discord Threads / Slack `thread_ts` (`/bind <id>`, `/use claude|codex|agy`) to controlled `tmux` panes (`tmux send-keys`) or headless session resume (`claude --resume <id> -p`, `codex exec resume <id>`).
+  - **Outbound (`poll_outbound_replies`)**: Monitors bound `.jsonl` transcripts (`claude`, `codex`, `agy`) with SQLite watermarks; replies exceeding 80 lines are automatically saved as `.md` files and dispatched as document attachments (`--file`).
+  - **Cross-Agent Topic Continuity**: Topic / Thread bindings attach to the task (`task_id`); when handing off across agents (`claude -> codex -> agy`), the new session automatically inherits the bound Telegram Topic / Slack `thread_ts` / Discord `thread_id` without dropping the conversation thread.
+- **100% ToS-Compliant Two-Tier Remote Architecture**
+  - **Zero OAuth Token Extraction**: MixHub never reads, extracts, or proxies any third-party cloud OAuth token or subscription credential.
+  - **Tier 1 (First-Party Native Remote Apps)**: Prioritizes Anthropic's official `claude --resume <id> --remote-control` (Claude iOS App / `claude.ai/code`) and OpenAI's official `ChatGPT.app` / ChatGPT Mobile App (`hub codex-release-lock <id>`).
+  - **Tier 2 (Official Hooks & Local Personal Bridge)**: Integrates via Claude Code's documented `Stop` / `Notification` hooks (`~/.claude/settings.json`) and Codex's `notify` hook (`~/.codex/config.toml`), with optional strict notify-only guard (`enable_local_pty_input=False`).
+- **Fable 5.1 Modular Protocols & Health Check (`protocols.py` / `hub doctor`)**
+  - Defines the 4 narrow-waist `@runtime_checkable` protocols (`Provider`, `Channel`, `Quirk`, `Theme`) with `safe()` fault isolation (3 consecutive plugin failures auto-degrade without crashing the kernel) and 90-day `sunset` / `evaporate_when` Quirk audits.
+- **Hybrid-Brain Cost & ROI Report Calculator (`cost_report.py` / `hub report`)**
+  - Quantifies token and USD savings across local sessions using authoritative binary pricing tiers (`Claude Fable 5.1`, `Claude Opus 5.5`, `Gemini 4 Argon`, `GPT-6 Astra`, `GPT-6.1 Sol`, `DeepSeek V4 Pro`), cumulative multi-turn context growth, and 5-minute active Cache TTL window refreshes (`$5.00/1M` on Opus 5.5).
+  - **Practical 85/15 Hybrid Sizing Guidance**: By routing `85%` of high-frequency file reading, iteration, and test execution to daily workhorses (`Argon`, `Sol`, `DeepSeek`) and invoking top-tier masterminds (`Opus 5.5`, `Fable 5.1`, `Astra`) for the `15%` critical architecture and blind-review checkpoints via `<2k` `handoff.yaml` bundles, high-intensity developers typically require only **`~$15–$30/month`** in top-tier API quota (or a base tier subscription) for full-month coverage.
+  - Includes a restrained Claude Code-style 5-second ephemeral toast (`✦ Handoff 84.2k → 1.2k ctx (-83.0k tokens · ~$2.40 saved) · How was this handoff? [1] Great  [2] Fine  [3] Dismiss`) and a reproducible 60-turn A/B benchmark (`tests/test_handoff_ab.py`).
+- **5 Unified Semantic Channel Primitives Across Telegram, Discord, Slack & Feishu/Lark (`channels.py`)**
+  - Exposes 5 cohesive cross-platform methods (`thinking`, `progress`, `brief`, `ask`, `handoff_notice`) + first-class `typing_context` breathing indicator (`sendChatAction("typing")` / `assistant.threads.setStatus`), `<blockquote expandable>` / CardKit 2.0 `collapsible_panel` collapsible blocks, `copy_text` one-tap clipboard buttons, OpenAI Opus voice notes (`sendVoice`), and Slack Canvas sync.
+- **Official Brand Vector SVGs & PUA Font Generator (`hub install-icons`)**
+  - Web UI (`http://127.0.0.1:8765`) renders authentic vector SVGs for Anthropic Claude, Google Gemini, and OpenAI Codex with stacked avatar badges for cross-agent relays and local time-of-day greetings.
+  - `hub install-icons` generates `~/Library/Fonts/HubIcons.ttf` (`\uE900-\uE902`) when `fontTools` is available and gracefully falls back to brand-colored `●`.
+
+## Quick Start
+
+```bash
+ln -sf ~/.gemini/session-hub/bin/hub ~/.local/bin/hub
+ln -sf ~/.gemini/session-hub/bin/mixhub ~/.local/bin/mixhub
+```
+
+### Commands
+
+| Command | Description |
+| :--- | :--- |
+| `mixhub` / `hub` / `hub workspace` | Open the dual-pane in-place workspace (32-col left sidebar + right live/reader pane) |
+| `hub tui` | Open the single-window TUI browser |
+| `hub handoff <id> --to <agent>` | Fence source session and generate 10-section `<2000 tok` handoff bundle (`claude\|agy\|codex\|deepseek`) |
+| `hub sync-rules [dir] [--dry-run]` | Synchronize `AGENTS.md` (SSoT) with `CLAUDE.md` and `.gemini/GEMINI.md` |
+| `hub notify [options] <message>` | Send plain-text notifications / mobile cards to Telegram, Discord, or Slack |
+| `hub codex-release-lock <id>` | Release terminal Codex writer lock for instant `ChatGPT.app` / mobile takeover |
+| `hub mobile-handoff <id>` | Switch session to `NATIVE_EXTERNAL` mobile control mode |
+| `hub install-icons` | Generate `HubIcons.ttf` PUA vector font (`\uE900-\uE902`) or verify `●` fallback |
+| `hub doctor [--json]` | Run Fable 5.1 modular health check across Providers, Channels, Locks, and Quirks |
+| `hub report [--format terminal\|mobile\|markdown\|json]` | Calculate High-Low Brain Hybrid token & USD savings report |
+| `hub anchor [id]` | Generate zero-token Markdown fact anchors from raw JSONL transcripts |
+| `hub slim [--dry-run]` | Strip historical base64 screenshots (>7d) and expired subagent logs (>1d) |
+| `hub web` | Open the local MixHub web workspace (`http://127.0.0.1:8765`) |
+
+## Running Tests
+
+```bash
+python3 -m unittest discover -s tests -v
+```