agyscope 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. agyscope-0.2.1/.github/workflows/test.yml +72 -0
  2. agyscope-0.2.1/.gitignore +9 -0
  3. agyscope-0.2.1/.pre-commit-config.yaml +42 -0
  4. agyscope-0.2.1/CHANGELOG.md +44 -0
  5. agyscope-0.2.1/LICENSE +21 -0
  6. agyscope-0.2.1/PKG-INFO +489 -0
  7. agyscope-0.2.1/README.md +464 -0
  8. agyscope-0.2.1/examples/config.toml +29 -0
  9. agyscope-0.2.1/examples/themes/catppuccin-mocha.toml +23 -0
  10. agyscope-0.2.1/init.lua +12 -0
  11. agyscope-0.2.1/integrations/rex/hooks.json +16 -0
  12. agyscope-0.2.1/lua/agyscope/config.lua +220 -0
  13. agyscope-0.2.1/lua/agyscope/init.lua +80 -0
  14. agyscope-0.2.1/lua/agyscope/layer.lua +51 -0
  15. agyscope-0.2.1/lua/agyscope/message.lua +52 -0
  16. agyscope-0.2.1/lua/agyscope/rexapi.lua +143 -0
  17. agyscope-0.2.1/pyproject.toml +46 -0
  18. agyscope-0.2.1/src/agyscope/__init__.py +3 -0
  19. agyscope-0.2.1/src/agyscope/__main__.py +7 -0
  20. agyscope-0.2.1/src/agyscope/agentdb.py +221 -0
  21. agyscope-0.2.1/src/agyscope/app.py +291 -0
  22. agyscope-0.2.1/src/agyscope/cli.py +153 -0
  23. agyscope-0.2.1/src/agyscope/config.py +162 -0
  24. agyscope-0.2.1/src/agyscope/discovery.py +137 -0
  25. agyscope-0.2.1/src/agyscope/integrations/__init__.py +1 -0
  26. agyscope-0.2.1/src/agyscope/integrations/rex/__init__.py +1 -0
  27. agyscope-0.2.1/src/agyscope/integrations/rex/focus.py +41 -0
  28. agyscope-0.2.1/src/agyscope/integrations/rex/hook.py +280 -0
  29. agyscope-0.2.1/src/agyscope/integrations/rex/pointer.py +45 -0
  30. agyscope-0.2.1/src/agyscope/keymap.py +126 -0
  31. agyscope-0.2.1/src/agyscope/pager.py +46 -0
  32. agyscope-0.2.1/src/agyscope/resolve.py +143 -0
  33. agyscope-0.2.1/src/agyscope/textview.py +7 -0
  34. agyscope-0.2.1/src/agyscope/themes.py +167 -0
  35. agyscope-0.2.1/src/agyscope/transcript.py +482 -0
  36. agyscope-0.2.1/src/agyscope/viewstate.py +173 -0
  37. agyscope-0.2.1/src/agyscope/widgets.py +668 -0
  38. agyscope-0.2.1/stylua.toml +8 -0
  39. agyscope-0.2.1/tests/lua/config_test.lua +97 -0
  40. agyscope-0.2.1/tests/lua/harness.lua +32 -0
  41. agyscope-0.2.1/tests/lua/layer_test.lua +54 -0
  42. agyscope-0.2.1/tests/lua/manual_toggle.lua +36 -0
  43. agyscope-0.2.1/tests/lua/rexapi_test.lua +205 -0
  44. agyscope-0.2.1/tests/py/fixtures/app/brain/chk-2222/.system_generated/logs/transcript.jsonl +2 -0
  45. agyscope-0.2.1/tests/py/fixtures/app/brain/plan-1111/.system_generated/logs/transcript.jsonl +6 -0
  46. agyscope-0.2.1/tests/py/fixtures/app/brain/rev-3333/.system_generated/logs/transcript.jsonl +4 -0
  47. agyscope-0.2.1/tests/py/fixtures/app/brain/root-0000/.system_generated/logs/transcript.jsonl +8 -0
  48. agyscope-0.2.1/tests/py/fixtures/make_fixtures.py +100 -0
  49. agyscope-0.2.1/tests/py/helpers.py +55 -0
  50. agyscope-0.2.1/tests/py/test_agentdb.py +260 -0
  51. agyscope-0.2.1/tests/py/test_app.py +798 -0
  52. agyscope-0.2.1/tests/py/test_cli.py +234 -0
  53. agyscope-0.2.1/tests/py/test_config.py +320 -0
  54. agyscope-0.2.1/tests/py/test_discovery.py +146 -0
  55. agyscope-0.2.1/tests/py/test_hook.py +343 -0
  56. agyscope-0.2.1/tests/py/test_keymap.py +86 -0
  57. agyscope-0.2.1/tests/py/test_keymap_textual.py +46 -0
  58. agyscope-0.2.1/tests/py/test_package.py +12 -0
  59. agyscope-0.2.1/tests/py/test_pager.py +37 -0
  60. agyscope-0.2.1/tests/py/test_resolve.py +136 -0
  61. agyscope-0.2.1/tests/py/test_rex_pointer.py +39 -0
  62. agyscope-0.2.1/tests/py/test_themes.py +152 -0
  63. agyscope-0.2.1/tests/py/test_transcript.py +203 -0
  64. agyscope-0.2.1/tests/py/test_viewstate.py +371 -0
  65. agyscope-0.2.1/tests/py/test_widgets.py +833 -0
  66. agyscope-0.2.1/tests/run_all.sh +41 -0
@@ -0,0 +1,72 @@
1
+ name: test
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ concurrency:
12
+ group: ${{ github.workflow }}-${{ github.ref }}
13
+ cancel-in-progress: true
14
+
15
+ jobs:
16
+ python:
17
+ strategy:
18
+ fail-fast: false
19
+ matrix:
20
+ os: [ubuntu-latest, macos-latest]
21
+ python: ["3.11", "3.13", "3.x"]
22
+ runs-on: ${{ matrix.os }}
23
+ steps:
24
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
25
+ - uses: actions/setup-python@v5
26
+ id: setup-python
27
+ with:
28
+ python-version: ${{ matrix.python }}
29
+ - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
30
+ with:
31
+ python-version: ${{ steps.setup-python.outputs.python-version }}
32
+ enable-cache: true
33
+ cache-dependency-glob: pyproject.toml # no uv.lock is shipped; uv resolves from PyPI
34
+ - name: Python tests (pytest, incl. Textual)
35
+ env:
36
+ UV_PYTHON: ${{ steps.setup-python.outputs.python-version }}
37
+ run: sh tests/run_all.sh py
38
+
39
+ lua:
40
+ name: lua ${{ matrix.lua }}
41
+ strategy:
42
+ fail-fast: false
43
+ matrix:
44
+ lua: ["5.1.5", "luajit-2.1"] # Rex runs Lua 5.1
45
+ runs-on: ubuntu-latest
46
+ steps:
47
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
48
+ - uses: leafo/gh-actions-lua@32909a2dea0a48c433aec79e7fcd31b4cd55800f # v13.1.0
49
+ with:
50
+ luaVersion: ${{ matrix.lua }}
51
+ - name: Lua tests
52
+ run: sh tests/run_all.sh lua
53
+
54
+ lint:
55
+ name: pre-commit (lint)
56
+ runs-on: ubuntu-latest
57
+ steps:
58
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
59
+ - uses: JohnnyMorganz/stylua-action@76fd70c03e6340ceaf673366712db9b20560b402 # v5.0.0
60
+ with:
61
+ token: ${{ secrets.GITHUB_TOKEN }}
62
+ version: "2.6.0"
63
+ args: --version
64
+ - name: Install pre-commit
65
+ run: |
66
+ pipx install pre-commit==4.3.0
67
+ shellcheck --version
68
+ - name: pre-commit
69
+ env:
70
+ REQUIRE_LINT_TOOLS: "1"
71
+ SKIP: tests # the python and lua jobs run them
72
+ run: pre-commit run --all-files --show-diff-on-failure
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .DS_Store
4
+ .venv/
5
+ uv.lock
6
+ dist/
7
+ build/
8
+ *.egg-info/
9
+ .pytest_cache/
@@ -0,0 +1,42 @@
1
+ # pre-commit hooks: `pre-commit install` once, then they run on every commit.
2
+ # All hooks are local and use tools already on PATH; nothing is downloaded.
3
+ # shellcheck and stylua are skipped with a note when missing, unless
4
+ # REQUIRE_LINT_TOOLS=1 (CI sets it).
5
+ minimum_pre_commit_version: "3.2.0"
6
+ repos:
7
+ - repo: local
8
+ hooks:
9
+ - id: trailing-whitespace
10
+ name: no trailing whitespace
11
+ language: pygrep
12
+ entry: '[ \t]+$'
13
+ types: [text]
14
+ - id: end-of-file
15
+ name: files end with one newline
16
+ language: pygrep
17
+ entry: '(?<!\n)\Z|\n\n\Z'
18
+ args: [--multiline]
19
+ types: [text]
20
+ - id: check-yaml
21
+ name: YAML parses
22
+ language: system
23
+ entry: ruby -ryaml -e 'ARGV.each { |f| YAML.load_file(f) }'
24
+ types: [yaml]
25
+ - id: shellcheck
26
+ name: shellcheck
27
+ language: system
28
+ entry: sh -c 'if command -v shellcheck >/dev/null; then exec shellcheck "$@"; fi; [ "${REQUIRE_LINT_TOOLS:-}" != 1 ] || { echo "shellcheck not found"; exit 1; }; echo "shellcheck not installed; skipped"' --
29
+ types: [shell]
30
+ verbose: true
31
+ - id: stylua
32
+ name: stylua (format check)
33
+ language: system
34
+ entry: sh -c 'if command -v stylua >/dev/null; then exec stylua --check "$@"; fi; [ "${REQUIRE_LINT_TOOLS:-}" != 1 ] || { echo "stylua not found"; exit 1; }; echo "stylua not installed; skipped"' --
35
+ types: [lua]
36
+ verbose: true
37
+ - id: tests
38
+ name: plugin tests
39
+ language: system
40
+ entry: sh tests/run_all.sh
41
+ pass_filenames: false
42
+ files: '(\.(lua|py)$|pyproject\.toml)'
@@ -0,0 +1,44 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.2.1] - 2026-11-16
9
+
10
+ ### Changed
11
+
12
+ - **BREAKING:** Switched configuration from `config.json` to TOML (`config.toml`).
13
+ `config.json` is no longer read; agyscope shows a warning if `config.json` exists next to
14
+ a missing `config.toml`.
15
+ - **BREAKING:** Minimum supported Python version raised from 3.10 to **Python 3.11**
16
+ (uses stdlib `tomllib` with no new dependencies).
17
+ - Subagent state and step colors now follow the active Textual theme.
18
+
19
+ ### Added
20
+
21
+ - Published to PyPI; install with `uv tool install agyscope`.
22
+ - Theme support via `theme` in `config.toml` and `--theme NAME`, plus user themes loaded
23
+ from `~/.config/agyscope/themes/*.toml` with `agyscope-<state>` variable overrides.
24
+ - Shipped `examples/themes/catppuccin-mocha.toml` and `examples/config.toml`.
25
+ - Resizable list columns: configurable initial widths via `[columns]` in `config.toml` and
26
+ session-only mouse dragging of column header borders.
27
+ - Horizontal marquee scrolling for the highlighted subagent's **Last step** cell when it
28
+ overflows (`marquee` in `config.toml`, `--marquee` / `--no-marquee`).
29
+
30
+ ## [0.2.0] - 2026-11-16
31
+
32
+ ### Changed
33
+
34
+ - Renamed project from `rex-agy-subagent` to `agyscope` and restructured it as an
35
+ installable Python package (`agyscope` and `agyscope-rex-hook`).
36
+ - Replaced the earlier UI with a full-screen Textual panel featuring subagent list and
37
+ live step view screens, `emacs`/`vim` key presets, folding, and pager support.
38
+
39
+ ## [0.1.0] - 2026-11-15
40
+
41
+ ### Added
42
+
43
+ - Initial `rex-agy-subagent` release: subagent viewer panel and `PostToolUse` hook
44
+ integration for Rex terminal panes.
agyscope-0.2.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 daehyeok
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,489 @@
1
+ Metadata-Version: 2.5
2
+ Name: agyscope
3
+ Version: 0.2.1
4
+ Summary: Unofficial read-only subagent viewer for the Antigravity agent CLI (agy)
5
+ Project-URL: Homepage, https://github.com/daehyeok/agyscope
6
+ Project-URL: Repository, https://github.com/daehyeok/agyscope
7
+ Project-URL: Issues, https://github.com/daehyeok/agyscope/issues
8
+ Project-URL: Releases, https://github.com/daehyeok/agyscope/releases
9
+ Author: Daehyeok Mun
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: agy,antigravity,rex,subagent,textual,tui
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: MacOS
17
+ Classifier: Operating System :: POSIX :: Linux
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Topic :: Software Development
21
+ Classifier: Topic :: Terminals
22
+ Requires-Python: >=3.11
23
+ Requires-Dist: textual<9,>=8.2
24
+ Description-Content-Type: text/markdown
25
+
26
+ # agyscope
27
+
28
+ [![test](https://github.com/daehyeok/agyscope/actions/workflows/test.yml/badge.svg)](https://github.com/daehyeok/agyscope/actions/workflows/test.yml)
29
+
30
+ `agyscope` is an unofficial, read-only viewer for the subagents of an Antigravity agent
31
+ CLI (`agy`) session. It runs in any terminal.
32
+
33
+ It shows a full-width subagent list with each subagent's state, model, age, and last
34
+ step. Press `Enter` on any subagent to open a full-screen view of its live steps, where
35
+ you can fold turns and tool calls, scroll line-by-line, or open the full transcript in
36
+ a pager. Press `Esc` or `q` to return to the list. agyscope only reads files. It never
37
+ sends anything to an agent or a terminal.
38
+
39
+ > **Unofficial.** This project is not affiliated with or endorsed by Google. See
40
+ > [Disclaimer](#disclaimer).
41
+
42
+ ![demo](https://raw.githubusercontent.com/daehyeok/agyscope/main/docs/demo.gif)
43
+
44
+ agyscope rebuilds the tree from the agent's transcripts, so it always shows every
45
+ subagent of the session, including ones that finished before you opened it. Closing
46
+ it loses nothing. Reopen it and everything is back.
47
+
48
+ Running agents in [Rex](#rex-integration) panes? The optional Rex integration opens
49
+ agyscope in a floating pane next to the agent, from a key or automatically when the
50
+ first subagent starts.
51
+
52
+ ## Install
53
+
54
+ Requirements, on every host that runs the agent:
55
+
56
+ - [uv](https://docs.astral.sh/uv/) and Python 3.11 or newer (a uv-managed Python is fine);
57
+ - `less`, or the pager you configure;
58
+ - `lsof` to follow an agent process. On Linux it is optional: without it agyscope reads
59
+ `/proc/<pid>/fd`.
60
+
61
+ Install the `agyscope` and `agyscope-rex-hook` commands from PyPI with uv:
62
+
63
+ ```sh
64
+ uv tool install agyscope
65
+ ```
66
+
67
+ Upgrade, pin a version, or uninstall:
68
+
69
+ ```sh
70
+ uv tool upgrade agyscope
71
+ uv tool install agyscope==0.2.1
72
+ uv tool uninstall agyscope
73
+ ```
74
+
75
+ (`pipx install agyscope` also works.)
76
+
77
+ uv puts the commands in its tool bin directory (normally `~/.local/bin`) and installs
78
+ Textual into the tool's own environment, using the host's own index configuration
79
+ (`uv.toml`, `UV_INDEX_URL`, ...). Nothing else is installed globally.
80
+
81
+ ### Development / from source
82
+
83
+ To install directly from GitHub or from an editable local clone (edits to the clone
84
+ take effect at once):
85
+
86
+ ```sh
87
+ uv tool install git+https://github.com/daehyeok/agyscope
88
+ ```
89
+
90
+ ```sh
91
+ git clone https://github.com/daehyeok/agyscope ~/src/agyscope
92
+ uv tool install --editable ~/src/agyscope
93
+ ```
94
+
95
+ ## Usage
96
+
97
+ ```sh
98
+ agyscope --pid 1234 # follow the agent process 1234
99
+ agyscope --conversation <id> # show one conversation
100
+ agyscope --once --pid 1234 # print the list once as plain text
101
+ agyscope --once --conversation <id> # same, for a conversation id
102
+ agyscope --view <child-id-prefix> --conversation <id> # one subagent, fully unfolded
103
+ ```
104
+
105
+ Which conversation is shown:
106
+
107
+ 1. `--pid PID`: the agent keeps `<data dir>/presence/<conversation>.lock` open, and the
108
+ open files come from `lsof`, or from `/proc/<pid>/fd` when `lsof` is missing. The
109
+ directory holding `presence/` is the data directory, so no setting is needed.
110
+ agyscope re-checks the pid every 3 seconds, so resuming another conversation in the
111
+ same process switches the view. A dead pid keeps the last answer.
112
+ 2. With the [Rex integration](#rex-integration), the conversation the hook last recorded
113
+ for the pane (`--rex-block`).
114
+ 3. `--conversation ID`.
115
+
116
+ From the root conversation it follows every `invoke_subagent` result to the child
117
+ transcripts, recursively.
118
+
119
+ `--once` and `--view` print text and exit; they don't start the Textual UI. The exit
120
+ code is 0 on success, 1 when no conversation was found (or after `ctrl+c`), and 2 when
121
+ agyscope crashed. After a crash on a terminal it waits for `Enter`, so the traceback
122
+ stays readable.
123
+
124
+ Settings flags: `--app-dir DIR`, `--keymap emacs|vim`, `--keys-json JSON`,
125
+ `--pager-json JSON`, `--theme NAME`, `--marquee` / `--no-marquee`
126
+ (see [Configuration](#configuration)). `agyscope --help` lists them all.
127
+
128
+ ## Configuration
129
+
130
+ For each setting, the first source that sets it wins:
131
+
132
+ 1. command-line flags (`--app-dir`, `--keymap`, `--keys-json`, `--pager-json`, `--theme`,
133
+ `--marquee` / `--no-marquee`);
134
+ 2. the config file `${XDG_CONFIG_HOME:-~/.config}/agyscope/config.toml` (normally
135
+ `~/.config/agyscope/config.toml`), or the file named by `AGYSCOPE_CONFIG`;
136
+ 3. the defaults.
137
+
138
+ > **Migrating from 0.2.0:** config.json is no longer read; convert it to config.toml.
139
+ > If `config.json` sits next to a missing `config.toml`, agyscope warns on the status line
140
+ > and starts with the defaults.
141
+
142
+ | Setting | Default | Description |
143
+ |---|---|---|
144
+ | `app_dir` | `"~/.gemini/antigravity-cli"` | Fallback data directory of the agent. It holds `brain/<conversation>/…/transcript.jsonl` and `presence/`. |
145
+ | `keymap` | `"emacs"` | Key preset: `"emacs"` or `"vim"`. |
146
+ | `keys` | `{}` | Extra keys per action, added to the preset, e.g. `keys = { down = ["J"], close = "C-x" }`. |
147
+ | `pager` | `["less", "-R", "+G"]` | Pager argv for the pager action. The file path replaces a `{file}` argument, or is appended. |
148
+ | `theme` | `"textual-dark"` | Theme name (Textual built-in or a file in `~/.config/agyscope/themes/`). |
149
+ | `marquee` | `true` | Horizontally scroll the highlighted row's **Last step** cell when it overflows. |
150
+ | `columns` | `{role = 24, state = 8, model = 22, age = 5}` | Initial list column widths in cells (`role` 8–80, `state` 4–20, `model` 6–60, `age` 3–10). |
151
+
152
+ The data directory is usually found without `app_dir`: from the presence lock the agent
153
+ process holds open (`--pid`), or from the transcript path the Rex hook records. Those
154
+ win over `app_dir`, which is only used when neither is available, for example with
155
+ `--conversation`.
156
+
157
+ The same file also holds the [Rex hook settings](#hook-settings) (`bounds`,
158
+ `auto_open`, `interactive`, `command`); agyscope itself ignores them.
159
+
160
+ An invalid value shows a warning on the bottom line (with `--once`/`--view`, on stderr),
161
+ and agyscope uses the default for that setting. A config mistake never stops it from
162
+ starting.
163
+
164
+ See [examples/config.toml](https://github.com/daehyeok/agyscope/blob/main/examples/config.toml) for a commented template with every
165
+ setting. Example `~/.config/agyscope/config.toml`:
166
+
167
+ ```toml
168
+ keymap = "emacs"
169
+ pager = ["bat", "--paging=always", "--style=plain"]
170
+ theme = "catppuccin-mocha"
171
+
172
+ [keys]
173
+ down = ["J"]
174
+ up = ["K"]
175
+
176
+ [columns]
177
+ role = 28
178
+ ```
179
+
180
+ ## Themes
181
+
182
+ Set `theme = "<name>"` in `config.toml` or pass `--theme <name>`. Built-in Textual themes
183
+ include `textual-dark`, `textual-light`, `nord`, `gruvbox`, `dracula`, `tokyo-night`,
184
+ `monokai`, `flexoki`, `solarized-light`, `solarized-dark`, `rose-pine`, `rose-pine-moon`,
185
+ `rose-pine-dawn`, `atom-one-dark`, `atom-one-light`, `catppuccin-mocha`,
186
+ `catppuccin-latte`, `catppuccin-frappe`, `catppuccin-macchiato`, `ansi-dark`, and
187
+ `ansi-light`.
188
+
189
+ User themes live in `~/.config/agyscope/themes/*.toml` (or `themes/` beside
190
+ `AGYSCOPE_CONFIG`). Each file defines a Textual theme: `primary` is required, `name`
191
+ defaults to the file stem, and any of `secondary`, `warning`, `error`, `success`,
192
+ `accent`, `foreground`, `background`, `surface`, `panel`, `boost`, `dark`,
193
+ `luminosity_spread`, `text_alpha`, `ansi`, and `[variables]` are accepted. A user theme
194
+ with the same name as a built-in replaces it. Invalid theme files warn and are skipped.
195
+
196
+ Subagent state colors follow the active theme (`working`/`running` → `$warning`,
197
+ `done` → `$success`, `error`/`failed`/`warn` → `$error`, `waiting` → `$primary`,
198
+ `msg`/`cmd` → `$accent`, `quiet`/`dim` → `$text-muted`). Any state or step style can be
199
+ overridden in `[variables]` with `agyscope-<state>` (such as `agyscope-waiting`).
200
+
201
+ To use the shipped Catppuccin Mocha palette and state colors
202
+ ([examples/themes/catppuccin-mocha.toml](https://github.com/daehyeok/agyscope/blob/main/examples/themes/catppuccin-mocha.toml)):
203
+
204
+ ```sh
205
+ mkdir -p ~/.config/agyscope/themes
206
+ curl -fsSL https://raw.githubusercontent.com/daehyeok/agyscope/main/examples/themes/catppuccin-mocha.toml \
207
+ -o ~/.config/agyscope/themes/catppuccin-mocha.toml
208
+ ```
209
+
210
+ Then set `theme = "catppuccin-mocha"` in `~/.config/agyscope/config.toml`.
211
+
212
+ ## Keys
213
+
214
+ agyscope is read-only, and keys not listed here do nothing. Keys in the "always" column
215
+ work in every preset. On the list screen, clicking a subtree's `▶`/`▼` icon folds or
216
+ unfolds it. On the view screen, the mouse wheel scrolls steps freely line-by-line, and
217
+ clicking an item's header toggles its fold.
218
+
219
+ | Action | Always | emacs (default) | vim |
220
+ |---|---|---|---|
221
+ | `up` / `down` | Up / Down | `C-p` / `C-n` | `k` / `j` |
222
+ | `page_up` / `page_down` | PgUp / PgDn | `M-v` / `C-v` | `C-u` `C-b` / `C-d` `C-f` |
223
+ | `first` / `last` (follow) | Home / End | `M-<` / `M->` | `g` / `G` |
224
+ | `open` (list: view subagent or fold group; view: fold/unfold) | Enter, Right | `Tab` | `Space` |
225
+ | `fold_all` | | `M-a` | `a` |
226
+ | `pager` (open full transcript in pager) | | `M-o`, `o` | `o` |
227
+ | `back` (view: return to list; list: collapse/parent) | Left, Esc | `C-g` | `Esc` |
228
+ | `close` (list: exit; view: return to list) | | `q` | `q` |
229
+
230
+ Note: Textual reports `Esc` followed by `<` or `>` as plain `<` and `>`, so `M-<` and
231
+ `M->` are bound to `<` and `>` as well (either key works). In the view screen, `q`
232
+ (`close`) returns to the list just like `back`; in the list screen, `q` exits agyscope
233
+ (in a Rex pane it also focuses the agent pane). `C-c` and `C-q` exit from either screen
234
+ without returning focus to the agent pane.
235
+
236
+ Key names for `keys` are single characters (`J`, `<`), `C-x` for Control, `M-x` for
237
+ Meta/Alt, and `Up Down Left Right PgUp PgDn Home End Enter Esc Tab Space`.
238
+
239
+ ## Two screens: Subagent list and step view
240
+
241
+ **List screen.** Subagents are shown newest first, with nested subagents indented. A
242
+ whole tree is under **Working** while any member is `working`, `waiting` or `quiet`, and
243
+ under **Completed** otherwise. These are the states:
244
+
245
+ | State | Meaning |
246
+ |---|---|
247
+ | `working` | running |
248
+ | `waiting` | ended its turn after starting background work (a background command or a subagent) that hasn't reported back |
249
+ | `done` | ended its turn |
250
+ | `quiet` | not finished, and its transcript hasn't changed for 5 minutes |
251
+ | `error` | its last step failed or is an error message (a failed tool call alone is not an error) |
252
+
253
+ **Columns.** The list formats each subagent row into aligned columns:
254
+
255
+ - **Subagent** (24 cells from the tree's left edge, including tree guides and the fold
256
+ icon): long roles end in `…` so the remaining columns line up at every depth.
257
+ - **State** (8 cells, colored).
258
+ - **Model** (22 cells, ending in `…` if longer).
259
+ - **Age** (5 cells, right-aligned).
260
+ - **Last step** (remaining width, ending in `…` if longer).
261
+
262
+ When the window is narrower than 73 columns (with default widths), **Last step** is
263
+ dropped and **Model** shrinks to fit (down to 8 cells). Below 48 columns, **Model** is
264
+ dropped too; the full model name is always shown in the view screen's header. Group rows
265
+ (`Working` and `Completed`) show only the group name.
266
+
267
+ Initial widths can be set under `[columns]` in `config.toml`. You can also drag the
268
+ column header borders horizontally with the mouse to resize columns for the current
269
+ session (dragged widths are not saved back to the config file).
270
+
271
+ **Marquee.** When the highlighted row's **Last step** is wider than its cell, it pauses
272
+ for 1.5 s, scrolls sideways a cell at a time until the end is visible, pauses for 1.5 s,
273
+ and jumps back to the start. Set `marquee = false` (or pass `--no-marquee`) to disable it.
274
+
275
+ **View screen.** Shows the selected subagent's live steps full screen, grouped under
276
+ the message that started each turn:
277
+
278
+ ```
279
+ ▼ Message from parent
280
+ ▶ Analyzed BUILD #L1-674
281
+ ▼ * Running run tests
282
+ $ make test
283
+ ok pkg/a 0.12s
284
+ ▶ Reply: Plan written.
285
+ ```
286
+
287
+ Steps fold and unfold independently. Running steps are unfolded, and background commands
288
+ stream their logs live. Scrolling is line-granular: mouse wheel, page keys, or line scrolls
289
+ move through long outputs freely. When following (`⏬ follow`), new steps scroll into view
290
+ automatically; scrolling up pauses follow (`⏸ paused`), and `last` (or `End` / `G` / `M->`)
291
+ resumes following. The pager action opens the whole view, fully unfolded, in your pager.
292
+
293
+ **Navigation and preserved state.** Both screens refresh every second. On the list
294
+ screen, `open` (`Enter`, `Right`, emacs `Tab`, vim `Space`) opens the selected subagent's
295
+ view—including parent subagents that have children—or folds/unfolds a group row.
296
+ Subtrees can be folded by clicking their `▶`/`▼` icon or with `fold_all` (`M-a` / `a`),
297
+ and `back` collapses an expanded subtree or moves to its parent. The list keeps its
298
+ cursor and folds while a view is open, and each subagent remembers its own scroll
299
+ position, folds, and follow state across reopens (opening a subagent for the first time
300
+ starts in follow mode). If the subagent being viewed disappears (for example, when the
301
+ conversation switches), agyscope returns to the list automatically.
302
+
303
+ ## Rex integration
304
+
305
+ For agents running in Rex terminal panes, the repository is also a Rex
306
+ plugin. It opens agyscope in a floating pane in the agent pane's window:
307
+
308
+ ```
309
+ your key --> action "agyscope" (Rex config, Lua)
310
+ |
311
+ +-- panel in this window? minimized -> restore and focus
312
+ | visible -> minimize
313
+ +-- no panel: find the agent process in the focused pane
314
+ none -> small message pane "No agent in this pane"
315
+ found -> open a floating pane ON THE PANE'S HOST running
316
+ agyscope --pid <pid> --rex-block <pane>
317
+
318
+ agyscope-rex-hook (optional, PostToolUse on invoke_subagent)
319
+ records the pane's root conversation and opens the same panel without focus
320
+ when the first subagent starts; the data directory comes from the payload's
321
+ transcript path
322
+ ```
323
+
324
+ `--rex-block` makes agyscope fall back to the conversation the hook recorded for that
325
+ pane, and return focus to the agent pane after `close` (`q`). Without it agyscope loads
326
+ no Rex code.
327
+
328
+ Remote panes are supported: the panel runs on the host where the agent runs and reads
329
+ that host's transcripts. [Install](#install) `agyscope` (`uv tool install agyscope`) on
330
+ every host whose panes run the agent—that provides both the `agyscope` and
331
+ `agyscope-rex-hook` Python commands. Rex itself only needs the Lua plugin.
332
+
333
+ ### Lua plugin (Rex client)
334
+
335
+ Requires Rex with Lua config (`init.lua`). Clone the repository into your Rex config
336
+ directory (the clone only provides the Lua plugin; `agyscope` and `agyscope-rex-hook`
337
+ come from the PyPI [install](#install)):
338
+
339
+ ```sh
340
+ git clone https://github.com/daehyeok/agyscope ~/.config/rex/plugins/agyscope
341
+ ```
342
+
343
+ Load it from `~/.config/rex/init.lua` and bind any key you like. The plugin binds
344
+ none itself:
345
+
346
+ ```lua
347
+ require("plugins.agyscope").setup{}
348
+
349
+ rex.bind("alt+s", "agyscope") -- a single key
350
+ -- rex.bind("ctrl+b>a>s", "agyscope") -- or a prefix-style sequence
351
+ ```
352
+
353
+ If your config doesn't search `~/.config/rex/?/init.lua`, add the plugin's `lua/`
354
+ directory to `package.path` yourself and use `require("agyscope").setup{}`:
355
+
356
+ ```lua
357
+ local dir = os.getenv("HOME") .. "/.config/rex/plugins/agyscope/lua/"
358
+ package.path = dir .. "?.lua;" .. dir .. "?/init.lua;" .. package.path
359
+ require("agyscope").setup{}
360
+ ```
361
+
362
+ Check the config with `rex config check`, then reload it with `rex config reload`.
363
+
364
+ `setup(opts)` accepts these options. Unknown options and wrong types raise an error
365
+ that `rex config check` reports.
366
+
367
+ | Option | Default | Description |
368
+ |---|---|---|
369
+ | `action` | `"agyscope"` | Name of the registered action; bind your key to it. |
370
+ | `title` | `"Show/Hide Agent Subagent Panel"` | Title in Rex's action palette. |
371
+ | `agent_apps` | `{ "agy", "antigravity" }` | Program names that count as the agent. They are matched against Rex's program status, then the pane's foreground process name, path or `argv0`. |
372
+ | `command` | `{ "agyscope" }` | Panel command on the pane's host, as an argv list. It is looked up on `PATH` plus `~/.local/bin`; a leading `~/` is expanded on that host. |
373
+ | `bounds` | `{ 0.6, 0.04, 0.38, 0.42 }` | Panel position and size `{ x, y, w, h }`, as fractions of the window (top-right). |
374
+ | `panel` | `{}` | agyscope settings passed as flags: `app_dir`, `keymap`, `keys`, `pager` (see [Configuration](#configuration)). They override the host's config file for panels this action opens. `theme`, `marquee`, and `columns` are set only in `config.toml` (not via `panel`). |
375
+ | `interactive` | `true` | Run the panel through your shell with its interactive startup files (`~/.zshrc`, `~/.bashrc`), so it finds what your terminals find. See [The panel's PATH](#the-panels-path). |
376
+
377
+ Example:
378
+
379
+ ```lua
380
+ require("plugins.agyscope").setup{
381
+ bounds = { 0.55, 0.05, 0.43, 0.5 },
382
+ panel = { keymap = "vim", pager = { "bat", "--paging=always", "--style=plain" } },
383
+ }
384
+ ```
385
+
386
+ ### The hook (optional, each host that runs the agent)
387
+
388
+ `agyscope-rex-hook` is installed alongside `agyscope` by `uv tool install agyscope`. It
389
+ needs an agent CLI version that runs `PostToolUse` hooks from `~/.gemini/config/hooks.json`;
390
+ the key binding works without it. Merge
391
+ [integrations/rex/hooks.json](https://github.com/daehyeok/agyscope/blob/main/integrations/rex/hooks.json)
392
+ into `~/.gemini/config/hooks.json`:
393
+
394
+ ```json
395
+ {
396
+ "agyscope": {
397
+ "PostToolUse": [
398
+ { "matcher": "invoke_subagent",
399
+ "hooks": [ { "type": "command", "command": "~/.local/bin/agyscope-rex-hook", "timeout": 5 } ] }
400
+ ]
401
+ }
402
+ }
403
+ ```
404
+
405
+ The hook always answers `{}` at once and exits 0. It never changes or delays the
406
+ agent. Outside Rex it does nothing.
407
+
408
+ ### Hook settings
409
+
410
+ The hook reads these from the same config file as agyscope
411
+ (`~/.config/agyscope/config.toml`, or `AGYSCOPE_CONFIG`):
412
+
413
+ | Setting | Default | Description |
414
+ |---|---|---|
415
+ | `bounds` | `[0.6, 0.04, 0.38, 0.42]` | Panel position and size for panels the hook opens. |
416
+ | `auto_open` | `true` | Whether the hook opens the panel on the first subagent. |
417
+ | `interactive` | `true` | Whether panels the hook opens run through your shell with its interactive startup files. See [The panel's PATH](#the-panels-path). |
418
+ | `command` | `["agyscope"]` | Panel command (argv list). A bare name is resolved next to the hook's own executable when it exists there, so the default works without `PATH`. |
419
+
420
+ Because the settings live in one file per host, panels opened by the hook and by the
421
+ key look the same.
422
+
423
+ ### The panel's PATH
424
+
425
+ Rex starts the panel through your login shell on the pane's host. By default
426
+ (`interactive` is true for both the plugin and the hook) that shell also reads its
427
+ interactive startup files, such as `~/.zshrc`, so the panel sees the same `PATH` as
428
+ your terminals. The plugin also looks in `~/.local/bin`, where `uv tool install` puts
429
+ `agyscope`; it never guesses other install directories.
430
+
431
+ If your rc files are slow, print output or ask questions, set `interactive = false`
432
+ in `setup{}` and `interactive = false` in `config.toml`. Then make sure `agyscope`
433
+ is on the login `PATH` or in `~/.local/bin`, or set `command` to its full path.
434
+
435
+ ## Limits
436
+
437
+ - The process-to-conversation lookup relies on the agent holding
438
+ `<data dir>/presence/<conversation>.lock` open, and on reading the process's open
439
+ files (`lsof`, or `/proc` on Linux; both only see your own processes). In Rex, if that
440
+ fails, the panel falls back to the conversation the hook last recorded for the pane,
441
+ so the hook becomes necessary.
442
+ - The agent runs the hook for every `invoke_subagent`, including those a subagent
443
+ makes. Without a `rootConversationId` in the payload, the hook records a conversation
444
+ only when it holds a presence lock, which only root conversations do. If the payload
445
+ has no transcript path either, the hook can't check and records `conversationId`.
446
+ - A panel opened by the hook follows the conversation the hook last recorded for that
447
+ pane. A panel opened by the key follows the agent process.
448
+ - Only transcripts in the Antigravity format are understood. Unknown steps are
449
+ skipped.
450
+
451
+ ## Development
452
+
453
+ ```sh
454
+ uv run --python 3.13 pytest # Python tests (pytest, including the Textual UI)
455
+ sh tests/run_all.sh # all tests: Python (via uv) and Lua
456
+ sh tests/run_all.sh py # Python tests only
457
+ sh tests/run_all.sh lua # Lua tests only
458
+ pre-commit install # optional: lint and test on every commit
459
+ ```
460
+
461
+ `uv.lock` is not committed: uv resolves from your own index and keeps a local lock.
462
+ Fixtures are synthetic; `uv run python tests/py/fixtures/make_fixtures.py` regenerates
463
+ `tests/py/fixtures/app/`.
464
+
465
+ The [pre-commit](https://pre-commit.com) hooks check whitespace and YAML, run shellcheck and the
466
+ [StyLua](https://github.com/JohnnyMorganz/StyLua) format check (`stylua --check .`; fix with `stylua .`)
467
+ when they're installed, and run the tests. CI runs the Python tests with uv on Python 3.11,
468
+ 3.13 and the latest 3.x, the Lua tests, and the same hooks with both tools required.
469
+
470
+ `tests/lua/manual_toggle.lua` runs the Rex action for a given pane
471
+ (`AGY_BLOCK=… AGY_SESSION=… rex do tests/lua/manual_toggle.lua`).
472
+
473
+ ## Disclaimer
474
+
475
+ This is an independent, unofficial project. It is not affiliated with, endorsed by,
476
+ or supported by Google LLC or the makers of Rex. It reads files the agent CLI writes
477
+ for its own use; those formats are undocumented and may change without notice, which
478
+ can break agyscope at any time. Use it at your own risk.
479
+
480
+ ## Trademarks
481
+
482
+ Antigravity, Gemini and Google are trademarks of Google LLC. Rex is a trademark of
483
+ its respective owner. Other names may be trademarks of their respective owners. They
484
+ are used here only to describe what this software works with; no endorsement is
485
+ implied.
486
+
487
+ ## License
488
+
489
+ MIT, see [LICENSE](https://github.com/daehyeok/agyscope/blob/main/LICENSE).