legbar 0.1.0__tar.gz

legbar-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,134 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    # legbar claims 3.9+ on macOS, Linux, and Windows. curses is stdlib on the
+    # first two; Windows gets it from the windows-curses wheel (declared in
+    # pyproject.toml, platform-gated), which is why this job installs it
+    # explicitly rather than relying on the package install step alone.
+    #
+    # 3.14 is in the matrix because it is what the primary dev box runs -- the
+    # sibling repos went months testing only 3.9 and 3.13 while every local run
+    # used 3.14. macos-13 is here because macos-latest is arm64, so without it
+    # Intel Macs have no coverage.
+    #
+    # Windows is excluded from 3.14 on purpose: windows-curses wheels top out at
+    # 3.13, so that leg would fail on dependency resolution rather than on
+    # anything in this repo. Drop the exclusion once upstream ships a wheel.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, macos-13, windows-latest]
+        python: ["3.9", "3.13", "3.14"]
+        exclude:
+          - os: windows-latest
+            python: "3.14"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install windows-curses
+        if: runner.os == 'Windows'
+        run: pip install windows-curses
+
+      - name: Run tests
+        run: python -m unittest discover -s tests -t . -v
+
+      # Everything here must work on a box with no Claude Code, no sessions, no
+      # Cursor install and no gh auth -- degradation is the contract under test.
+      # A fleet dashboard that crashes on an empty fleet is worse than useless,
+      # because the empty case is exactly when someone is debugging why nothing
+      # is running.
+      - name: Smoke test with nothing running
+        shell: bash
+        env:
+          LEGBAR_SESSIONS_DIR: ${{ runner.temp }}/no-sessions
+          LEGBAR_PROJECTS_DIR: ${{ runner.temp }}/no-projects
+          LEGBAR_CURSOR_HOME: ${{ runner.temp }}/no-cursor
+        run: |
+          python legbar.py --version
+          python legbar.py --help > /dev/null
+          python legbar.py --once --no-git --no-ci
+          # Workspace-relative, not /tmp: on the Windows runner bash writes
+          # /tmp into Git Bash's temp while Python reads it as C:\tmp, so the
+          # two disagree and the read fails on that leg alone.
+          python legbar.py --json --no-git --no-ci > state.json
+          python -c "import json; d=json.load(open('state.json')); assert d['sessions']==[], d['sessions']; print('empty-fleet JSON ok')"
+
+      # henhouse is a working CLI in its own right, and legbar is only a
+      # renderer over it -- so it gets its own smoke test rather than being
+      # covered incidentally.
+      - name: Smoke test henhouse
+        shell: bash
+        env:
+          LEGBAR_SESSIONS_DIR: ${{ runner.temp }}/no-sessions
+          LEGBAR_PROJECTS_DIR: ${{ runner.temp }}/no-projects
+        run: python henhouse.py --no-git
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      # Stdlib-only is a promise this repo makes in its README and pyproject,
+      # and the sibling repos enforce it the same way: the only third-party
+      # import allowed anywhere is windows-curses, and only behind a platform
+      # guard. A dependency that sneaks in is a dependency someone's locked-down
+      # box will not have.
+      - name: Assert stdlib-only
+        run: |
+          python - <<'PY'
+          import ast, sys, pathlib
+          ALLOWED = {"henhouse", "legbar", "curses", "_curses"}
+          bad = []
+          for f in ("legbar.py", "henhouse.py"):
+              tree = ast.parse(pathlib.Path(f).read_text(encoding="utf-8"))
+              for node in ast.walk(tree):
+                  if isinstance(node, ast.Import):
+                      names = [a.name.split(".")[0] for a in node.names]
+                  elif isinstance(node, ast.ImportFrom):
+                      names = [(node.module or "").split(".")[0]]
+                  else:
+                      continue
+                  for n in names:
+                      if n and n not in ALLOWED and n not in sys.stdlib_module_names:
+                          bad.append(f"{f}: {n}")
+          if bad:
+              print("non-stdlib imports found:", *bad, sep="\n  ")
+              raise SystemExit(1)
+          print("stdlib-only: ok")
+          PY
+
+      - name: Assert the output stays ASCII
+        # Block-drawing characters mojibake in the Windows console. This is a
+        # promise the README makes and the tests assert per-line; this catches
+        # a stray glyph landing in a source literal that no test happens to
+        # render.
+        run: |
+          python - <<'PY'
+          import pathlib
+          for f in ("legbar.py", "henhouse.py"):
+              for i, line in enumerate(pathlib.Path(f).read_text(encoding="utf-8").splitlines(), 1):
+                  if not line.isascii():
+                      raise SystemExit(f"{f}:{i} non-ASCII: {line.strip()[:60]}")
+          print("ascii-only: ok")
+          PY

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

@@ -0,0 +1,142 @@
+name: release
+
+# Builds the wheel and sdist for a tag, verifies the built package actually
+# runs, attaches both to the GitHub Release, and publishes to PyPI via OIDC
+# trusted publishing -- no API token exists anywhere, not in secrets and not
+# on a laptop.
+#
+# PyPI is deliberately the only channel here. The sibling repos publish to
+# brew, npm and a signed apt repo as well, and each of those carries its own
+# one-time credential setup (a tap PAT, an npm trusted publisher, a GPG
+# signing key). Adding them before the first PyPI release has ever run would
+# mean debugging four publish paths at once against a package that has never
+# been published. They come one at a time, after this one is green.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Build and verify only -- publishes nothing, attaches nothing.
+        type: boolean
+        default: true
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade build packaging
+          python -m build
+
+      # The version lives in legbar.py alone. A tag that disagrees with it
+      # would publish artifacts whose filenames contradict the release they
+      # hang off.
+      - name: Check the tag matches __version__
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          code_version=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' legbar.py)
+          tag_version="${GITHUB_REF_NAME#v}"
+          if [ "$code_version" != "$tag_version" ]; then
+            echo "::error::tag $tag_version != __version__ $code_version" >&2
+            exit 1
+          fi
+
+      # PEP 440 normalises the version before it reaches the wheel filename --
+      # "0.1.0-alpha" becomes "0.1.0a0", so a raw string comparison against
+      # __version__ would fail on a perfectly valid prerelease. Compare the
+      # normalisation instead, and print both so the drift between the tag and
+      # what PyPI will display is visible in the log rather than discovered on
+      # the project page.
+      - name: Check the wheel filename matches the normalised version
+        run: |
+          python - <<'PY'
+          import pathlib, re, sys
+          from packaging.version import Version
+          code = re.search(r'^__version__ = "(.*)"', pathlib.Path("legbar.py").read_text(), re.M).group(1)
+          wheel = next(pathlib.Path("dist").glob("*.whl")).name.split("-")[1]
+          print(f"__version__ / tag : {code}")
+          print(f"wheel and sdist   : {wheel}   (what PyPI will display)")
+          if str(Version(code)) != wheel:
+              print(f"::error::{code} normalises to {Version(code)}, but the wheel says {wheel}")
+              sys.exit(1)
+          if code != wheel:
+              print(f"::warning::PyPI will show {wheel}, not {code} -- valid, but the tag and the project page will read differently")
+          PY
+
+      # Everything below runs against the built artifact, not the source tree.
+      # A wheel that imports in the repo root and nowhere else is the classic
+      # packaging failure, and it is invisible until someone installs it.
+      - name: Verify the built package actually runs
+        run: |
+          python -m venv /tmp/v
+          /tmp/v/bin/pip install --quiet dist/*.whl
+          /tmp/v/bin/legbar --version
+          /tmp/v/bin/python -c "import legbar, henhouse"
+
+      # The empty-fleet case is the contract legbar's CI already guards, and
+      # it has to survive packaging too: henhouse must be importable *and*
+      # runnable from the installed wheel, not just from a checkout.
+      - name: Verify the installed package degrades on an empty fleet
+        env:
+          LEGBAR_SESSIONS_DIR: ${{ runner.temp }}/no-sessions
+          LEGBAR_PROJECTS_DIR: ${{ runner.temp }}/no-projects
+          LEGBAR_CURSOR_HOME: ${{ runner.temp }}/no-cursor
+        run: |
+          cd /tmp
+          /tmp/v/bin/legbar --json --no-git --no-ci > state.json
+          /tmp/v/bin/python -c "import json; d=json.load(open('state.json')); assert d['sessions']==[], d['sessions']; print('empty-fleet JSON ok')"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+
+      # Pushing a tag does not create a GitHub Release, so uploading straight
+      # to one fails on a plain `git push --tags`. Create it if it is not there
+      # and upload either way, so the tag is the only step a release needs.
+      - name: Attach to the release
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Canonical PEP 440 prerelease spellings only -- aN / bN / rcN. The
+          # repo does not use -alpha or .beta forms precisely because they are
+          # not what ends up on the wheel.
+          prerelease=""
+          case "$GITHUB_REF_NAME" in *a[0-9]*|*b[0-9]*|*rc[0-9]*) prerelease="--prerelease" ;; esac
+          gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1 \
+            || gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --generate-notes $prerelease
+          gh release upload "$GITHUB_REF_NAME" dist/* --clobber
+
+  # Publishes the tagged build to PyPI via trusted publishing (OIDC): PyPI
+  # trusts this repo's release.yml through the "pypi" environment, so there is
+  # no token to store, leak or rotate.
+  #
+  # One-time setup this job depends on and cannot do for itself: register a
+  # pending Trusted Publisher on PyPI for the project "legbar", pointing at
+  # owner gmhoward9289-ops, repository legbar, workflow release.yml,
+  # environment "pypi". Until that exists this job fails alone -- the release
+  # itself, and the artifacts attached to it, still land.
+  pypi:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

legbar-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+state.json

legbar-0.1.0/.repo-visibility

@@ -0,0 +1 @@
+public

legbar-0.1.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+Notable changes to legbar; entries newest first.
+
+## Versioning
+
+Plain SemVer. `0.1.0` is the first release: the program works, both lanes render
+against real data, and calling that an alpha would understate it. A leading `0.`
+already says the API may move.
+
+- **Source of truth:** `legbar.__version__`; the man page and any package
+  metadata must agree with it.
+- **Tags:** `v` + the version string.
+- **If a prerelease is ever needed,** it is written in canonical PEP 440 form:
+  `0.2.0a1`, `0.2.0b1`, `0.2.0rc1` — never `-alpha`, `-alpha.2` or `alpha2`.
+  PEP 440 rewrites all three before they reach a wheel filename (`0.2.0-alpha`
+  becomes `0.2.0a0`), so the tag and the PyPI page would read differently for
+  the same build. `release.yml` checks the normalisation on every tag.
+
+## v0.1.0 - 2026-08-09
+
+First cut. Both lanes render against real data on COOPER.
+
+### Added
+- **One merged view.** `SESSIONS` (every live agent, with model, context burn
+  and status) beside `CI / PRS` (GitHub runs and open pull requests, failures
+  pinned). Panes stack instead of splitting below 110 columns.
+- **A Cursor lane, which neither parent tool had on this side.** Cursor writes
+  no session marker and no claim, so a fleet view reading only Claude's session
+  directory is blind to every Cursor agent beside it. legbar infers them from
+  `~/.cursor/projects/<slug>/agent-transcripts/`, marks them `cu`, and leaves
+  `pid` as `None` — liveness there is a transcript mtime, not a process probe,
+  and the weaker signal is labelled rather than dressed up as the stronger one.
+- **Filesystem-resolved Cursor slugs.** The slug joins path parts with `-`,
+  which is legal inside a directory name, so a naive split gets every
+  hyphenated repo wrong (`heron-ops`, `swamp-ops`, `open-vanity`). Each segment
+  now resolves longest-first against what exists on disk, falling back to the
+  naive split when nothing matches rather than raising.
+- `--once`, `--json`, `--no-git`, `--no-ci`; `q` / `g` / `r` in the full-screen
+  view.
+
+### Changed
+- **One configuration block, one prefix.** roost and leghorn grew four env-var
+  conventions between them (`ROOST_*`, `LEGHORN_ROOT`, `CCWORK_*`, and bare
+  `CLAUDE_PROJECTS_DIR` / `CURSOR_AGENT_HOME`), and — worse — the same two paths
+  were hardcoded in one tool and overridable in the other, so the pair could be
+  pointed at different data on one machine and silently disagree about what was
+  running. Every override is now `LEGBAR_*`, declared once, with the older names
+  still honoured so existing installs keep their configuration.
+- `henhouse.py` (renamed from leghorn's `coop.py`) is legbar's canonical copy of
+  the discovery layer.
+
+### Known gaps
+- Worktrees of one GitHub repo are listed as separate clones, so the same run
+  and PR appear once per worktree in the CI pane. Inherited from leghorn's
+  `github_repos()`; it wants a dedup by origin.
+- leghorn and roost do not import this copy of `henhouse.py` yet — that
+  consolidation is the next step, and until it lands the drift the shared layer
+  was meant to end is only fixed on legbar's side.

legbar-0.1.0/LICENSE

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

legbar-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: legbar
+Version: 0.1.0
+Summary: One screen for the whole fleet: live agent sessions beside GitHub CI
+Project-URL: Homepage, https://github.com/gmhoward9289-ops/legbar
+Project-URL: Issues, https://github.com/gmhoward9289-ops/legbar/issues
+Author-email: "George M. Howard" <dev@swamplink.com>
+License: MIT License
+        
+        Copyright (c) 2026 George M. Howard
+        
+        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.
+License-File: LICENSE
+Keywords: agents,ci,claude,cursor,dashboard,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.9
+Requires-Dist: windows-curses; sys_platform == 'win32'
+Description-Content-Type: text/markdown
+
+<img src="assets/legbar.svg" alt="" width="120" align="right">
+
+# legbar
+
+One screen for the whole fleet: **live agent sessions beside GitHub CI**, drawn
+from a single discovery layer so the two panes can never disagree.
+
+`roost` answers *what are the models doing*. `leghorn` answers *what are the
+repos doing*. Both are true at once and neither view contains the other — so
+watching a fleet has meant watching two windows and joining them by eye.
+legbar draws both lanes on one canvas.
+
+```
+legbar  5 sessions | 1 cursor | 1 need input | 15 ci red | 125k held | 18:37:00
+
+SESSIONS                                                    CI / PRS
+--------                                                    --------
+cc heron-ops-3c FB5  ###-------  32% needsinput  dev        X  roost          ci
+cc swamp-ops-ad OP5  ###-------  25% working     dev        X  roost          #56 ci: skip winget~
+cc heron-ops-16 FB5  #---------  10% working     dev        X  copilot-money~ Tests
+cc claude-10    OP5  #---------   8% idle        Claude     >  leghorn        release
+cu c5468eb1     -                  - idle        dev        .  leghorn        #61 checks pending
+```
+
+> **A recorded demo is coming.** The frame above is real output, captured from
+> a live fleet. The animated walkthrough its sibling tools ship
+> ([roost](https://github.com/gmhoward9289-ops/roost),
+> [leghorn](https://github.com/gmhoward9289-ops/leghorn)) lands once the
+> early bugs are shaken out — recording a tool while it is still moving
+> produces a demo that is wrong by the time anyone watches it.
+
+## What each lane shows
+
+**SESSIONS** — every live agent on the machine. Claude Code sessions are joined
+by pid against `~/.claude/sessions/<pid>.json`, with model, context burn, and
+status read from the session's own JSONL transcript. **Cursor agents appear
+too**, marked `cu` — Cursor writes no session marker and no claim, so a fleet
+view that only reads Claude's session directory is blind to every Cursor agent
+running beside it.
+
+**CI / PRS** — GitHub Actions runs and open pull requests across every clone,
+with failures pinned so a red build cannot scroll away.
+
+## Install
+
+```
+pipx install legbar
+```
+
+Python 3.9+, standard library only. Works on macOS, Linux and Windows.
+
+## Usage
+
+```
+legbar              # the full-screen view
+legbar --once       # render one frame and exit (pipes, CI, screenshots)
+legbar --json       # the joined state, for piping somewhere else
+legbar --no-git     # skip git probing if it is ever slow
+legbar --no-ci      # skip the gh sweep (offline, or when it is slow)
+```
+
+In the full-screen view: `q` quit, `g` toggle git probing, `r` refresh now.
+
+## Configuration
+
+Every override is `LEGBAR_*`. The older `roost` / `leghorn` / `ccwork` variable
+names are still honoured, so an existing install keeps whatever it had
+configured; the new name wins when both are set.
+
+| Variable | Default | What it points at |
+|---|---|---|
+| `LEGBAR_REPOS_ROOT` | `~/GitHub` | where the clones live |
+| `LEGBAR_SESSIONS_DIR` | `~/.claude/sessions` | live-session markers |
+| `LEGBAR_PROJECTS_DIR` | `~/.claude/projects` | session transcripts |
+| `LEGBAR_CURSOR_HOME` | `~/.cursor` | Cursor's agent transcripts |
+| `LEGBAR_CURSOR_MAX_IDLE_SECS` | `86400` | how far back a Cursor agent counts as live |
+| `LEGBAR_BACKENDS` | `claude,cursor` | which discovery lanes run at all |
+
+## Two honest caveats
+
+**Cursor liveness is inferred, not probed.** A Claude row means *this process
+exists* (`os.kill(pid, 0)`). A Cursor row means *this transcript moved
+recently* — Cursor writes no pid to join against. That is a weaker signal and
+it is labelled as one; `pid` is `None` for Cursor rows rather than invented.
+
+**Cursor's project slugs are lossy.** The slug joins path parts with `-`, and
+`-` is legal inside a directory name, so `c-Users-me-dev-heron-ops` reads
+equally as `dev/heron/ops` and `dev/heron-ops`. legbar resolves each segment
+longest-first against what actually exists on disk. A slug that resolves
+nowhere — another machine's checkout, a deleted clone — falls back to the
+naive split rather than raising.
+
+## It is ASCII on purpose
+
+Block-drawing characters mojibake in the Windows console, so the context bars,
+the pane rules and the status glyphs are all plain ASCII. Same constraint
+`roost`'s sparklines and `leghorn`'s tables are built around.
+
+```
+       ,__
+     _(o  \__
+    /        \
+   |  ======  |
+   |  ======  |
+    \  ====  /
+     \______/
+      ||  ||
+      ^^  ^^
+```
+
+## Read-only
+
+legbar reads transcripts and registries, and runs `git` and `gh` in read-only
+modes. It never writes to a repo.
+
+## The family
+
+- **[roost](https://github.com/gmhoward9289-ops/roost)** — `top` for Claude
+  Code: per-session context burn, models, and the subagents a session spawned.
+- **[leghorn](https://github.com/gmhoward9289-ops/leghorn)** — the repo lane on
+  its own: sessions joined to worktrees and real git state, CI, and a commit
+  feed.
+- **legbar** — both lanes on one screen, over one discovery layer.
+
+`henhouse.py` is that discovery layer: sessions, transcripts, git, GitHub, and
+Cursor. It is a working CLI in its own right (`python henhouse.py`).
+
+## License
+
+MIT

legbar-0.1.0/README.md

@@ -0,0 +1,130 @@
+<img src="assets/legbar.svg" alt="" width="120" align="right">
+
+# legbar
+
+One screen for the whole fleet: **live agent sessions beside GitHub CI**, drawn
+from a single discovery layer so the two panes can never disagree.
+
+`roost` answers *what are the models doing*. `leghorn` answers *what are the
+repos doing*. Both are true at once and neither view contains the other — so
+watching a fleet has meant watching two windows and joining them by eye.
+legbar draws both lanes on one canvas.
+
+```
+legbar  5 sessions | 1 cursor | 1 need input | 15 ci red | 125k held | 18:37:00
+
+SESSIONS                                                    CI / PRS
+--------                                                    --------
+cc heron-ops-3c FB5  ###-------  32% needsinput  dev        X  roost          ci
+cc swamp-ops-ad OP5  ###-------  25% working     dev        X  roost          #56 ci: skip winget~
+cc heron-ops-16 FB5  #---------  10% working     dev        X  copilot-money~ Tests
+cc claude-10    OP5  #---------   8% idle        Claude     >  leghorn        release
+cu c5468eb1     -                  - idle        dev        .  leghorn        #61 checks pending
+```
+
+> **A recorded demo is coming.** The frame above is real output, captured from
+> a live fleet. The animated walkthrough its sibling tools ship
+> ([roost](https://github.com/gmhoward9289-ops/roost),
+> [leghorn](https://github.com/gmhoward9289-ops/leghorn)) lands once the
+> early bugs are shaken out — recording a tool while it is still moving
+> produces a demo that is wrong by the time anyone watches it.
+
+## What each lane shows
+
+**SESSIONS** — every live agent on the machine. Claude Code sessions are joined
+by pid against `~/.claude/sessions/<pid>.json`, with model, context burn, and
+status read from the session's own JSONL transcript. **Cursor agents appear
+too**, marked `cu` — Cursor writes no session marker and no claim, so a fleet
+view that only reads Claude's session directory is blind to every Cursor agent
+running beside it.
+
+**CI / PRS** — GitHub Actions runs and open pull requests across every clone,
+with failures pinned so a red build cannot scroll away.
+
+## Install
+
+```
+pipx install legbar
+```
+
+Python 3.9+, standard library only. Works on macOS, Linux and Windows.
+
+## Usage
+
+```
+legbar              # the full-screen view
+legbar --once       # render one frame and exit (pipes, CI, screenshots)
+legbar --json       # the joined state, for piping somewhere else
+legbar --no-git     # skip git probing if it is ever slow
+legbar --no-ci      # skip the gh sweep (offline, or when it is slow)
+```
+
+In the full-screen view: `q` quit, `g` toggle git probing, `r` refresh now.
+
+## Configuration
+
+Every override is `LEGBAR_*`. The older `roost` / `leghorn` / `ccwork` variable
+names are still honoured, so an existing install keeps whatever it had
+configured; the new name wins when both are set.
+
+| Variable | Default | What it points at |
+|---|---|---|
+| `LEGBAR_REPOS_ROOT` | `~/GitHub` | where the clones live |
+| `LEGBAR_SESSIONS_DIR` | `~/.claude/sessions` | live-session markers |
+| `LEGBAR_PROJECTS_DIR` | `~/.claude/projects` | session transcripts |
+| `LEGBAR_CURSOR_HOME` | `~/.cursor` | Cursor's agent transcripts |
+| `LEGBAR_CURSOR_MAX_IDLE_SECS` | `86400` | how far back a Cursor agent counts as live |
+| `LEGBAR_BACKENDS` | `claude,cursor` | which discovery lanes run at all |
+
+## Two honest caveats
+
+**Cursor liveness is inferred, not probed.** A Claude row means *this process
+exists* (`os.kill(pid, 0)`). A Cursor row means *this transcript moved
+recently* — Cursor writes no pid to join against. That is a weaker signal and
+it is labelled as one; `pid` is `None` for Cursor rows rather than invented.
+
+**Cursor's project slugs are lossy.** The slug joins path parts with `-`, and
+`-` is legal inside a directory name, so `c-Users-me-dev-heron-ops` reads
+equally as `dev/heron/ops` and `dev/heron-ops`. legbar resolves each segment
+longest-first against what actually exists on disk. A slug that resolves
+nowhere — another machine's checkout, a deleted clone — falls back to the
+naive split rather than raising.
+
+## It is ASCII on purpose
+
+Block-drawing characters mojibake in the Windows console, so the context bars,
+the pane rules and the status glyphs are all plain ASCII. Same constraint
+`roost`'s sparklines and `leghorn`'s tables are built around.
+
+```
+       ,__
+     _(o  \__
+    /        \
+   |  ======  |
+   |  ======  |
+    \  ====  /
+     \______/
+      ||  ||
+      ^^  ^^
+```
+
+## Read-only
+
+legbar reads transcripts and registries, and runs `git` and `gh` in read-only
+modes. It never writes to a repo.
+
+## The family
+
+- **[roost](https://github.com/gmhoward9289-ops/roost)** — `top` for Claude
+  Code: per-session context burn, models, and the subagents a session spawned.
+- **[leghorn](https://github.com/gmhoward9289-ops/leghorn)** — the repo lane on
+  its own: sessions joined to worktrees and real git state, CI, and a commit
+  feed.
+- **legbar** — both lanes on one screen, over one discovery layer.
+
+`henhouse.py` is that discovery layer: sessions, transcripts, git, GitHub, and
+Cursor. It is a working CLI in its own right (`python henhouse.py`).
+
+## License
+
+MIT