atv (async task viewer) is a Textual UI for discovering Python processes, inspecting asyncio tasks and await trees, comparing snapshots, and capturing Tachyon flame graphs.
cd atv
uv syncuv sync installs the specified dependencies (textual, psutil) into your local environment.
uv run atvSelect a process in the left pane, then use:
| Key | Action |
|---|---|
R |
Refresh processes, keeping the selected PID when possible |
Enter / P |
Capture asyncio ps |
T |
Capture asyncio pstree |
S |
Save the last successful task/tree snapshot as text |
D |
Compare the last two captures of the same PID and view |
F |
Capture a Tachyon flame graph of running asyncio tasks |
G |
Capture a Tachyon flame graph including waiting tasks |
O |
Open the last successful flame graph in a browser |
X |
Cancel the current observation |
Q |
Exit |
Task snapshots show the state at capture time. Flame graphs aggregate samples
across a time window. Snapshot diffs are textual: task IDs, stack lines and
ordering changes may appear in the diff; this is not a task lifecycle tracker.
Capture twice with P or T before using D. Saved snapshots and profiles get unique
filenames under ~/.atv/captures; captures are never overwritten automatically.
Profiling requires an observer with profiling.sampling (Python 3.15+).
Task inspection remains available with Python 3.14. Choose an observer matching
the target Python minor version and standard/free-threaded build; pre-release
versions may require an exact version match.
uv run atv --python "$(uv python find 3.15)" --duration 10
uv run atv --output-dir ./captures--duration accepts 1–300 seconds. F and G attach only to the selected process;
X cancels the observer, not the target. atv does not invoke sudo automatically.
On macOS, process observation may require elevated privileges. Use the
Python permission guide
to configure your environment. Errors remain visible in the output pane.
When running atv under sudo, set --output-dir explicitly if desired; generated
files belong to that user and the browser may need to be opened manually.
uv run python -m unittest discover -s tests -vThe suite checks subprocess errors, cancellation/timeout cleanup, and headless UI interactions with mocked external inspection. It does not require attaching to other processes or elevated privileges.
Once released, you'll be able to launch it with a one-liner.
uvx atvIf you want to test uvx behavior during local development, run the following in the project root.
uvx --from . atv- Structured task navigation and lifecycle-aware snapshot comparison
- Periodic task inspection with an explicit refresh interval
- Integration with application-provided task information
This project is licensed under the MIT License. See LICENSE for details.