muxtower 0.1.0__tar.gz

muxtower-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: muxtower
+Version: 0.1.0
+Summary: Approve and drive coding agents running in tmux on a remote machine, from your phone. Headless daemon + API, one Bearer token, works behind any reverse proxy.
+License-Expression: Apache-2.0
+Keywords: tmux,claude-code,codex,coding-agent,remote,approval,pwa
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: fastapi (>=0.115)
+Requires-Dist: httpx (>=0.27)
+Requires-Dist: libtmux (>=0.61)
+Requires-Dist: pydantic (>=2.7)
+Requires-Dist: pywebpush (>=2.0)
+Requires-Dist: segno (>=1.6)
+Requires-Dist: uvicorn[standard] (>=0.30)
+Requires-Dist: websockets (>=14)
+Description-Content-Type: text/markdown
+
+# muxtower (Python package)
+
+`pipx install muxtower` installs one command, `muxtower`:
+
+- `muxtower serve` — run the daemon: the API under `/v1` and the web app at `/`.
+- `muxtower token add|list|revoke` — manage device tokens.
+
+See the repository README and `docs/design.md`.
+

muxtower-0.1.0/README.md

@@ -0,0 +1,8 @@
+# muxtower (Python package)
+
+`pipx install muxtower` installs one command, `muxtower`:
+
+- `muxtower serve` — run the daemon: the API under `/v1` and the web app at `/`.
+- `muxtower token add|list|revoke` — manage device tokens.
+
+See the repository README and `docs/design.md`.

muxtower-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "muxtower"
+version = "0.1.0"
+description = "Approve and drive coding agents running in tmux on a remote machine, from your phone. Headless daemon + API, one Bearer token, works behind any reverse proxy."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11,<4.0"
+keywords = ["tmux", "claude-code", "codex", "coding-agent", "remote", "approval", "pwa"]
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+    "pydantic>=2.7",
+    "libtmux>=0.61",
+    "pywebpush>=2.0",
+    "segno>=1.6",
+    "httpx>=0.27",  # vendored claude_rc (Remote Control), joining a hub
+    "websockets>=14",  # Codex's app-server, a node's link to its hub
+]
+
+[project.scripts]
+muxtower = "muxtower.cli.main:main"
+
+[tool.poetry]
+packages = [{ include = "muxtower", from = "src" }]
+# The built UI is copied into src/muxtower/web/ by `make wheel`; it is git-ignored, so include it explicitly.
+include = [{ path = "src/muxtower/web/**/*", format = ["sdist", "wheel"] }]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3"
+pytest-asyncio = "^0.24"
+httpx = "^0.27"
+ruff = "^0.7"
+mypy = "^1.13"
+
+[build-system]
+requires = ["poetry-core>=2.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 120
+extend-exclude = ["src/muxtower/vendor"]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "S", "BLE"]
+ignore = ["S101"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S105", "S106"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+ignore_missing_imports = true
+exclude = ["src/muxtower/vendor/"]
+
+[[tool.mypy.overrides]]
+module = "muxtower.vendor.*"
+follow_imports = "skip"

muxtower-0.1.0/src/muxtower/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("muxtower")  # the one in pyproject.toml, as installed
+except PackageNotFoundError:  # pragma: no cover - run without being installed
+    __version__ = "0.0.0"

muxtower-0.1.0/src/muxtower/__main__.py

@@ -0,0 +1,3 @@
+from muxtower.cli.main import main
+
+main()

muxtower-0.1.0/src/muxtower/agent_text.py

@@ -0,0 +1,31 @@
+"""Turning agent tool calls and long text into the short lines a phone or glasses can show."""
+
+import json
+from typing import Any
+
+DETAIL_LIMIT = 4000
+
+
+def truncate(text: str) -> str:
+    return text if len(text) <= DETAIL_LIMIT else text[:DETAIL_LIMIT] + "…"
+
+
+def tool_description(tool_input: Any) -> str | None:
+    """What the agent said a tool call does, when it said (Claude Code's Bash and Task take one)."""
+    value = tool_input.get("description") if isinstance(tool_input, dict) else None
+    return (value.strip()[:200] or None) if isinstance(value, str) else None
+
+
+def describe_tool_input(tool_input: Any) -> str | None:
+    """The one thing a human needs to judge a tool call: the command, the path, the URL…"""
+    if not isinstance(tool_input, dict):
+        return None
+    for key in ("command", "cmd", "file_path", "path", "url", "pattern", "query", "prompt", "plan"):
+        value = tool_input.get(key)
+        if isinstance(value, str) and value:
+            return truncate(value)
+    questions = tool_input.get("questions")
+    if isinstance(questions, list):
+        texts = [q.get("question", "") for q in questions if isinstance(q, dict)]
+        return truncate("\n".join(t for t in texts if t)) or None
+    return truncate(json.dumps(tool_input, ensure_ascii=False, indent=1)) if tool_input else None

muxtower-0.1.0/src/muxtower/agents/__init__.py

@@ -0,0 +1,8 @@
+"""Coding agents muxtower knows beyond running them in a terminal, one package each.
+
+An agent plugin tells, for a tmux pane running it, which session of the agent that is (`ClaudeProcessPort`:
+its Remote Control id, transcript file and name) and reads its transcript into conversation items
+(`sessions.transcripts.TranscriptFormat`). `agents.processes.AgentProcesses` asks each plugin in turn.
+Claude Code's live in `sessions/claude_processes.py` and `claude_conversation.py`; Codex's here, in
+`agents/codex/`.
+"""

muxtower-0.1.0/src/muxtower/agents/accounts.py

@@ -0,0 +1,91 @@
+"""The account each agent on this machine runs as, so sessions of different accounts can be told apart
+(two Claude accounts, Claude Code with an API key, Codex). Read from the agents' own login files, for
+who is logged in only: no token is kept, logged or sent anywhere. Re-read when a file changes.
+
+Claude Code (and its Remote Control sessions): `~/.claude.json` names the claude.ai account it signed in
+with; without one, an API key (`ANTHROPIC_API_KEY`) is "API key". Codex: `~/.codex/auth.json` holds a
+ChatGPT sign-in, whose ID token names its email, or an API key."""
+
+import base64
+import json
+import os
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+from muxtower.sessions.models import Session
+from muxtower.sessions.ports import SessionSource
+
+API_KEY = "API key"
+
+
+def _jwt_email(token: Any) -> str | None:
+    """The email claim of an ID token, read for display only (it is the agent's own; not verified)."""
+    if not isinstance(token, str) or token.count(".") != 2:
+        return None
+    payload = token.split(".")[1]
+    try:
+        claims = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
+    except ValueError:
+        return None
+    email = claims.get("email") if isinstance(claims, dict) else None
+    return email if isinstance(email, str) and email else None
+
+
+class _Cached:
+    """A value read from a file, again only when the file changed."""
+
+    def __init__(self, path: Path, read: Callable[[dict[str, Any]], str | None]) -> None:
+        self.path = path
+        self.read = read
+        self._stamp: float | None = None
+        self._value: str | None = None
+
+    def get(self) -> str | None:
+        try:
+            stamp = self.path.stat().st_mtime
+        except OSError:
+            return None
+        if stamp != self._stamp:
+            try:
+                data = json.loads(self.path.read_text())
+                self._value = self.read(data) if isinstance(data, dict) else None
+            except (OSError, ValueError):
+                self._value = None
+            self._stamp = stamp
+        return self._value
+
+
+class Accounts:
+    def __init__(self, home: Path | None = None, env: Mapping[str, str] | None = None) -> None:
+        home = home or Path.home()
+        self.env = os.environ if env is None else env
+        self._claude = _Cached(home / ".claude.json", self._claude_account)
+        self._codex = _Cached(home / ".codex" / "auth.json", self._codex_account)
+
+    @staticmethod
+    def _claude_account(data: dict[str, Any]) -> str | None:
+        account = data.get("oauthAccount")
+        email = account.get("emailAddress") if isinstance(account, dict) else None
+        return email if isinstance(email, str) and email else None
+
+    @staticmethod
+    def _codex_account(data: dict[str, Any]) -> str | None:
+        tokens = data.get("tokens")
+        if data.get("auth_mode") != "apikey" and isinstance(tokens, dict):
+            if email := _jwt_email(tokens.get("id_token")):
+                return email
+        return API_KEY if data.get("OPENAI_API_KEY") else None
+
+    def claude(self) -> str | None:
+        return self._claude.get() or (API_KEY if self.env.get("ANTHROPIC_API_KEY") else None)
+
+    def codex(self) -> str | None:
+        return self._codex.get()
+
+    def __call__(self, session: Session) -> str | None:
+        if session.runtime == "codex" or session.source == SessionSource.CODEX:
+            return self.codex()
+        if session.runtime.startswith("claude") or session.source == SessionSource.REMOTE_CONTROL:
+            return self.claude()
+        return None

muxtower-0.1.0/src/muxtower/agents/codex/processes.py

@@ -0,0 +1,66 @@
+"""Which Codex session a tmux pane runs.
+
+Codex keeps no file per process (Claude Code does), but while a session runs its process holds the
+session's rollout file open for appending: the pane's process, or one it started, has an open file
+`<codex home>/sessions/…/rollout-<time>-<thread id>.jsonl`. The rollout is the transcript; the thread's
+name (what `/rename` set, else its title) is in Codex's state database, read without writing. A
+session's rollout is only created with its first message, so a fresh Codex has none yet. Codex has no
+Remote Control, so no remote id.
+"""
+
+import os
+import re
+import sqlite3
+from pathlib import Path
+
+from muxtower.infra.procfs import Children, family
+from muxtower.sessions.claude_processes import ClaudeProcess
+
+SEARCH_DEPTH = 3
+THREAD_ID = re.compile(r"rollout-.*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$")
+STATE_DB = "state_5.sqlite"
+
+
+class CodexProcesses:
+    def __init__(self, codex_home: Path | None = None, proc: Path = Path("/proc")) -> None:
+        self.home = codex_home or Path(os.environ.get("CODEX_HOME") or Path.home() / ".codex")
+        self.sessions = str(self.home / "sessions") + os.sep
+        self.proc = proc
+
+    def _rollout(self, pane_pid: int) -> str | None:
+        """The rollout file the pane's Codex holds open, if it runs one."""
+        for pid in family(pane_pid, Children(self.proc), SEARCH_DEPTH):
+            try:
+                fds = list((self.proc / str(pid) / "fd").iterdir())
+            except OSError:
+                continue
+            for fd in fds:
+                try:
+                    target = os.readlink(fd)
+                except OSError:
+                    continue
+                if target.startswith(self.sessions) and THREAD_ID.search(target):
+                    return target
+        return None
+
+    def remote_id(self, pane_pid: int) -> str | None:
+        return None
+
+    def transcript(self, pane_pid: int) -> str | None:
+        return self._rollout(pane_pid)
+
+    def name(self, pane_pid: int) -> str | None:
+        rollout = self._rollout(pane_pid)
+        found = THREAD_ID.search(rollout) if rollout else None
+        if not found:
+            return None
+        try:
+            with sqlite3.connect(f"file:{self.home / STATE_DB}?mode=ro", uri=True, timeout=1) as db:
+                row = db.execute("SELECT name, title FROM threads WHERE id = ?", (found.group(1),)).fetchone()
+        except sqlite3.Error:
+            return None
+        name = next((str(v).strip() for v in row or () if v and str(v).strip()), None)
+        return name[:80] if name else None
+
+    def running(self) -> dict[str, ClaudeProcess]:
+        return {}

muxtower-0.1.0/src/muxtower/agents/codex/rollout.py

@@ -0,0 +1,155 @@
+"""A Codex session's conversation, read from its rollout file.
+
+Codex writes each session to `~/.codex/sessions/YYYY/MM/DD/rollout-<time>-<thread id>.jsonl`: one
+`{timestamp, type, payload}` per line. What the owner and the agent said are `event_msg`s
+(`user_message`, `agent_message`); tool calls are `response_item`s (`function_call`, `custom_tool_call`,
+`local_shell_call`, `web_search_call`) whose output arrives later under the same `call_id`; a turn ends
+with `task_complete` (or `turn_complete`, `turn_aborted`). Approval prompts are never written down, so
+the file cannot tell a waiting turn from a working one: the screen does.
+
+In "code mode" a tool call is a script (`custom_tool_call` named `exec`) that calls the real tools, as
+`tools.exec_command({"cmd": …})`: the first one it calls names the call.
+"""
+
+import json
+import re
+from datetime import datetime
+from typing import Any
+
+from muxtower.agent_text import describe_tool_input, truncate
+from muxtower.sessions.models import ConversationItem, ConversationItemKind, ItemStatus
+
+MAX_ITEMS = 2000
+TOOL_CALLS = {"function_call", "custom_tool_call", "local_shell_call", "web_search_call"}
+TOOL_OUTPUTS = {"function_call_output", "custom_tool_call_output", "local_shell_call_output"}
+TURN_ENDS = {"task_complete", "turn_complete"}
+ABORTED = {"turn_aborted", "task_aborted"}
+SCRIPT_CALL = re.compile(r"tools\.(\w+)\(\s*(\{.*?\})\s*\)", re.S)
+FAILED = re.compile(r"^(Script failed|Process exited with code [1-9])|Exit code: [1-9]", re.M)
+
+
+def _at(value: Any) -> datetime | None:
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00")) if value else None
+    except ValueError:
+        return None
+
+
+def _json(text: Any) -> Any:
+    try:
+        return json.loads(text) if isinstance(text, str) else text
+    except ValueError:
+        return None
+
+
+def _output_text(output: Any) -> str:
+    if isinstance(output, list):
+        return "\n".join(str(o.get("text") or "") for o in output if isinstance(o, dict))
+    return str(output or "")
+
+
+def tool_of(payload: dict[str, Any]) -> tuple[str, str | None]:
+    """The tool a call runs and the one line that says what it does."""
+    kind = payload.get("type")
+    if kind == "local_shell_call":
+        command = (payload.get("action") or {}).get("command")
+        return "exec_command", " ".join(command) if isinstance(command, list) else None
+    if kind == "web_search_call":
+        query = (payload.get("action") or {}).get("query")
+        return "web_search", str(query) if query else None
+    name = str(payload.get("name") or "tool")
+    if kind == "custom_tool_call" and name == "exec":  # code mode: a script calling tools
+        script = str(payload.get("input") or "")
+        found = SCRIPT_CALL.search(script)
+        if found:
+            args = _json(found.group(2))
+            return found.group(1), describe_tool_input(args) if isinstance(args, dict) else truncate(found.group(2))
+        return "exec", truncate(script) or None
+    args = _json(payload.get("arguments")) if kind == "function_call" else payload.get("input")
+    if isinstance(args, dict):
+        return name, describe_tool_input(args)
+    return name, truncate(str(args)) if args else None
+
+
+class RolloutBuilder:
+    """Rollout lines → conversation items, in the order written; a tool call's item is sent again once
+    its output tells how it ended."""
+
+    def __init__(self) -> None:
+        self.items: dict[int, ConversationItem] = {}
+        self._calls: dict[str, int] = {}  # call_id → its item's seq
+        self._seq = 0
+
+    @property
+    def last_reply(self) -> str | None:
+        for seq in sorted(self.items, reverse=True):
+            if self.items[seq].kind == ConversationItemKind.REPLY:
+                return self.items[seq].text
+        return None
+
+    def after(self, seq: int, limit: int) -> list[ConversationItem]:
+        newer = [self.items[s] for s in sorted(self.items) if s > seq]
+        return newer[-limit:] if seq == 0 else newer[:limit]
+
+    def feed_lines(self, lines: list[bytes]) -> list[ConversationItem]:
+        touched: dict[int, ConversationItem] = {}
+        for line in lines:
+            self._seq += 1
+            try:
+                record = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(record, dict) and isinstance(record.get("payload"), dict):
+                for item in self._apply(str(record.get("type")), record["payload"], _at(record.get("timestamp"))):
+                    self.items[item.seq] = item
+                    touched[item.seq] = item
+        for seq in sorted(self.items)[:-MAX_ITEMS]:
+            del self.items[seq]
+        return [touched[s] for s in sorted(touched)]
+
+    def _item(self, kind: ConversationItemKind, at: datetime | None, **fields: Any) -> ConversationItem:
+        return ConversationItem(seq=self._seq, at=at, kind=kind, **fields)
+
+    def _finish(self, call_id: Any, status: ItemStatus) -> list[ConversationItem]:
+        seq = self._calls.get(str(call_id))
+        item = self.items.get(seq) if seq is not None else None
+        if item is None or item.status == ItemStatus.ERROR:
+            return []
+        return [item.model_copy(update={"status": status})]
+
+    def _apply(self, kind: str, payload: dict[str, Any], at: datetime | None) -> list[ConversationItem]:
+        sub = payload.get("type")
+        if kind == "event_msg":
+            if sub == "user_message" and (text := str(payload.get("message") or "").strip()):
+                return [self._item(ConversationItemKind.PROMPT, at, text=text)]
+            if sub == "agent_message" and (text := str(payload.get("message") or "").strip()):
+                return [self._item(ConversationItemKind.REPLY, at, text=text)]
+            if sub == "exec_command_end" and payload.get("exit_code") not in (0, None):
+                return self._finish(payload.get("call_id"), ItemStatus.ERROR)
+            if sub in TURN_ENDS:
+                return [self._item(ConversationItemKind.RESULT, at, status=ItemStatus.DONE)]
+            if sub in ABORTED:
+                reason = str(payload.get("reason") or "interrupted")
+                return [self._item(ConversationItemKind.RESULT, at, text=reason, status=ItemStatus.ERROR)]
+            if sub == "error" and (text := str(payload.get("message") or "").strip()):
+                return [self._item(ConversationItemKind.RESULT, at, text=text, status=ItemStatus.ERROR)]
+            return []
+        if kind != "response_item":
+            return []
+        if sub in TOOL_CALLS:
+            name, what = tool_of(payload)
+            done = sub == "web_search_call" or payload.get("status") == "failed"
+            status = (
+                ItemStatus.ERROR
+                if payload.get("status") == "failed"
+                else ItemStatus.DONE
+                if done
+                else ItemStatus.RUNNING
+            )
+            if call_id := payload.get("call_id"):
+                self._calls[str(call_id)] = self._seq
+            return [self._item(ConversationItemKind.TOOL, at, tool_name=name, text=what, status=status)]
+        if sub in TOOL_OUTPUTS:
+            failed = FAILED.search(_output_text(payload.get("output")))
+            return self._finish(payload.get("call_id"), ItemStatus.ERROR if failed else ItemStatus.DONE)
+        return []

muxtower-0.1.0/src/muxtower/agents/processes.py

@@ -0,0 +1,22 @@
+"""Every agent plugin's answer for a pane, asked in turn: the first that recognizes the pane's agent
+answers (a pane runs one agent; each plugin finds only its own)."""
+
+from muxtower.sessions.claude_processes import ClaudeProcess
+from muxtower.sessions.ports import ClaudeProcessPort
+
+
+class AgentProcesses:
+    def __init__(self, plugins: list[ClaudeProcessPort]) -> None:
+        self.plugins = plugins
+
+    def remote_id(self, pane_pid: int) -> str | None:
+        return next((found for p in self.plugins if (found := p.remote_id(pane_pid))), None)
+
+    def transcript(self, pane_pid: int) -> str | None:
+        return next((found for p in self.plugins if (found := p.transcript(pane_pid))), None)
+
+    def name(self, pane_pid: int) -> str | None:
+        return next((found for p in self.plugins if (found := p.name(pane_pid))), None)
+
+    def running(self) -> dict[str, ClaudeProcess]:
+        return {k: v for p in self.plugins for k, v in p.running().items()}