pitwall-agents 0.1.0__tar.gz

pitwall_agents-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: release
+
+# Publishes to PyPI when a version tag (v*) is pushed, or when run by hand.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Test
+        run: uv run --extra dev pytest -q
+
+      - name: Tag matches the package version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v${version}" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != v${version}"; exit 1; }
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}

pitwall_agents-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.superpowers/
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+spike/

pitwall_agents-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Sinha
+
+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.

pitwall_agents-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: pitwall-agents
+Version: 0.1.0
+Summary: A pit wall for your coding agents: see every session's state on a desk device and jump to the right terminal tab.
+Project-URL: Homepage, https://github.com/siddhant573/pitwall
+Author: Siddhant Sinha
+License-Expression: MIT
+License-File: LICENSE
+Keywords: badge,bluetooth,claude-code,coding-agents,github-universe,iterm2
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: bleak>=0.22
+Requires-Dist: mpremote>=1.24
+Requires-Dist: pyserial>=3.5
+Requires-Dist: tomli>=2; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pitwall 🏁
+
+**A pit wall for your coding agents.** See every agent session's state on a device on your desk, and jump to the right terminal tab with one button.
+
+If you run 15–20 Claude Code sessions in iTerm tabs, you know the loop: cycle through tabs, find the one waiting on a permission prompt, approve it, repeat. pitwall shows you which session needs you, so you can stop hunting for it.
+
+The first device is the **GitHub Universe 2026 badge** (Pimoroni Badger 2350). The protocol is open, so a Stream Deck, a macro keypad or anything else can join (see [Write your own device](#write-your-own-device)).
+
+<!-- docs/media/demo.gif goes here -->
+
+## The flags
+
+| | State | Means |
+|---|---|---|
+| 🟢 | **Green flag** | the agent is working |
+| 🟡 | **Box box** | the agent needs you: a permission prompt or a question |
+| 🏁 | **Chequered flag** | the agent finished its turn |
+| 🔴 | **Red flag** | the agent's turn failed |
+
+The sessions waiting longest for you are always at the top.
+
+## Install (macOS)
+
+```bash
+pipx install pitwall-agents
+pitwall setup
+```
+
+`pitwall setup` finds your badge, your agents and your terminal, shows what it will do, and after one "yes":
+
+1. writes `~/.pitwall/config.toml`
+2. adds pitwall's hooks to Claude Code (`~/.claude/settings.json`, with a backup)
+3. installs the Pitwall app on the badge (plug it in over USB with a data cable)
+4. keeps the helper running in the background with a LaunchAgent (starts at login)
+
+Then open **Pitwall** from the badge's home menu. Your Claude Code sessions show up on their next prompt or tool call.
+
+**Bluetooth is automatic.** While the badge is plugged in, the helper gives it a random key over the cable. Unplug it and it keeps working over Bluetooth; plug it back in and it switches to USB.
+
+**macOS asks once** to let pitwall control iTerm2 (to switch tabs) and use Bluetooth. Allow both.
+
+No badge? `pitwall sim` shows the same board in a terminal tab, and `pitwall status` prints it once.
+
+## Configure
+
+`~/.pitwall/config.toml`:
+
+```toml
+terminal = "iterm2"
+agents = ["claude-code"]
+
+[devices.badger2350]          # GitHub Universe 2026 badge (Pimoroni Badger 2350)
+transports = ["usb", "ble"]
+```
+
+For one run, `pitwall serve --device badger2350:usb` overrides the devices (repeat `--device` for several).
+
+| Command | Does |
+|---|---|
+| `pitwall setup` | detect and install everything |
+| `pitwall service install \| uninstall \| status \| restart` | the background LaunchAgent |
+| `pitwall status` | print the board |
+| `pitwall install claude-code` / `pitwall uninstall claude-code` | add or remove the hooks |
+| `pitwall install badge` | (re)install the badge app |
+| `pitwall serve [-v] [--device …]` | run the helper in the foreground |
+| `pitwall sim` | a simulated device in the terminal |
+
+Logs: `~/.pitwall/serve.log`.
+
+## Badge buttons
+
+| Button | Does |
+|---|---|
+| UP / DOWN | move the cursor |
+| SELECT | jump to the selected session's tab |
+| RIGHT | jump to the session that's waited longest for you (🟡) |
+| LEFT | back to the top |
+
+The badge's lights pulse when a session goes 🟡. If it loses the helper, it says so and dims the last board.
+
+## What pitwall does *not* do
+
+- **It never acts on your agents.** Devices only show status and switch tabs. There's no approving or prompting from a button.
+- **It never reads your prompts or code.** The hook sends only the session id, the folder name and the terminal tab. Over Bluetooth, even that is encrypted after pairing.
+- **No cloud, no accounts, no network calls.** Everything stays on your Mac and your desk.
+- **It never slows Claude down.** The hook exits immediately (about 50 ms) even if the helper isn't running.
+
+## Write your own device
+
+Devices speak a tiny JSON-lines protocol. Connect to `~/.pitwall/devices.sock`, say `hello`, and you'll get a `board` every time something changes. Send `focus` to switch tabs. Everything is in **[docs/protocol.md](docs/protocol.md)**, and no pitwall code needs reading. Other agents can report sessions the same way, through `~/.pitwall/pitwall.sock`.
+
+## Roadmap
+
+- More devices: Stream Deck (one key per session), Logitech MX Creative Keypad
+- More agents: Codex, Copilot CLI, Gemini CLI
+- More terminals: Ghostty, WezTerm, tmux
+
+## Skills for your agent
+
+The repo ships two [Claude Code skills](skills/): `pitwall` (set up, check, troubleshoot) and `pitwall-device` (build a new device on the protocol). Copy them into `~/.claude/skills/` to use them.
+
+## Uninstall
+
+```bash
+pitwall service uninstall
+pitwall uninstall claude-code
+pipx uninstall pitwall-agents
+```
+
+On the badge, delete `apps/pitwall` while it's in disk mode.
+
+## License
+
+MIT © Siddhant Sinha

pitwall_agents-0.1.0/README.md

@@ -0,0 +1,114 @@
+# pitwall 🏁
+
+**A pit wall for your coding agents.** See every agent session's state on a device on your desk, and jump to the right terminal tab with one button.
+
+If you run 15–20 Claude Code sessions in iTerm tabs, you know the loop: cycle through tabs, find the one waiting on a permission prompt, approve it, repeat. pitwall shows you which session needs you, so you can stop hunting for it.
+
+The first device is the **GitHub Universe 2026 badge** (Pimoroni Badger 2350). The protocol is open, so a Stream Deck, a macro keypad or anything else can join (see [Write your own device](#write-your-own-device)).
+
+<!-- docs/media/demo.gif goes here -->
+
+## The flags
+
+| | State | Means |
+|---|---|---|
+| 🟢 | **Green flag** | the agent is working |
+| 🟡 | **Box box** | the agent needs you: a permission prompt or a question |
+| 🏁 | **Chequered flag** | the agent finished its turn |
+| 🔴 | **Red flag** | the agent's turn failed |
+
+The sessions waiting longest for you are always at the top.
+
+## Install (macOS)
+
+```bash
+pipx install pitwall-agents
+pitwall setup
+```
+
+`pitwall setup` finds your badge, your agents and your terminal, shows what it will do, and after one "yes":
+
+1. writes `~/.pitwall/config.toml`
+2. adds pitwall's hooks to Claude Code (`~/.claude/settings.json`, with a backup)
+3. installs the Pitwall app on the badge (plug it in over USB with a data cable)
+4. keeps the helper running in the background with a LaunchAgent (starts at login)
+
+Then open **Pitwall** from the badge's home menu. Your Claude Code sessions show up on their next prompt or tool call.
+
+**Bluetooth is automatic.** While the badge is plugged in, the helper gives it a random key over the cable. Unplug it and it keeps working over Bluetooth; plug it back in and it switches to USB.
+
+**macOS asks once** to let pitwall control iTerm2 (to switch tabs) and use Bluetooth. Allow both.
+
+No badge? `pitwall sim` shows the same board in a terminal tab, and `pitwall status` prints it once.
+
+## Configure
+
+`~/.pitwall/config.toml`:
+
+```toml
+terminal = "iterm2"
+agents = ["claude-code"]
+
+[devices.badger2350]          # GitHub Universe 2026 badge (Pimoroni Badger 2350)
+transports = ["usb", "ble"]
+```
+
+For one run, `pitwall serve --device badger2350:usb` overrides the devices (repeat `--device` for several).
+
+| Command | Does |
+|---|---|
+| `pitwall setup` | detect and install everything |
+| `pitwall service install \| uninstall \| status \| restart` | the background LaunchAgent |
+| `pitwall status` | print the board |
+| `pitwall install claude-code` / `pitwall uninstall claude-code` | add or remove the hooks |
+| `pitwall install badge` | (re)install the badge app |
+| `pitwall serve [-v] [--device …]` | run the helper in the foreground |
+| `pitwall sim` | a simulated device in the terminal |
+
+Logs: `~/.pitwall/serve.log`.
+
+## Badge buttons
+
+| Button | Does |
+|---|---|
+| UP / DOWN | move the cursor |
+| SELECT | jump to the selected session's tab |
+| RIGHT | jump to the session that's waited longest for you (🟡) |
+| LEFT | back to the top |
+
+The badge's lights pulse when a session goes 🟡. If it loses the helper, it says so and dims the last board.
+
+## What pitwall does *not* do
+
+- **It never acts on your agents.** Devices only show status and switch tabs. There's no approving or prompting from a button.
+- **It never reads your prompts or code.** The hook sends only the session id, the folder name and the terminal tab. Over Bluetooth, even that is encrypted after pairing.
+- **No cloud, no accounts, no network calls.** Everything stays on your Mac and your desk.
+- **It never slows Claude down.** The hook exits immediately (about 50 ms) even if the helper isn't running.
+
+## Write your own device
+
+Devices speak a tiny JSON-lines protocol. Connect to `~/.pitwall/devices.sock`, say `hello`, and you'll get a `board` every time something changes. Send `focus` to switch tabs. Everything is in **[docs/protocol.md](docs/protocol.md)**, and no pitwall code needs reading. Other agents can report sessions the same way, through `~/.pitwall/pitwall.sock`.
+
+## Roadmap
+
+- More devices: Stream Deck (one key per session), Logitech MX Creative Keypad
+- More agents: Codex, Copilot CLI, Gemini CLI
+- More terminals: Ghostty, WezTerm, tmux
+
+## Skills for your agent
+
+The repo ships two [Claude Code skills](skills/): `pitwall` (set up, check, troubleshoot) and `pitwall-device` (build a new device on the protocol). Copy them into `~/.claude/skills/` to use them.
+
+## Uninstall
+
+```bash
+pitwall service uninstall
+pitwall uninstall claude-code
+pipx uninstall pitwall-agents
+```
+
+On the badge, delete `apps/pitwall` while it's in disk mode.
+
+## License
+
+MIT © Siddhant Sinha

pitwall_agents-0.1.0/badge/pitwall/__init__.py

@@ -0,0 +1,239 @@
+# pitwall: a pit wall for your coding agents, on the GitHub Universe badge.
+# Shows every agent session's state and focuses its terminal tab on a button press.
+import math
+
+import links
+import model
+
+badge.mode(HIRES | VSYNC)
+
+try:
+    import missing_details
+    FONT = missing_details.mona_sans()
+except Exception:
+    FONT = None
+
+UID = badge.uid if isinstance(badge.uid, str) else "".join("%02x" % b for b in badge.uid)
+CAPS = {"display": [320, 240], "color": True,
+        "buttons": ["up", "down", "left", "right", "select"], "keys": 0, "led": True}
+
+bg = color.rgb(12, 14, 20)
+panel = color.rgb(30, 34, 46)
+white = color.rgb(238, 240, 246)
+dim = color.rgb(238, 240, 246, 110)
+faint = color.rgb(238, 240, 246, 50)
+sub = color.rgb(238, 240, 246, 165)
+amber = color.rgb(255, 196, 40)
+red = color.rgb(240, 70, 70)
+green = color.rgb(80, 210, 110)
+black = color.rgb(20, 20, 20)
+
+STATE_PEN = {"box": amber, "red": red, "green": green}
+STATE_WORD = {"red": "failed", "done": "done", "green": "working"}
+
+ROW_TOP, ROW_H, ROWS = 27, 31, 6
+FOOT_Y = 215
+
+view = model.View()
+usb = links.Usb()
+try:
+    ble = links.Ble(UID, {"type": "hello", "device": "badger2350", "uid": UID, "transport": "ble", "caps": CAPS})
+except Exception as e:
+    print("pitwall: bluetooth unavailable", e)
+    ble = None
+
+last_rx = {"usb": None, "ble": None}
+last_hello_ms = -10000
+
+
+def hello(transport):
+    return {"type": "hello", "device": "badger2350", "uid": UID, "transport": transport, "caps": CAPS}
+
+
+def active_transport(now):
+    if last_rx["usb"] is not None and now - last_rx["usb"] <= model.STALE_MS:
+        return "usb"
+    if ble is not None and ble.authed:
+        return "ble"
+    return None
+
+
+def send(msg, now):
+    t = active_transport(now)
+    if t == "usb":
+        usb.send(msg)
+    elif t == "ble":
+        ble.send(msg)
+
+
+def handle(msg, transport, now):
+    kind = msg.get("type")
+    if kind == "hello":
+        if transport == "usb":
+            usb.send(hello("usb"))
+        return
+    if kind == "pair_key" and transport == "usb":
+        # USB is a local cable: the helper hands over its Bluetooth key here
+        try:
+            host, key = msg["host"], bytes.fromhex(msg["key"])
+        except Exception:
+            return
+        if len(key) == 32:
+            if ble is not None:
+                ble.add_key(host, key)
+            else:
+                keys = links.load_keys()
+                keys[host] = key
+                links.save_keys(keys)
+            usb.send({"type": "paired", "host": host})
+        return
+    if kind in ("board", "alert"):
+        last_rx[transport] = now
+        # while USB is live, ignore a stale BLE board (the helper only talks on one anyway)
+        if transport == "ble" and active_transport(now) == "usb":
+            return
+        view.on_message(msg, now)
+
+
+def text(s, x, y, size, pen):
+    screen.pen = pen
+    screen.text(s, x, y, size)
+
+
+def text_w(s, size):
+    return screen.measure_text(s, size)[0]
+
+
+def chip(state, x, y, s, flash):
+    if state == "done":
+        half = s / 2
+        for i in range(2):
+            for j in range(2):
+                screen.pen = white if (i + j) % 2 == 0 else black
+                screen.shape(shape.rectangle(x + i * half, y + j * half, half, half))
+        return
+    pen = STATE_PEN.get(state, dim)
+    if state == "box" and flash:
+        pen = white
+    screen.pen = pen
+    screen.shape(shape.rounded_rectangle(x, y, s, s, 3))
+
+
+def draw_header(now):
+    screen.pen = panel
+    screen.shape(shape.rectangle(0, 0, 320, 24))
+    x = 8
+    for state in ("box", "red", "done", "green"):
+        chip(state, x, 6, 12, False)
+        n = str(view.counts.get(state, 0))
+        text(n, x + 16, 4, 14, white)
+        x += 26 + text_w(n, 14)
+    t = active_transport(now)
+    link = "USB" if t == "usb" else ("BT" if t == "ble" else "--")
+    try:
+        level = int(badge.battery_level())
+    except Exception:
+        level = None
+    right = link + ("  %d%%" % level if level is not None else "")
+    if len(view.sessions) > ROWS:
+        right = "%d/%d   " % (view.cursor + 1, len(view.sessions)) + right
+    text(right, 312 - text_w(right, 12), 6, 12, dim if t else red)
+
+
+def fit(s, size, max_w):
+    """Cut text to fit max_w pixels, with an ellipsis."""
+    s = str(s)
+    if text_w(s, size) <= max_w:
+        return s
+    while s and text_w(s + "…", size) > max_w:
+        s = s[:-1]
+    return s + "…"
+
+
+def draw_rows(now, stale):
+    rows = view.rows(ROWS)
+    if not rows:
+        msg = "No agent sessions yet" if not stale else "Waiting for pit wall…"
+        text(msg, 160 - text_w(msg, 16) / 2, 105, 16, dim)
+        return
+    flash = view.alerting(now) and (now // 250) % 2 == 0
+    for idx, (i, s, selected) in enumerate(rows):
+        y = ROW_TOP + idx * ROW_H
+        if selected:
+            screen.pen = panel
+            screen.shape(shape.rounded_rectangle(4, y, 312, ROW_H - 2, 6))
+        state = s.get("state", "")
+        chip(state, 12, y + 8, 13, flash and s.get("id") == view.alert_id)
+        if state == "box":
+            right, rpen = model.fmt_age(s.get("age_s", 0)), amber
+        else:
+            right, rpen = STATE_WORD.get(state, ""), dim
+        rw = text_w(right, 12)
+        text(right, 308 - rw, y + 9, 12, rpen if not stale else faint)
+        max_w = 308 - rw - 10 - 34
+        live = s.get("focusable", True) and not stale
+        title, folder = s.get("title"), str(s.get("label", ""))
+        if title and title.strip().lower() != folder.strip().lower():
+            text(fit(title, 14, max_w), 34, y + 2, 14, white if live else dim)
+            text(fit(folder, 11, max_w), 34, y + 17, 11, sub if live else faint)
+        else:
+            text(fit(title or folder, 14, max_w), 34, y + 8, 14, white if live else dim)
+
+
+def draw_footer(stale):
+    screen.pen = red if stale else panel
+    screen.shape(shape.rectangle(0, FOOT_Y + 2, 320, 240 - FOOT_Y - 2))
+    if stale:
+        msg = "No connection to pit wall"
+        text(msg, 160 - text_w(msg, 12) / 2, FOOT_Y + 5, 12, white)
+        return
+    x = 8
+    for key, what in (("SELECT", "focus"), ("RIGHT", "next box box"), ("LEFT", "top")):
+        text(key, x, FOOT_Y + 5, 12, amber)
+        x += text_w(key, 12) + 4
+        text(what, x, FOOT_Y + 5, 12, white)
+        x += text_w(what, 12) + 12
+
+
+def update():
+    global last_hello_ms
+    now = badge.ticks
+    for m in usb.read():
+        handle(m, "usb", now)
+    if ble is not None:
+        for m in ble.read():
+            handle(m, "ble", now)
+
+    if badge.pressed(BUTTON_UP):
+        view.move(-1)
+    elif badge.pressed(BUTTON_DOWN):
+        view.move(1)
+    elif badge.pressed(BUTTON_LEFT):
+        view.move(-len(view.sessions))
+    elif badge.pressed(BUTTON_SELECT):
+        sid = view.selected_id()
+        if sid:
+            send({"type": "focus", "id": sid}, now)
+    elif badge.pressed(BUTTON_RIGHT):
+        send({"type": "focus_next_waiting"}, now)
+
+    stale = view.stale(now)
+    if stale and now - last_hello_ms > 5000:
+        usb.send(hello("usb"))  # the helper may have missed our first hello
+        last_hello_ms = now
+
+    try:
+        badge.caselights((0.5 + 0.5 * math.sin(now / 120)) if view.alerting(now) else 0)
+    except Exception:
+        pass
+
+    if FONT is not None:
+        screen.font = FONT
+    screen.pen = bg
+    screen.clear()
+    draw_header(now)
+    draw_rows(now, stale)
+    draw_footer(stale)
+
+
+run(update)