mixhub-cli 0.2.0__tar.gz → 0.2.1__tar.gz

mixhub_cli-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: publish
+
+# Push a tag like v0.2.1 to build and upload that version to PyPI.
+# PyPI trusts this workflow (Trusted Publishing), so no token is stored anywhere.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Tag matches the package version
+        run: |
+          v=$(python -c "import mixhub; print(mixhub.__version__)")
+          test "v$v" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME, package $v"; exit 1; }
+      - name: Build
+        run: |
+          python -m pip install -q build
+          python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mixhub_cli-0.2.1/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: "3.10"
+          - os: ubuntu-latest
+            python: "3.13"
+          - os: macos-latest
+            python: "3.13"
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: tmux
+        run: |
+          if [ "$RUNNER_OS" = Linux ]; then sudo apt-get install -y -qq tmux; else brew install tmux; fi
+          tmux -V
+      - run: python -m pip install -q pytest
+      - run: python -m pytest -q -o faulthandler_timeout=60 tests/  # a hung test prints where it is stuck
+      - run: node --test tests/webui_composer.test.mjs

{mixhub_cli-0.2.0 → mixhub_cli-0.2.1}/.gitignore

@@ -58,3 +58,6 @@ tests/test_git_steward.py
 # local launchers for processes started before the root scripts moved
 /tui.py
 /slack_bridge.py
+
+# Maintainer-only two-way extras (Slack bridge, Telegram approvals); imports mixhub, never the reverse
+/mixhub_private/

{mixhub_cli-0.2.0 → mixhub_cli-0.2.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: mixhub-cli
-Version: 0.2.0
-Summary: One switchboard for Claude Code, Gemini (AGY), Codex and OpenCode sessions: a tmux workspace, a web workbench and handoff between agents.
+Version: 0.2.1
+Summary: A terminal sidebar for your Claude Code, Codex, Gemini and OpenCode sessions.
 Project-URL: Homepage, https://github.com/ShinoKana/mixhub
 Project-URL: Repository, https://github.com/ShinoKana/mixhub.git
 Project-URL: Issues, https://github.com/ShinoKana/mixhub/issues
@@ -29,43 +29,52 @@ Description-Content-Type: text/markdown
 
 # MixHub
 
-**One switchboard for Claude Code, Gemini (AGY), Codex and OpenCode sessions**
+**A terminal sidebar for your Claude Code, Codex, Gemini and OpenCode sessions**
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-596F62.svg)](#license)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](#install)
 [![Dependencies: stdlib](https://img.shields.io/badge/python_dependencies-stdlib_only-596F62.svg)](#architecture)
 
-A `tmux` workspace that lists every coding-agent session on your machine in one sidebar, previews any transcript, and runs the real CLI in the right pane. MixHub reads each agent's own files and never patches the agents.
-
 </div>
 
-```text
-┌─ SIDEBAR (32 cols) ────────────┬─ RIGHT PANE (PREVIEW OR LIVE CLI) ───────────────────────────┐
-│  ⌄  mixhub              ‹ ›  ◧ │  ~/workspace/project · a1b2c3d4                              │
-│                                │  ◇ Auth flow                                                 │
-│  ✎  New session                │  ──────────────────────────────────────────────────────────  │
-│  ▾  Pinned 1                   │                                                           ─  │
-│  ◇  Auth flow               ★  │  > Refactor the state machine and run the tests           ━  │
-│  ▾  Active 2                   │    Edited rules_sync.py (+42 -8)                          ─  │
-│  ◈  Payment webhook        2m  │    Ran 43 tests in 0.14s · OK                             ─  │
-│  ◇  API rate limit         5m  │                                                           ─  │
-│  ▾  Recent 4                   │  > Check idempotency on retry                             ━  │
-│  ·  Database migration     3h  │    Verified retry keys and added unit coverage.           ─  │
-│  ·  OAuth token refresh    1d  │                                                              │
-│  claude 83% 03:00   60% 10/30  │  ──────────────────────────────────────────────────────────  │
-│  codex  69% 04:25   41% 10/31  │   [ Resume ↵ ]  [ Go to Tab ]                                │
-│  gemini 86% 02:29   21% 11/01  │                                                              │
-│  ▴ cpu 12%  mem 64%     ↗ web  │                                                              │
-└────────────────────────────────┴──────────────────────────────────────────────────────────────┘
+MixHub is a tmux workspace that lists every coding-agent session on your machine, including the ones you started in other terminal tabs, and shows whether each one is working, waiting for you or done. Click a session and its real CLI opens on the right. The others keep running in the background.
+
+```bash
+pipx install mixhub-cli    # or: uv tool install mixhub-cli
+mixhub
 ```
 
+Early, used daily on macOS with around a dozen sessions. Linux works but gets less testing. Needs Python 3.10+ and tmux.
+
+https://github.com/user-attachments/assets/3c068cd5-b168-4b5c-96a0-208c8a6a908d
+
 ## Why
 
-Agent CLIs keep getting better at what happens inside one session. What they don't do is look across sessions: which of my twelve sessions is waiting for me, which one finished while I was away, which agent still has quota left, and how do I hand a half-done task to another agent. MixHub covers that part and nothing else:
+I usually have several agents going at once, often from different vendors. I kept missing the one that had been sitting on a permission prompt for ten minutes, and losing sessions I had started in some other tab. A terminal tab shows a title, not whether the agent behind it is stuck. MixHub works that out from each agent's own session files and puts all of them in one list.
+
+What it does:
+
+- Lists sessions from Claude Code, Codex, Gemini (Antigravity CLI) and OpenCode, wherever they were started.
+- Marks each one as working, waiting for approval, done or unread. Status comes from the agents' session files; reading the screen is only a fallback.
+- Runs the unmodified CLI in the right pane. Switching sessions switches a tmux window, so nothing is interrupted.
+- Shows 5-hour and weekly quota for each agent at the bottom of the sidebar.
+- Rings the terminal when a session finishes or starts waiting while you're elsewhere.
 
-- It reads the native transcript files and databases in place. There is no import step and no second copy of your history; `claude --resume <id>` keeps working as before.
-- The right pane runs the unmodified CLI. When an agent ships an update, you get it in MixHub without waiting for MixHub.
-- It only adds things that stay useful as agents improve: a cross-agent index, a process pool, quota at a glance, handoff between agents, and notifications.
+What it doesn't do: it doesn't create worktrees or touch git, doesn't patch the agents, and doesn't send anything off your machine unless you set up a notification channel (otherwise the only network call is a daily update check, which you can turn off). It uses its own private tmux servers, so your own tmux config and sessions are left alone.
+
+## Similar tools
+
+| | Agents | Runs in | Git worktrees | Per-session status | Sessions started elsewhere |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| MixHub | Claude Code, Codex, Gemini, OpenCode | any terminal (needs tmux) | no | from session files | listed |
+| [Claude Code Agent View](https://code.claude.com/docs/en/agent-view) | Claude Code | the `claude` CLI | background sessions by default | yes | only after `/bg` or `claude --bg` |
+| [cmux](https://github.com/manaflow-ai/cmux) | Claude Code, Codex, OpenCode, Gemini, Amp and more | its own macOS app | no | notifications via hooks / OSC | not documented |
+| [claude-squad](https://github.com/smtg-ai/claude-squad) | Claude Code, Codex, Gemini, Aider | any terminal (needs tmux) | one per session | not documented | no, manages its own |
+| [ccmanager](https://github.com/kbwo/ccmanager) | Claude Code, Codex, Gemini, OpenCode and more | any terminal | yes, managed in the app | busy / waiting / idle | not documented |
+| [agent-deck](https://github.com/asheshgoplani/agent-deck) | Claude Code, Codex, Gemini, OpenCode and more | any terminal (tmux) | optional | running / waiting / idle | its own tmux sessions |
+| [tmux-agent-status](https://github.com/samleeney/tmux-agent-status) | Claude Code, Codex, Devin | inside your tmux | no | via agent hooks | inside tmux |
+
+If you only use Claude Code, Agent View is built in. If you want a worktree per task, claude-squad and ccmanager do that and MixHub doesn't.
 
 ## Install
 
@@ -86,7 +95,7 @@ The script installs the `mixhub-cli` package (it provides the `mixhub` command)
 ```bash
 mixhub           # open or reattach to the workspace
 mixhub web       # local web workbench at http://127.0.0.1:8765
-mixhub doctor    # check providers, channels, locks and terminal settings
+mixhub doctor    # check agent CLIs, tmux, notification channels and terminal settings
 ```
 
 From a clone:
@@ -118,13 +127,13 @@ mixhub update --check  # only say whether a newer version exists
 
 ## The workspace
 
-**Sidebar.** Sessions are grouped into `Pinned`, `Active` (sessions you are working with) and `Recent`. A row shows the agent's brand-colored badge, the title the agent itself gave the session, and its age. The badge animates while the agent is working and turns into a waiting mark when it needs approval or an answer. Unread replies are bold. `▾ mixhub` filters by agent, `‹ ›` walks back and forward through what you looked at, `◧` collapses the sidebar. Hover a row to pin it. The sidebar is entirely click-driven; keys go to the agent.
+**Sidebar.** Sessions are grouped into `Pinned`, `Active` (sessions you are working with) and `Recent`. A row shows the agent's brand-colored badge, the title the agent itself gave the session, and its age. The badge animates while the agent is working; when the agent needs approval or an answer it stops, turns bold amber, and the age turns yellow. Unread replies are bold. `▾ mixhub` filters by agent, `‹ ›` walks back and forward through what you looked at, `◧` collapses the sidebar. Hover a row to pin it. The sidebar is entirely click-driven; keys go to the agent. Subagent runs, headless or scripted runs, and sessions whose working directory is under `/tmp` are not listed.
 
 **Right pane.** Clicking a session that is running in MixHub switches to its live CLI window. Clicking any other session shows a read-only transcript preview with a turn minimap; `[ Resume ↵ ]` starts the CLI in place, and `[ Go to Tab ]` jumps to a session that is running in another Terminal tab. Each live window has a two-row header with the working directory, session id and title.
 
 **Home.** With nothing selected, the right pane holds a plain login shell under the preview, for quick commands without leaving the workspace. Clear it the usual way (`clear` or Ctrl+L).
 
-**Footer.** Remaining `5h` and weekly quota with reset times for each agent that has at least one session on this machine, plus CPU and memory. Codex quota comes from its own session files. For exact Claude Code and Gemini (AGY) numbers, point their status line at MixHub, which records the quota each agent reports and prints a short status line back:
+**Footer.** Used `5h` and weekly quota with reset times for each agent that has at least one session on this machine, plus CPU and memory. Codex quota comes from its own session files. For exact Claude Code and Gemini (AGY) numbers, point their status line at MixHub, which records the quota each agent reports and prints a short status line back:
 
 ```jsonc
 // ~/.claude/settings.json
@@ -144,15 +153,11 @@ Without it the footer estimates Claude's quota from transcripts.
 
 ## Session lifecycle
 
-MixHub separates whether a session is listed as `Active` from whether its process is running. Idle live sessions are put to sleep (process stopped, session kept in `Active`) and resumed in place when you click them:
+MixHub separates whether a session is listed as `Active` from whether its process is running. Sessions keep running until you `/exit` them or close them from the sidebar. To have idle ones put to sleep (process stopped, session kept in `Active`, resumed in place when you click it), set `auto_sleep_hours` in `Preferences`; it is off by default.
 
-| Condition | Idle time before sleep |
-| :--- | :--- |
-| Normal | 12 hours |
-| Moderate memory pressure | 6 hours |
-| Critical memory pressure, or more than 6 live sessions | 4 hours |
+A session is never put to sleep while it is working or waiting for approval, has running subagents or open background tasks, or has user processes running on its terminal. If the process table can't be read, nothing is put to sleep. Only sessions running in MixHub's own windows are ever put to sleep, automatically or from the web; an agent you started in another terminal is listed but never stopped. `/exit` in the agent moves the session to `Recent`; a system shutdown keeps `Active` as it was.
 
-A session is never put to sleep while it is working or waiting for approval, has running subagents or open background tasks, or has user processes running on its terminal. If the process table can't be read, nothing is put to sleep. `/exit` in the agent moves the session to `Recent`; a system shutdown keeps `Active` as it was.
+On macOS, while an agent is working and the Mac runs on power, MixHub keeps it from idle-sleeping (`caffeinate -i`, released when the work ends; never on battery).
 
 ## Handoff between agents
 
@@ -164,7 +169,7 @@ mixhub handoff SESSION_ID --to claude --mode review
 mixhub handoff SESSION_ID --to agy --dry-run
 ```
 
-The new session is titled `↳ <source title>`. A write lease per working tree records which session is allowed to write, and a relay to a busy session is held until its turn ends.
+The new session is titled `↳ <source title>`.
 
 ## Web workbench and notifications
 
@@ -173,8 +178,45 @@ The new session is titled `↳ <source title>`. A write lease per working tree r
   <img alt="The MixHub web workbench: a session list with quota on the left and a Claude Code transcript on the right" src=".github/assets/web-light.png">
 </picture>
 
-- `mixhub web` serves a loopback-only web UI: search across all sessions, full transcripts, and a phone-friendly bar for approving or stopping a waiting session.
-- `mixhub notify` and the attention hook can send to Telegram, Discord, Slack (Socket Mode bridge), Feishu/Lark, or any webhook or command, with `always`, `auto_idle` and `manual` modes.
+- `mixhub web` serves a loopback-only web UI: search across all sessions and full transcripts. The terminal workspace is where MixHub gets used day to day; the web workbench sees much less use and has rougher edges, so please [open an issue](../../issues) when something there looks wrong.
+- `mixhub notify` sends a one-way message to Telegram, a Slack incoming webhook or any URL that takes a JSON POST. It only tells you something happened; replying and approving stay in the agents' own remote control.
+
+### Notification channels
+
+Nothing is sent until you set up a channel in `~/.config/mixhub/channels.json`. Every section is optional:
+
+```json
+{
+  "telegram": {
+    "bot_token": "123456:ABC...",
+    "chat_id": -1001234567890,
+    "topics": {"builds": 42, "reviews": 57},
+    "default_topic": "builds",
+    "routing_rules": {"reviews": ["review", "pr"]}
+  },
+  "slack": {"webhook_url": "https://hooks.slack.com/services/..."},
+  "webhook": {"url": "https://example.com/mixhub", "headers": {"Authorization": "Bearer ..."}}
+}
+```
+
+- Telegram goes through the Bot API (`sendMessage`, plus `sendDocument` for an attached file). `topics` maps forum topic names to thread ids. A message goes to the topic you name with `--topic`, else the first topic whose `routing_rules` keyword appears in the session's folder, title or the message, else `default_topic`, else the chat itself. To send through your own command instead, set `"tgnotify_bin"`. It is called as `<bin> -t <topic> [--alert] [--file F] <text>`.
+- Slack posts to the channel the incoming webhook belongs to.
+- `webhook` receives `{"text", "title", "session_id", "tool", "topic"}`.
+
+The notification settings in the web workbench (the bell) show which channels are set up and send a test message.
+
+```bash
+mixhub notify "Deploy finished"                  # every configured channel
+mixhub notify --channel telegram --topic builds --alert "Tests failed"
+mixhub notify --session 1a2b3c                   # a short card about that session
+```
+
+To hear when an agent needs you or finishes a turn, add the agents' own hooks. `mixhub notify --print-hooks` prints both snippets with the full path to `mixhub`:
+
+- Claude Code (`~/.claude/settings.json`): `Notification` and `Stop` hooks running `mixhub notify --hook claude`. You get the prompt Claude is waiting on, or the start of its last reply.
+- Codex (`~/.codex/config.toml`): `notify = ["mixhub", "notify", "--hook", "codex"]`, which sends the last reply after each turn.
+
+A hook sends to every configured channel, sends nothing when none is configured, and always exits 0.
 
 ## Language
 
@@ -189,9 +231,9 @@ The web workbench and its API listen on `127.0.0.1` only and have no login. They
 - Other programs and other users on the same machine can reach it. Don't run MixHub on a shared machine you don't trust.
 - Requests from websites in your browser are refused: the server checks the `Host` header (against DNS rebinding), `Origin` and `Sec-Fetch-Site`, only accepts JSON for anything that changes state, and sends a strict Content-Security-Policy.
 - It only answers to `127.0.0.1` and `localhost`, so a reverse proxy or a forwarded port won't work, and shouldn't. To open it from another device, use an SSH tunnel (`ssh -L 8765:127.0.0.1:8765 your-machine`, then `http://localhost:8765`).
-- Notification channels (Telegram, Slack, Discord, Feishu, webhooks) send session titles and message text to those services. Nothing is sent unless you configure a channel.
+- Notification channels (Telegram, Slack, webhooks) send session titles and message text to those services. Nothing is sent unless you configure a channel.
 
-MixHub reads the agents' transcripts and databases without changing them. It writes to agent files only when you ask it to: renaming a session (the title goes where that agent keeps titles), workspace trust you opted into with `trust_all_workspaces` or `trust_roots` (so a resume doesn't stop at the trust prompt), `mixhub slim --apply` (replaces old screenshots in Claude transcripts with a placeholder) and `mixhub sync-rules` (writes `.gemini/GEMINI.md` from `AGENTS.md`).
+MixHub reads the agents' transcripts and databases without changing them. It writes to agent files only when you ask it to: renaming a session (the title goes where that agent keeps titles, also while the session runs: a title record appended to a Claude transcript, a row updated in the Codex or Gemini database), workspace trust you opted into with `trust_all_workspaces` or `trust_roots` (so a resume doesn't stop at the trust prompt) and `mixhub sync-rules` (writes `.gemini/GEMINI.md` from `AGENTS.md`).
 
 ## Configuration
 
@@ -202,13 +244,13 @@ Everything works without configuration. Optional settings live in a JSON file na
 ```json
 {
   "language": "auto",
-  "user_name": "Developer",
-  "claude_theme": false,
+  "host_label": "work-laptop",
   "trust_all_workspaces": false,
   "trust_roots": ["~/workspace"],
   "agy_mouse_shim": "auto",
   "dispatch_scripts": ["my-agent-runner"],
-  "update_check": true
+  "update_check": true,
+  "auto_sleep_hours": 0
 }
 ```
 
@@ -223,7 +265,7 @@ Everything works without configuration. Optional settings live in a JSON file na
 | `MIXHUB_NO_OPEN=1` | `mixhub web` starts the daemon without opening a browser |
 | `MIXHUB_NO_UPDATE_CHECK=1` | No daily update check |
 
-`dispatch_scripts` names your own wrapper scripts that start agents headlessly, so their sessions are not mistaken for interactive ones. Prompts that your own automation sends can be hidden from the list with `data/local_rules.json` (`automated_prefixes`, `automated_substrings`).
+`host_label` is the machine name shown in the web workbench (the hostname by default). `dispatch_scripts` names your own wrapper scripts that start agents headlessly, so their sessions are not mistaken for interactive ones. Prompts that your own automation sends can be hidden from the list with `data/local_rules.json` (`automated_prefixes`, `automated_substrings`). Notes your own tools type into an agent on another agent's behalf go in `relayed_prefixes`: they never count as you having used a session, but don't hide one either.
 
 ## Architecture
 
@@ -235,24 +277,23 @@ Python standard library only. The code lives in the `mixhub` package:
 | `mixhub/providers` | Per-agent launch and resume commands, quota reading, native title sync, harness presets |
 | `mixhub/tui` | The curses sidebar, preview reader and window header (`HubTUI`, composed from one mixin per concern) |
 | `mixhub/tmux` | The two tmux servers: outer workspace, the `hubpool` window pool, headers, home shell |
-| `mixhub/handoff` | Handoff extraction and rendering, write leases, hold queue, clean forks |
-| `mixhub/channels` | Notification adapters, approval ledger, away receipts, Slack bridge |
+| `mixhub/handoff` | Handoff extraction and rendering |
+| `mixhub/channels` | One-way notifications: Telegram Bot API, Slack incoming webhook |
 | `mixhub/probe` | Reading an agent's screen: working, waiting for approval, menus |
 | `mixhub/proc` | Process identity and classification, safe-kill guards |
 | `mixhub/rules` | Shared agent rules compiler and workspace trust |
 | `mixhub/filters/agy_claude` | Optional PTY filter for AGY (theme, cursor, mouse) |
 | `mixhub/web` | Loopback HTTP API and assets for the web workbench |
 | `mixhub/cli` | The `mixhub` command |
-| `mixhub/core` | Shared paths, launch commands, preferences, plugin protocols |
+| `mixhub/core` | Shared paths, launch commands, preferences, session states |
 
 State (pins, working set, caches, logs) lives in `~/.local/share/mixhub` for an installed package, or next to the code in a git checkout; set `MIXHUB_HOME` to put it elsewhere.
 
-The workspace is two tmux servers. The outer session holds the sidebar on the left and, on the right, a client of a private `tmux -L hubpool` server where every live agent runs in its own window. Switching sessions switches that window, so agents keep running untouched while you look elsewhere.
+The workspace is two private tmux servers, neither of them your default one, so MixHub's sessions, options, key bindings and hooks never reach your own tmux. The outer session (`tmux -L mixhub`) holds the sidebar on the left and, on the right, a client of `tmux -L hubpool`, where every live agent runs in its own window. Switching sessions switches that window, so agents keep running untouched while you look elsewhere. Run `mixhub` inside your own tmux and the workspace opens nested in that pane.
 
 ## Roadmap
 
 - An agent-facing command set (list sessions, read another session's recent turns) and a skill so agents can use MixHub themselves.
-- Two-way chat channels: replies in a Telegram topic delivered into the matching session.
 - Broader Linux polish.
 
 ## Development

{mixhub_cli-0.2.0 → mixhub_cli-0.2.1}/Preferences.example

@@ -1,10 +1,10 @@
 {
   "language": "auto",
-  "user_name": "Developer",
-  "claude_theme": false,
+  "host_label": "work-laptop",
   "trust_all_workspaces": false,
   "trust_roots": ["~/workspace"],
   "agy_mouse_shim": "auto",
   "dispatch_scripts": ["my-agent-runner"],
-  "update_check": true
+  "update_check": true,
+  "auto_sleep_hours": 0
 }

{mixhub_cli-0.2.0 → mixhub_cli-0.2.1}/README.md

@@ -2,43 +2,52 @@
 
 # MixHub
 
-**One switchboard for Claude Code, Gemini (AGY), Codex and OpenCode sessions**
+**A terminal sidebar for your Claude Code, Codex, Gemini and OpenCode sessions**
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-596F62.svg)](#license)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](#install)
 [![Dependencies: stdlib](https://img.shields.io/badge/python_dependencies-stdlib_only-596F62.svg)](#architecture)
 
-A `tmux` workspace that lists every coding-agent session on your machine in one sidebar, previews any transcript, and runs the real CLI in the right pane. MixHub reads each agent's own files and never patches the agents.
-
 </div>
 
-```text
-┌─ SIDEBAR (32 cols) ────────────┬─ RIGHT PANE (PREVIEW OR LIVE CLI) ───────────────────────────┐
-│  ⌄  mixhub              ‹ ›  ◧ │  ~/workspace/project · a1b2c3d4                              │
-│                                │  ◇ Auth flow                                                 │
-│  ✎  New session                │  ──────────────────────────────────────────────────────────  │
-│  ▾  Pinned 1                   │                                                           ─  │
-│  ◇  Auth flow               ★  │  > Refactor the state machine and run the tests           ━  │
-│  ▾  Active 2                   │    Edited rules_sync.py (+42 -8)                          ─  │
-│  ◈  Payment webhook        2m  │    Ran 43 tests in 0.14s · OK                             ─  │
-│  ◇  API rate limit         5m  │                                                           ─  │
-│  ▾  Recent 4                   │  > Check idempotency on retry                             ━  │
-│  ·  Database migration     3h  │    Verified retry keys and added unit coverage.           ─  │
-│  ·  OAuth token refresh    1d  │                                                              │
-│  claude 83% 03:00   60% 10/30  │  ──────────────────────────────────────────────────────────  │
-│  codex  69% 04:25   41% 10/31  │   [ Resume ↵ ]  [ Go to Tab ]                                │
-│  gemini 86% 02:29   21% 11/01  │                                                              │
-│  ▴ cpu 12%  mem 64%     ↗ web  │                                                              │
-└────────────────────────────────┴──────────────────────────────────────────────────────────────┘
+MixHub is a tmux workspace that lists every coding-agent session on your machine, including the ones you started in other terminal tabs, and shows whether each one is working, waiting for you or done. Click a session and its real CLI opens on the right. The others keep running in the background.
+
+```bash
+pipx install mixhub-cli    # or: uv tool install mixhub-cli
+mixhub
 ```
 
+Early, used daily on macOS with around a dozen sessions. Linux works but gets less testing. Needs Python 3.10+ and tmux.
+
+https://github.com/user-attachments/assets/3c068cd5-b168-4b5c-96a0-208c8a6a908d
+
 ## Why
 
-Agent CLIs keep getting better at what happens inside one session. What they don't do is look across sessions: which of my twelve sessions is waiting for me, which one finished while I was away, which agent still has quota left, and how do I hand a half-done task to another agent. MixHub covers that part and nothing else:
+I usually have several agents going at once, often from different vendors. I kept missing the one that had been sitting on a permission prompt for ten minutes, and losing sessions I had started in some other tab. A terminal tab shows a title, not whether the agent behind it is stuck. MixHub works that out from each agent's own session files and puts all of them in one list.
+
+What it does:
+
+- Lists sessions from Claude Code, Codex, Gemini (Antigravity CLI) and OpenCode, wherever they were started.
+- Marks each one as working, waiting for approval, done or unread. Status comes from the agents' session files; reading the screen is only a fallback.
+- Runs the unmodified CLI in the right pane. Switching sessions switches a tmux window, so nothing is interrupted.
+- Shows 5-hour and weekly quota for each agent at the bottom of the sidebar.
+- Rings the terminal when a session finishes or starts waiting while you're elsewhere.
 
-- It reads the native transcript files and databases in place. There is no import step and no second copy of your history; `claude --resume <id>` keeps working as before.
-- The right pane runs the unmodified CLI. When an agent ships an update, you get it in MixHub without waiting for MixHub.
-- It only adds things that stay useful as agents improve: a cross-agent index, a process pool, quota at a glance, handoff between agents, and notifications.
+What it doesn't do: it doesn't create worktrees or touch git, doesn't patch the agents, and doesn't send anything off your machine unless you set up a notification channel (otherwise the only network call is a daily update check, which you can turn off). It uses its own private tmux servers, so your own tmux config and sessions are left alone.
+
+## Similar tools
+
+| | Agents | Runs in | Git worktrees | Per-session status | Sessions started elsewhere |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| MixHub | Claude Code, Codex, Gemini, OpenCode | any terminal (needs tmux) | no | from session files | listed |
+| [Claude Code Agent View](https://code.claude.com/docs/en/agent-view) | Claude Code | the `claude` CLI | background sessions by default | yes | only after `/bg` or `claude --bg` |
+| [cmux](https://github.com/manaflow-ai/cmux) | Claude Code, Codex, OpenCode, Gemini, Amp and more | its own macOS app | no | notifications via hooks / OSC | not documented |
+| [claude-squad](https://github.com/smtg-ai/claude-squad) | Claude Code, Codex, Gemini, Aider | any terminal (needs tmux) | one per session | not documented | no, manages its own |
+| [ccmanager](https://github.com/kbwo/ccmanager) | Claude Code, Codex, Gemini, OpenCode and more | any terminal | yes, managed in the app | busy / waiting / idle | not documented |
+| [agent-deck](https://github.com/asheshgoplani/agent-deck) | Claude Code, Codex, Gemini, OpenCode and more | any terminal (tmux) | optional | running / waiting / idle | its own tmux sessions |
+| [tmux-agent-status](https://github.com/samleeney/tmux-agent-status) | Claude Code, Codex, Devin | inside your tmux | no | via agent hooks | inside tmux |
+
+If you only use Claude Code, Agent View is built in. If you want a worktree per task, claude-squad and ccmanager do that and MixHub doesn't.
 
 ## Install
 
@@ -59,7 +68,7 @@ The script installs the `mixhub-cli` package (it provides the `mixhub` command)
 ```bash
 mixhub           # open or reattach to the workspace
 mixhub web       # local web workbench at http://127.0.0.1:8765
-mixhub doctor    # check providers, channels, locks and terminal settings
+mixhub doctor    # check agent CLIs, tmux, notification channels and terminal settings
 ```
 
 From a clone:
@@ -91,13 +100,13 @@ mixhub update --check  # only say whether a newer version exists
 
 ## The workspace
 
-**Sidebar.** Sessions are grouped into `Pinned`, `Active` (sessions you are working with) and `Recent`. A row shows the agent's brand-colored badge, the title the agent itself gave the session, and its age. The badge animates while the agent is working and turns into a waiting mark when it needs approval or an answer. Unread replies are bold. `▾ mixhub` filters by agent, `‹ ›` walks back and forward through what you looked at, `◧` collapses the sidebar. Hover a row to pin it. The sidebar is entirely click-driven; keys go to the agent.
+**Sidebar.** Sessions are grouped into `Pinned`, `Active` (sessions you are working with) and `Recent`. A row shows the agent's brand-colored badge, the title the agent itself gave the session, and its age. The badge animates while the agent is working; when the agent needs approval or an answer it stops, turns bold amber, and the age turns yellow. Unread replies are bold. `▾ mixhub` filters by agent, `‹ ›` walks back and forward through what you looked at, `◧` collapses the sidebar. Hover a row to pin it. The sidebar is entirely click-driven; keys go to the agent. Subagent runs, headless or scripted runs, and sessions whose working directory is under `/tmp` are not listed.
 
 **Right pane.** Clicking a session that is running in MixHub switches to its live CLI window. Clicking any other session shows a read-only transcript preview with a turn minimap; `[ Resume ↵ ]` starts the CLI in place, and `[ Go to Tab ]` jumps to a session that is running in another Terminal tab. Each live window has a two-row header with the working directory, session id and title.
 
 **Home.** With nothing selected, the right pane holds a plain login shell under the preview, for quick commands without leaving the workspace. Clear it the usual way (`clear` or Ctrl+L).
 
-**Footer.** Remaining `5h` and weekly quota with reset times for each agent that has at least one session on this machine, plus CPU and memory. Codex quota comes from its own session files. For exact Claude Code and Gemini (AGY) numbers, point their status line at MixHub, which records the quota each agent reports and prints a short status line back:
+**Footer.** Used `5h` and weekly quota with reset times for each agent that has at least one session on this machine, plus CPU and memory. Codex quota comes from its own session files. For exact Claude Code and Gemini (AGY) numbers, point their status line at MixHub, which records the quota each agent reports and prints a short status line back:
 
 ```jsonc
 // ~/.claude/settings.json
@@ -117,15 +126,11 @@ Without it the footer estimates Claude's quota from transcripts.
 
 ## Session lifecycle
 
-MixHub separates whether a session is listed as `Active` from whether its process is running. Idle live sessions are put to sleep (process stopped, session kept in `Active`) and resumed in place when you click them:
+MixHub separates whether a session is listed as `Active` from whether its process is running. Sessions keep running until you `/exit` them or close them from the sidebar. To have idle ones put to sleep (process stopped, session kept in `Active`, resumed in place when you click it), set `auto_sleep_hours` in `Preferences`; it is off by default.
 
-| Condition | Idle time before sleep |
-| :--- | :--- |
-| Normal | 12 hours |
-| Moderate memory pressure | 6 hours |
-| Critical memory pressure, or more than 6 live sessions | 4 hours |
+A session is never put to sleep while it is working or waiting for approval, has running subagents or open background tasks, or has user processes running on its terminal. If the process table can't be read, nothing is put to sleep. Only sessions running in MixHub's own windows are ever put to sleep, automatically or from the web; an agent you started in another terminal is listed but never stopped. `/exit` in the agent moves the session to `Recent`; a system shutdown keeps `Active` as it was.
 
-A session is never put to sleep while it is working or waiting for approval, has running subagents or open background tasks, or has user processes running on its terminal. If the process table can't be read, nothing is put to sleep. `/exit` in the agent moves the session to `Recent`; a system shutdown keeps `Active` as it was.
+On macOS, while an agent is working and the Mac runs on power, MixHub keeps it from idle-sleeping (`caffeinate -i`, released when the work ends; never on battery).
 
 ## Handoff between agents
 
@@ -137,7 +142,7 @@ mixhub handoff SESSION_ID --to claude --mode review
 mixhub handoff SESSION_ID --to agy --dry-run
 ```
 
-The new session is titled `↳ <source title>`. A write lease per working tree records which session is allowed to write, and a relay to a busy session is held until its turn ends.
+The new session is titled `↳ <source title>`.
 
 ## Web workbench and notifications
 
@@ -146,8 +151,45 @@ The new session is titled `↳ <source title>`. A write lease per working tree r
   <img alt="The MixHub web workbench: a session list with quota on the left and a Claude Code transcript on the right" src=".github/assets/web-light.png">
 </picture>
 
-- `mixhub web` serves a loopback-only web UI: search across all sessions, full transcripts, and a phone-friendly bar for approving or stopping a waiting session.
-- `mixhub notify` and the attention hook can send to Telegram, Discord, Slack (Socket Mode bridge), Feishu/Lark, or any webhook or command, with `always`, `auto_idle` and `manual` modes.
+- `mixhub web` serves a loopback-only web UI: search across all sessions and full transcripts. The terminal workspace is where MixHub gets used day to day; the web workbench sees much less use and has rougher edges, so please [open an issue](../../issues) when something there looks wrong.
+- `mixhub notify` sends a one-way message to Telegram, a Slack incoming webhook or any URL that takes a JSON POST. It only tells you something happened; replying and approving stay in the agents' own remote control.
+
+### Notification channels
+
+Nothing is sent until you set up a channel in `~/.config/mixhub/channels.json`. Every section is optional:
+
+```json
+{
+  "telegram": {
+    "bot_token": "123456:ABC...",
+    "chat_id": -1001234567890,
+    "topics": {"builds": 42, "reviews": 57},
+    "default_topic": "builds",
+    "routing_rules": {"reviews": ["review", "pr"]}
+  },
+  "slack": {"webhook_url": "https://hooks.slack.com/services/..."},
+  "webhook": {"url": "https://example.com/mixhub", "headers": {"Authorization": "Bearer ..."}}
+}
+```
+
+- Telegram goes through the Bot API (`sendMessage`, plus `sendDocument` for an attached file). `topics` maps forum topic names to thread ids. A message goes to the topic you name with `--topic`, else the first topic whose `routing_rules` keyword appears in the session's folder, title or the message, else `default_topic`, else the chat itself. To send through your own command instead, set `"tgnotify_bin"`. It is called as `<bin> -t <topic> [--alert] [--file F] <text>`.
+- Slack posts to the channel the incoming webhook belongs to.
+- `webhook` receives `{"text", "title", "session_id", "tool", "topic"}`.
+
+The notification settings in the web workbench (the bell) show which channels are set up and send a test message.
+
+```bash
+mixhub notify "Deploy finished"                  # every configured channel
+mixhub notify --channel telegram --topic builds --alert "Tests failed"
+mixhub notify --session 1a2b3c                   # a short card about that session
+```
+
+To hear when an agent needs you or finishes a turn, add the agents' own hooks. `mixhub notify --print-hooks` prints both snippets with the full path to `mixhub`:
+
+- Claude Code (`~/.claude/settings.json`): `Notification` and `Stop` hooks running `mixhub notify --hook claude`. You get the prompt Claude is waiting on, or the start of its last reply.
+- Codex (`~/.codex/config.toml`): `notify = ["mixhub", "notify", "--hook", "codex"]`, which sends the last reply after each turn.
+
+A hook sends to every configured channel, sends nothing when none is configured, and always exits 0.
 
 ## Language
 
@@ -162,9 +204,9 @@ The web workbench and its API listen on `127.0.0.1` only and have no login. They
 - Other programs and other users on the same machine can reach it. Don't run MixHub on a shared machine you don't trust.
 - Requests from websites in your browser are refused: the server checks the `Host` header (against DNS rebinding), `Origin` and `Sec-Fetch-Site`, only accepts JSON for anything that changes state, and sends a strict Content-Security-Policy.
 - It only answers to `127.0.0.1` and `localhost`, so a reverse proxy or a forwarded port won't work, and shouldn't. To open it from another device, use an SSH tunnel (`ssh -L 8765:127.0.0.1:8765 your-machine`, then `http://localhost:8765`).
-- Notification channels (Telegram, Slack, Discord, Feishu, webhooks) send session titles and message text to those services. Nothing is sent unless you configure a channel.
+- Notification channels (Telegram, Slack, webhooks) send session titles and message text to those services. Nothing is sent unless you configure a channel.
 
-MixHub reads the agents' transcripts and databases without changing them. It writes to agent files only when you ask it to: renaming a session (the title goes where that agent keeps titles), workspace trust you opted into with `trust_all_workspaces` or `trust_roots` (so a resume doesn't stop at the trust prompt), `mixhub slim --apply` (replaces old screenshots in Claude transcripts with a placeholder) and `mixhub sync-rules` (writes `.gemini/GEMINI.md` from `AGENTS.md`).
+MixHub reads the agents' transcripts and databases without changing them. It writes to agent files only when you ask it to: renaming a session (the title goes where that agent keeps titles, also while the session runs: a title record appended to a Claude transcript, a row updated in the Codex or Gemini database), workspace trust you opted into with `trust_all_workspaces` or `trust_roots` (so a resume doesn't stop at the trust prompt) and `mixhub sync-rules` (writes `.gemini/GEMINI.md` from `AGENTS.md`).
 
 ## Configuration
 
@@ -175,13 +217,13 @@ Everything works without configuration. Optional settings live in a JSON file na
 ```json
 {
   "language": "auto",
-  "user_name": "Developer",
-  "claude_theme": false,
+  "host_label": "work-laptop",
   "trust_all_workspaces": false,
   "trust_roots": ["~/workspace"],
   "agy_mouse_shim": "auto",
   "dispatch_scripts": ["my-agent-runner"],
-  "update_check": true
+  "update_check": true,
+  "auto_sleep_hours": 0
 }
 ```
 
@@ -196,7 +238,7 @@ Everything works without configuration. Optional settings live in a JSON file na
 | `MIXHUB_NO_OPEN=1` | `mixhub web` starts the daemon without opening a browser |
 | `MIXHUB_NO_UPDATE_CHECK=1` | No daily update check |
 
-`dispatch_scripts` names your own wrapper scripts that start agents headlessly, so their sessions are not mistaken for interactive ones. Prompts that your own automation sends can be hidden from the list with `data/local_rules.json` (`automated_prefixes`, `automated_substrings`).
+`host_label` is the machine name shown in the web workbench (the hostname by default). `dispatch_scripts` names your own wrapper scripts that start agents headlessly, so their sessions are not mistaken for interactive ones. Prompts that your own automation sends can be hidden from the list with `data/local_rules.json` (`automated_prefixes`, `automated_substrings`). Notes your own tools type into an agent on another agent's behalf go in `relayed_prefixes`: they never count as you having used a session, but don't hide one either.
 
 ## Architecture
 
@@ -208,24 +250,23 @@ Python standard library only. The code lives in the `mixhub` package:
 | `mixhub/providers` | Per-agent launch and resume commands, quota reading, native title sync, harness presets |
 | `mixhub/tui` | The curses sidebar, preview reader and window header (`HubTUI`, composed from one mixin per concern) |
 | `mixhub/tmux` | The two tmux servers: outer workspace, the `hubpool` window pool, headers, home shell |
-| `mixhub/handoff` | Handoff extraction and rendering, write leases, hold queue, clean forks |
-| `mixhub/channels` | Notification adapters, approval ledger, away receipts, Slack bridge |
+| `mixhub/handoff` | Handoff extraction and rendering |
+| `mixhub/channels` | One-way notifications: Telegram Bot API, Slack incoming webhook |
 | `mixhub/probe` | Reading an agent's screen: working, waiting for approval, menus |
 | `mixhub/proc` | Process identity and classification, safe-kill guards |
 | `mixhub/rules` | Shared agent rules compiler and workspace trust |
 | `mixhub/filters/agy_claude` | Optional PTY filter for AGY (theme, cursor, mouse) |
 | `mixhub/web` | Loopback HTTP API and assets for the web workbench |
 | `mixhub/cli` | The `mixhub` command |
-| `mixhub/core` | Shared paths, launch commands, preferences, plugin protocols |
+| `mixhub/core` | Shared paths, launch commands, preferences, session states |
 
 State (pins, working set, caches, logs) lives in `~/.local/share/mixhub` for an installed package, or next to the code in a git checkout; set `MIXHUB_HOME` to put it elsewhere.
 
-The workspace is two tmux servers. The outer session holds the sidebar on the left and, on the right, a client of a private `tmux -L hubpool` server where every live agent runs in its own window. Switching sessions switches that window, so agents keep running untouched while you look elsewhere.
+The workspace is two private tmux servers, neither of them your default one, so MixHub's sessions, options, key bindings and hooks never reach your own tmux. The outer session (`tmux -L mixhub`) holds the sidebar on the left and, on the right, a client of `tmux -L hubpool`, where every live agent runs in its own window. Switching sessions switches that window, so agents keep running untouched while you look elsewhere. Run `mixhub` inside your own tmux and the workspace opens nested in that pane.
 
 ## Roadmap
 
 - An agent-facing command set (list sessions, read another session's recent turns) and a skill so agents can use MixHub themselves.
-- Two-way chat channels: replies in a Telegram topic delivered into the matching session.
 - Broader Linux polish.
 
 ## Development

{mixhub_cli-0.2.0 → mixhub_cli-0.2.1}/bin/hub

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Idempotent launcher for MixHub / Agent Session Hub (TUI, tmux workspace, handoff, sync-rules, notify, mobile-handoff, install-icons, and Web daemon).
+"""Idempotent launcher for MixHub / Agent Session Hub (TUI, tmux workspace, handoff, sync-rules, notify, and Web daemon).
 
 Thin entry point: the dispatcher and every command live in `mixhub.cli` (`main`, `daemon`, `sessions`, `tools`, `workspace`).
 """