agents-tree 0.1.0__tar.gz

agents_tree-0.1.0/LICENSE

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

agents_tree-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: agents-tree
+Version: 0.1.0
+Summary: Show Claude Code sessions and their subagents as a live tree: model, effort, context use, elapsed time, status.
+Keywords: claude-code,subagents,agents,cli,tui,herdr
+Author: Karel Blavka
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/blavka/agents-tree
+Project-URL: Issues, https://github.com/blavka/agents-tree/issues
+Description-Content-Type: text/markdown
+
+# agents-tree
+
+See what your coding agents are doing. `agents-tree` shows every running Claude
+Code session and the subagents it spawned as a tree, with each agent's model and
+effort, how full its context window is, how long it has been running, and its
+status.
+
+```
+Split protocol modules  [75d94683]  /home/me/src/core  background
+main                                            opus-5-5 (xhigh)        742k  74 % of 1M     42h00m  working
+├─ Explore: Study dskit modules and services    opus-5-5 (high)          53k   5 % of 1M      2m46s  completed
+└─ qp-builder: Builder: query list parsing fix  opus-5-5 (xhigh)        505k  50 % of 1M     20h16m  running
+
+Review flaky test  [b443f8f0]  /home/me/src/api  interactive
+main                                            opus-5-5 (high)         228k  23 % of 1M     41m19s  busy
+└─ claude-code-guide: Look up hook events       haiku-4-5                61k  31 % of 200k    2m34s  completed
+```
+
+It reads the transcripts Claude Code keeps on disk and never talks to a session,
+so nothing it prints ends up in an agent's context. It has no dependencies
+beyond Python 3.10.
+
+Claude Code is supported today; Codex and Grok are planned.
+
+## Install
+
+```bash
+uv tool install agents-tree      # or: pipx install agents-tree
+```
+
+From a checkout: `uv tool install .`, or run it in place with
+`PYTHONPATH=src python3 -m agents_tree`.
+
+## Use
+
+```bash
+agents-tree                 # every running session on this machine
+agents-tree .               # sessions running in this directory (or its newest session)
+agents-tree ~/src/api       # same, for another directory
+agents-tree b443f8f0        # one session, by id or a unique prefix (an ambiguous one lists the matches)
+agents-tree -r              # only running subagents and their parents
+agents-tree -w              # live view like top, refreshed every 2 s (-n 5 for 5 s)
+```
+
+In the live view:
+
+| Key | Does |
+| --- | --- |
+| `↑` `↓` / `j` `k` / wheel | select an agent |
+| `Enter` / `→` / click | open its detail: the prompt it was given, its tool calls (and the one it is waiting on), its last message, request and token counts, transcript path |
+| `Esc` / `←` / `q` | back to the tree (in the tree: clear the selection, then quit) |
+| `PgUp` `PgDn` `Home` `End` | scroll the detail, or jump through the tree |
+| `r` | toggle running-only |
+| `Ctrl+C` | quit |
+
+The live view takes the mouse for clicks and the wheel; most terminals still
+select text with Shift held, or start it with `--no-mouse`. When the tree is
+taller than the terminal, the oldest finished agents are folded into a
+"… N older finished agents hidden" line.
+
+| Column | Meaning |
+| --- | --- |
+| label | `agent-type: description` as the spawning agent gave it; `main` for the session itself |
+| model (effort) | model of the agent's latest request, and its effort level (models without effort show none) |
+| context | tokens in the latest request (input + cache + output), and that as a share of the context window |
+| elapsed | first to last transcript entry; up to now while the agent runs |
+| status | subagents: `running` (active in the last 2 minutes, or waiting on a tool call), `completed` / `failed` (as Claude Code reported), `done` (finished, no outcome recorded), `idle` (a teammate waiting for its next message), `stale` (no sign of life and no completion marker); `main`: the session's own state, or `not running` |
+
+### Caveats
+
+- **Context window is inferred.** Claude Code does not record it, so it is taken
+  from the model family: 1M for Claude 5 models (Opus, Sonnet, Fable), 200k
+  otherwise. Override with `--window 200000` or `AGENTS_TREE_WINDOW`.
+- **Transcript format is internal to Claude Code** and may change between
+  releases. Unknown lines are skipped, but a field that moves makes its column
+  show `-` until agents-tree is updated.
+- **Elapsed** spans wall-clock time, so a session resumed over several days, or a
+  subagent woken up again by a message, shows that whole span.
+- Running sessions come from `claude agents --json`; without `claude` on `PATH`,
+  agents-tree falls back to `~/.claude/sessions/` (interactive sessions only).
+
+## herdr plugin
+
+[herdr](https://herdr.dev) shows your agents, not their subagents. The plugin in
+this repository opens the live tree for the focused agent pane over that pane;
+closing it gives the layout back:
+
+```bash
+herdr integration install claude                 # herdr learns each pane's session id
+herdr plugin install blavka/agents-tree
+herdr plugin action invoke agents-tree.setup-keys
+```
+
+| Key | Action |
+| --- | --- |
+| `prefix+a` | live tree of the focused agent's session; `q` or the same key closes it |
+| `prefix+shift+a` | live tree of every running session |
+
+On a pane without an agent, `prefix+a` shows every running session. The plugin
+runs the copy of agents-tree bundled in the repository, so it needs only
+`python3` 3.10+ (or `AGENTS_TREE_PYTHON` pointing at one). `setup-keys` writes
+one marked block into your herdr `config.toml` (backed up first) and leaves keys
+you already use alone; `agents-tree.remove-keys` takes it out again. The
+`open-split` and `open-tab` actions show the same tree in a split or a tab.
+
+For development, link a checkout instead: `herdr plugin link /path/to/agents-tree`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run pylint src
+uv run pylint tests --disable=redefined-outer-name,protected-access,unused-argument
+uv run pyright
+```
+
+CI (`.github/workflows/test.yaml`) runs the same on every push and pull request:
+lint and types on Python 3.12, then the tests, a test run and a package build on
+3.10 to 3.14.
+
+To release, bump `version` in `pyproject.toml`, `src/agents_tree/__init__.py` and
+`herdr-plugin.toml`, then push a matching tag (`git tag v0.2.0 && git push origin
+v0.2.0`). `.github/workflows/publish.yaml` checks the tag against the version,
+tests, builds and publishes to PyPI through trusted publishing.
+
+Providers live in `src/agents_tree/providers/`: each turns one agent CLI's files
+into the provider-neutral `Session`/`Agent` model in `model.py`, which
+`render.py` draws.
+
+## License
+
+MIT

agents_tree-0.1.0/README.md

@@ -0,0 +1,133 @@
+# agents-tree
+
+See what your coding agents are doing. `agents-tree` shows every running Claude
+Code session and the subagents it spawned as a tree, with each agent's model and
+effort, how full its context window is, how long it has been running, and its
+status.
+
+```
+Split protocol modules  [75d94683]  /home/me/src/core  background
+main                                            opus-5-5 (xhigh)        742k  74 % of 1M     42h00m  working
+├─ Explore: Study dskit modules and services    opus-5-5 (high)          53k   5 % of 1M      2m46s  completed
+└─ qp-builder: Builder: query list parsing fix  opus-5-5 (xhigh)        505k  50 % of 1M     20h16m  running
+
+Review flaky test  [b443f8f0]  /home/me/src/api  interactive
+main                                            opus-5-5 (high)         228k  23 % of 1M     41m19s  busy
+└─ claude-code-guide: Look up hook events       haiku-4-5                61k  31 % of 200k    2m34s  completed
+```
+
+It reads the transcripts Claude Code keeps on disk and never talks to a session,
+so nothing it prints ends up in an agent's context. It has no dependencies
+beyond Python 3.10.
+
+Claude Code is supported today; Codex and Grok are planned.
+
+## Install
+
+```bash
+uv tool install agents-tree      # or: pipx install agents-tree
+```
+
+From a checkout: `uv tool install .`, or run it in place with
+`PYTHONPATH=src python3 -m agents_tree`.
+
+## Use
+
+```bash
+agents-tree                 # every running session on this machine
+agents-tree .               # sessions running in this directory (or its newest session)
+agents-tree ~/src/api       # same, for another directory
+agents-tree b443f8f0        # one session, by id or a unique prefix (an ambiguous one lists the matches)
+agents-tree -r              # only running subagents and their parents
+agents-tree -w              # live view like top, refreshed every 2 s (-n 5 for 5 s)
+```
+
+In the live view:
+
+| Key | Does |
+| --- | --- |
+| `↑` `↓` / `j` `k` / wheel | select an agent |
+| `Enter` / `→` / click | open its detail: the prompt it was given, its tool calls (and the one it is waiting on), its last message, request and token counts, transcript path |
+| `Esc` / `←` / `q` | back to the tree (in the tree: clear the selection, then quit) |
+| `PgUp` `PgDn` `Home` `End` | scroll the detail, or jump through the tree |
+| `r` | toggle running-only |
+| `Ctrl+C` | quit |
+
+The live view takes the mouse for clicks and the wheel; most terminals still
+select text with Shift held, or start it with `--no-mouse`. When the tree is
+taller than the terminal, the oldest finished agents are folded into a
+"… N older finished agents hidden" line.
+
+| Column | Meaning |
+| --- | --- |
+| label | `agent-type: description` as the spawning agent gave it; `main` for the session itself |
+| model (effort) | model of the agent's latest request, and its effort level (models without effort show none) |
+| context | tokens in the latest request (input + cache + output), and that as a share of the context window |
+| elapsed | first to last transcript entry; up to now while the agent runs |
+| status | subagents: `running` (active in the last 2 minutes, or waiting on a tool call), `completed` / `failed` (as Claude Code reported), `done` (finished, no outcome recorded), `idle` (a teammate waiting for its next message), `stale` (no sign of life and no completion marker); `main`: the session's own state, or `not running` |
+
+### Caveats
+
+- **Context window is inferred.** Claude Code does not record it, so it is taken
+  from the model family: 1M for Claude 5 models (Opus, Sonnet, Fable), 200k
+  otherwise. Override with `--window 200000` or `AGENTS_TREE_WINDOW`.
+- **Transcript format is internal to Claude Code** and may change between
+  releases. Unknown lines are skipped, but a field that moves makes its column
+  show `-` until agents-tree is updated.
+- **Elapsed** spans wall-clock time, so a session resumed over several days, or a
+  subagent woken up again by a message, shows that whole span.
+- Running sessions come from `claude agents --json`; without `claude` on `PATH`,
+  agents-tree falls back to `~/.claude/sessions/` (interactive sessions only).
+
+## herdr plugin
+
+[herdr](https://herdr.dev) shows your agents, not their subagents. The plugin in
+this repository opens the live tree for the focused agent pane over that pane;
+closing it gives the layout back:
+
+```bash
+herdr integration install claude                 # herdr learns each pane's session id
+herdr plugin install blavka/agents-tree
+herdr plugin action invoke agents-tree.setup-keys
+```
+
+| Key | Action |
+| --- | --- |
+| `prefix+a` | live tree of the focused agent's session; `q` or the same key closes it |
+| `prefix+shift+a` | live tree of every running session |
+
+On a pane without an agent, `prefix+a` shows every running session. The plugin
+runs the copy of agents-tree bundled in the repository, so it needs only
+`python3` 3.10+ (or `AGENTS_TREE_PYTHON` pointing at one). `setup-keys` writes
+one marked block into your herdr `config.toml` (backed up first) and leaves keys
+you already use alone; `agents-tree.remove-keys` takes it out again. The
+`open-split` and `open-tab` actions show the same tree in a split or a tab.
+
+For development, link a checkout instead: `herdr plugin link /path/to/agents-tree`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run pylint src
+uv run pylint tests --disable=redefined-outer-name,protected-access,unused-argument
+uv run pyright
+```
+
+CI (`.github/workflows/test.yaml`) runs the same on every push and pull request:
+lint and types on Python 3.12, then the tests, a test run and a package build on
+3.10 to 3.14.
+
+To release, bump `version` in `pyproject.toml`, `src/agents_tree/__init__.py` and
+`herdr-plugin.toml`, then push a matching tag (`git tag v0.2.0 && git push origin
+v0.2.0`). `.github/workflows/publish.yaml` checks the tag against the version,
+tests, builds and publishes to PyPI through trusted publishing.
+
+Providers live in `src/agents_tree/providers/`: each turns one agent CLI's files
+into the provider-neutral `Session`/`Agent` model in `model.py`, which
+`render.py` draws.
+
+## License
+
+MIT

agents_tree-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "agents-tree"
+version = "0.1.0"
+description = "Show Claude Code sessions and their subagents as a live tree: model, effort, context use, elapsed time, status."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "claude-code",
+    "subagents",
+    "agents",
+    "cli",
+    "tui",
+    "herdr",
+]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[[project.authors]]
+name = "Karel Blavka"
+
+[project.urls]
+Homepage = "https://github.com/blavka/agents-tree"
+Issues = "https://github.com/blavka/agents-tree/issues"
+
+[project.scripts]
+agents-tree = "agents_tree.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pylint>=4.1.2",
+    "pyright>=1.1.414",
+    "pytest>=9.1.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+[tool.pylint.main]
+py-version = "3.10"
+
+[tool.pylint.format]
+max-line-length = 100
+
+[tool.pylint."messages control"]
+disable = [
+    "missing-module-docstring",
+    "missing-class-docstring",
+    "missing-function-docstring",
+    "too-many-arguments",
+    "too-many-positional-arguments",
+    "too-many-instance-attributes",
+    "too-many-locals",
+    "too-many-branches",
+    "too-many-return-statements",
+    "too-few-public-methods",
+]

agents_tree-0.1.0/pyproject.toml.orig

@@ -0,0 +1,64 @@
+[project]
+name = "agents-tree"
+version = "0.1.0"
+description = "Show Claude Code sessions and their subagents as a live tree: model, effort, context use, elapsed time, status."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Karel Blavka" }]
+keywords = ["claude-code", "subagents", "agents", "cli", "tui", "herdr"]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/blavka/agents-tree"
+Issues = "https://github.com/blavka/agents-tree/issues"
+
+[project.scripts]
+agents-tree = "agents_tree.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pylint>=4.1.2",
+    "pyright>=1.1.414",
+    "pytest>=9.1.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+[tool.pylint.main]
+py-version = "3.10"
+
+[tool.pylint.format]
+max-line-length = 100
+
+[tool.pylint."messages control"]
+# Docstrings where they say something, and design limits judged in review, not by count.
+disable = [
+    "missing-module-docstring",
+    "missing-class-docstring",
+    "missing-function-docstring",
+    "too-many-arguments",
+    "too-many-positional-arguments",
+    "too-many-instance-attributes",
+    "too-many-locals",
+    "too-many-branches",
+    "too-many-return-statements",
+    "too-few-public-methods",
+]

agents_tree-0.1.0/src/agents_tree/__init__.py

@@ -0,0 +1,3 @@
+"""Show coding-agent sessions and their subagents as a live tree."""
+
+__version__ = "0.1.0"

agents_tree-0.1.0/src/agents_tree/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from agents_tree.cli import main
+
+sys.exit(main())

agents_tree-0.1.0/src/agents_tree/cli.py

@@ -0,0 +1,105 @@
+"""Command line: one-shot print, or a top-like live view with --watch."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import signal
+import sys
+from collections.abc import Callable
+
+from agents_tree import __version__, live
+from agents_tree.model import Session, override_window, sanitize
+from agents_tree.providers import PROVIDERS
+from agents_tree.render import render, style
+
+DESCRIPTION = "Show coding-agent sessions and their subagents as a tree: " \
+              "model (effort), context use, elapsed time and status."
+EPILOG = """\
+targets:
+  (none)        every running session on this machine
+  DIR           sessions running in DIR ("." works); if none, DIR's newest session
+  SESSION-ID    one session (a unique prefix is enough)
+
+live view keys: ↑/↓ or j/k select, enter or a click shows the agent's detail,
+  esc goes back, r toggles running-only, q quits
+
+Reads local transcripts only. Run it in its own terminal (or the herdr plugin):
+started with `!` inside an agent, its output lands in that agent's context.
+"""
+
+
+def _positive_int(value: str) -> int:
+    try:
+        n = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"not a whole number of tokens: {value!r}") from None
+    if n <= 0:
+        raise argparse.ArgumentTypeError("must be positive")
+    return n
+
+
+def _env_window() -> int | None:
+    value = os.environ.get("AGENTS_TREE_WINDOW", "").strip()
+    if not value:
+        return None
+    try:
+        return _positive_int(value)
+    except argparse.ArgumentTypeError:
+        print(f"agents-tree: ignoring AGENTS_TREE_WINDOW={value!r}", file=sys.stderr)
+        return None
+
+
+def parse_args(argv: list[str] | None) -> argparse.Namespace:
+    ap = argparse.ArgumentParser(prog="agents-tree", description=DESCRIPTION, epilog=EPILOG,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("target", nargs="?", metavar="DIR|SESSION-ID")
+    ap.add_argument("-w", "--watch", action="store_true", help="live view, like top")
+    ap.add_argument("-n", "--interval", type=float, default=2.0, metavar="SECONDS",
+                    help="live view refresh interval (default 2)")
+    ap.add_argument("-r", "--running", action="store_true",
+                    help="only running subagents (and their parents)")
+    ap.add_argument("--window", type=_positive_int, metavar="TOKENS", default=_env_window(),
+                    help="context window for the %% column (default: per model)")
+    ap.add_argument("--provider", choices=sorted(PROVIDERS), default="claude")
+    ap.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    ap.add_argument("--no-mouse", dest="mouse", action="store_false",
+                    help="live view: leave the mouse to the terminal (text selection)")
+    ap.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    args = ap.parse_args(argv)
+    if args.interval <= 0:
+        ap.error("--interval must be positive")
+    return args
+
+
+def loader(args: argparse.Namespace) -> Callable[[], list[Session]]:
+    """Sessions as the views get them: sanitised once, with --window applied."""
+    def load() -> list[Session]:
+        sessions = PROVIDERS[args.provider].sessions(args.target)
+        sanitize(sessions)
+        override_window(sessions, args.window)
+        return sessions
+
+    return load
+
+
+def main(argv: list[str] | None = None) -> int:
+    signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+    args = parse_args(argv)
+    color = args.color == "always" or (args.color == "auto" and sys.stdout.isatty()
+                                       and not os.environ.get("NO_COLOR"))
+    load = loader(args)
+    if not args.watch:
+        try:
+            sessions = load()
+        except LookupError as e:
+            print(style(color, "90", str(e)))
+            return 1
+        print(render(sessions, running_only=args.running, color=color))
+        return 0
+    try:
+        live.run(load, interval=args.interval, color=color, running_only=args.running,
+                 mouse=args.mouse)
+    except KeyboardInterrupt:
+        pass
+    return 0