agent-timelines 0.2.0__py3-none-any.whl

agent_timelines-0.2.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: agent-timelines
+Version: 0.2.0
+Summary: Live delegation graph of Claude Code sessions and their subagents
+Author: jasondasuki
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jasondasuki/agent-timelines
+Project-URL: Source, https://github.com/jasondasuki/agent-timelines
+Project-URL: Issues, https://github.com/jasondasuki/agent-timelines/issues
+Keywords: claude-code,claude,agents,subagents,dashboard,observability,pixel-art
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: src/agent_timelines/assets/LICENSES.txt
+Dynamic: license-file
+
+# agent-timelines
+
+[![CI](https://github.com/jasondasuki/agent-timelines/actions/workflows/ci.yml/badge.svg)](https://github.com/jasondasuki/agent-timelines/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jasondasuki/agent-timelines/blob/main/LICENSE)
+
+A pixel-art dashboard for Claude Code sessions. It shows which agent spawned which, the model and effort
+requested vs. what actually ran, tool calls, weighted token cost and dollars, handoffs and Workflow runs, live while the
+session works. Everything is read from your local transcripts; nothing leaves your machine.
+
+![Chart view: the delegation tree as a party of heroes, with one hero's detail panel open](https://raw.githubusercontent.com/jasondasuki/agent-timelines/main/docs/chart.jpg)
+
+- **Lobby**: your 200 most recent sessions as a retro game-server list (live dungeons + hall of records), with search, a project filter and
+  paging (`/` focuses the search box, left/right change the page).
+- **Chart view**: the delegation tree as a party of heroes, with flags for rule breaks (no model set,
+  model mismatch, ignored tool limit, unanswered handoff, …).
+  Each card shows the agent's top tools and the start of its final reply; the detail panel lists every tool and the full report
+  (a running agent shows what it is saying now).
+- **Timeline view**: one bar per agent on a shared clock, rows in party-tree order, so you can see who ran when and what overlapped.
+  Running agents get a striped bar; zoom with + and -.
+- **Map view**: the same session as a procedurally generated dungeon. The main session is the guild master
+  in the guild hall; each agent has its own room and fights an enemy while it works, then celebrates.
+
+![Lobby: live dungeons and the hall of records](https://raw.githubusercontent.com/jasondasuki/agent-timelines/main/docs/lobby.jpg)
+![Map view: a procedurally generated dungeon with one room per agent](https://raw.githubusercontent.com/jasondasuki/agent-timelines/main/docs/map.jpg)
+
+(The screenshots show a synthetic demo session.)
+
+## Install
+
+Needs Python 3.9+ on macOS or Linux (Windows is not supported). No other dependencies. Use one of the two options, not both.
+
+**Option A: the command-line tool from PyPI** (needs [uv](https://docs.astral.sh/uv/) or pipx)
+
+```sh
+uv tool install agent-timelines   # or: pipx install agent-timelines
+agent-timelines install    # adds 6 hooks to ~/.claude/settings.json (writes a backup next to it first)
+agent-timelines rebuild    # optional: fills the lobby with your sessions from the last 30 days
+agent-timelines serve      # opens http://127.0.0.1:8765/index.html (localhost only)
+```
+
+**Option B: the Claude Code plugin** (no pip, no settings.json edit; the hooks come with the plugin)
+
+```sh
+claude plugin marketplace add jasondasuki/agent-timelines
+claude plugin install agent-timelines@agent-timelines
+```
+
+Then ask for the dashboard with `/agent-timelines:dashboard`. The plugin's hooks run `python3` from your PATH, so Python 3.9+ must be there.
+If `agent-timelines install` hooks are also in settings.json, the plugin's hooks stay quiet so nothing is built twice.
+
+Start or continue a Claude Code session; it appears in the lobby on its first hook event.
+
+| Command | What it does |
+|---|---|
+| `install [--settings PATH]` | Add the hooks (replaces earlier agent-timelines hooks, keeps all others). |
+| `uninstall [--settings PATH]` | Remove the hooks. Your data folder stays. |
+| `serve [--port N] [--no-browser]` | Serve the dashboard on 127.0.0.1. |
+| `open [SESSION-PREFIX]` | Build one session (newest by default) and open it from disk, no server. |
+| `rebuild [--days N]` | Regenerate data for recent sessions from their transcripts. |
+| `list` | Recent sessions with their subagent counts. |
+
+`--settings` targets another Claude config dir, e.g. `--settings ~/.claude-work/settings.json`.
+`CLAUDE_CONFIG_DIR` is respected for the default paths.
+
+Data lives in `~/.claude/agent-timelines/` (one `<session>.data.js` and one `<session>.prompts.js` per session, removed after 30 days untouched).
+The pages hold prompt text from your sessions, which is why `serve` binds to localhost only and refuses requests that come from other sites (wrong `Host`, or a cross-site script or fetch).
+
+## Config (optional)
+
+`~/.config/agent-timelines/config.json` (or `$AGENT_TIMELINES_CONFIG`). Every key is optional:
+
+```json
+{
+  "out_dir": "~/.claude/agent-timelines",
+  "ctx_limit": 200000,
+  "tool_limit": 50,
+  "brief_limit": 8000,
+  "retain_days": 30,
+  "lobby_limit": 200,
+  "handover_dir": "~/.claude/handovers",
+  "agents_dir": "~/.claude/agents",
+  "guard_text": "Main session does not execute",
+  "tiers": {"Explore": "scanner", "Plan": "plan", "general-purpose": "executor"},
+  "rules": {"no-model": true, "no-effort": true},
+  "prices": {"gpt-6": {"in": 1, "out": 2}}
+}
+```
+
+`tool_limit` is unset by default, so there are no hearts, only a tool count; set it to the number your hand-off hook uses.
+`brief_limit`, `guard_text` and `handover_dir` match optional hand-off and guard hooks of your own;
+without such hooks those flags never fire. `tiers` maps agent types to character classes.
+`rules` turns single flags on or off by name; a flag you do not list keeps its default. `no-model` and `no-effort` are off by default;
+turn them on if your setup requires every spawn to name a model and effort. The flag names are `no-model`, `no-effort`, `auto-filled`,
+`frontmatter`, `model-mismatch`, `effort-mismatch`, `ctx` (the context-size flag), `handoff`, `tool-limit`, `ignored-limit`, `orphan`
+and `handoff-not-continued`; an unknown name is an error.
+
+`prices` adds or changes entries of the built-in price table (USD per million tokens; the table is dated, see `PRICES_ASOF` in `timeline.py`).
+The key is a model id prefix without `claude-`, the longest matching key wins, and the columns are `in`, `cc5` (5-minute cache write),
+`cc1` (1-hour cache write), `cr` (cache read), `out` and an optional `over` (`[prompt tokens, multiplier]`); a missing column counts as 0.
+Entries are merged per model, so you only list what you add or change. A model with no price is shown as unpriced (`$0.00+` on its card),
+never guessed.
+
+### Cost
+
+Cost is computed per message from the full model id and the usage recorded in the transcript, at Anthropic first-party API list prices
+([pricing page](https://platform.claude.com/docs/en/about-claude/pricing), table dated 2026-11-10). It is what those tokens would cost through the
+API; a subscription plan is not billed per token. Not modelled: the 1.1x US-only `inference_geo` surcharge (the transcript does not say whether it
+applied), batch discounts, Bedrock and Vertex prices, web-search and other server-tool fees. Gold is the same tokens weighted by cost, as before.
+
+## Development
+
+```sh
+python3 tests/test_timeline.py && python3 tests/test_cli.py   # Python
+node tests/test_dungeon.js && node tests/test_actors.js && node tests/test_lobby.js && node tests/test_gantt.js   # viewer scripts (Node 18+)
+open dev/dungeon-demo.html                                     # dungeon playground: agents, working, reset
+```
+
+## Credits
+
+- Sprites: [Kenney](https://www.kenney.nl) "Tiny Dungeon" and "1-Bit Pack", CC0.
+- Font: Press Start 2P by CodeMan38, SIL Open Font License 1.1.
+
+Details in `src/agent_timelines/assets/LICENSES.txt`.
+
+## License
+
+MIT, see [LICENSE](https://github.com/jasondasuki/agent-timelines/blob/main/LICENSE). Contributions welcome: see [CONTRIBUTING.md](https://github.com/jasondasuki/agent-timelines/blob/main/CONTRIBUTING.md). Security reports: [SECURITY.md](https://github.com/jasondasuki/agent-timelines/blob/main/SECURITY.md).

agent_timelines-0.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+agent_timelines/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_timelines/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+agent_timelines/actors.js,sha256=vzlvvAFU2X-YAGIpMUrvQIQLm9d3fXTZTD4buk6E5Io,12264
+agent_timelines/cli.py,sha256=hPj9pSOaQ9AO3bMzFsPIIRQJP_rG06qT06-f7WUWgfg,9586
+agent_timelines/dungeon.js,sha256=sKQNcYq34ei3qpDQPFQq39hCtgDC7mvdXV1o0IJIB5M,12520
+agent_timelines/gantt.js,sha256=MikACV4fPA5q2wkE0jsscm5VePLdJFltZqgHGd3wYOM,3689
+agent_timelines/lobby.js,sha256=Q6PweYBbQzkBG2obvn5m55hcIvby7teBqwRLc81oNVE,2426
+agent_timelines/timeline.py,sha256=VUVVoRcqQPbO-DquiEoUe1sucZygyTXK6GbGTElO8fI,34919
+agent_timelines/viewer.html,sha256=rQDYVbhJvDjvP8irIJ_TQQK-9AkVqFlTXsLN0XZSKVs,52156
+agent_timelines/assets/LICENSES.txt,sha256=H5CEDrbMPZDQqy_bIArZsH2OiEqI7mR-SVZZJ5iEx8g,4840
+agent_timelines/assets/PressStart2P-Regular.ttf,sha256=A0x38fBeyJQh5KY_DjpMoez4UsxtK_YR8SbydXKOAX0,118204
+agent_timelines/assets/one-bit.png,sha256=V4jwqdZUnGuzRwqVOOvs90tflKa4Wttd227W0lRIUiA,22927
+agent_timelines/assets/tiny-dungeon.png,sha256=0k5gpB5Kx6dFwDBN_eEhFDaIVX9AIV8jIhwpz-aDgl8,5294
+agent_timelines-0.2.0.dist-info/licenses/LICENSE,sha256=5PexdM_uPCCd4H9o75lr4ZVoo76-Jf3K1o0pJCeI5MU,1185
+agent_timelines-0.2.0.dist-info/licenses/src/agent_timelines/assets/LICENSES.txt,sha256=H5CEDrbMPZDQqy_bIArZsH2OiEqI7mR-SVZZJ5iEx8g,4840
+agent_timelines-0.2.0.dist-info/METADATA,sha256=C5huIyc40mIMCNY87UO18bYmCyikZjDNWJfJARl2_bo,8859
+agent_timelines-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+agent_timelines-0.2.0.dist-info/entry_points.txt,sha256=rSO9x3YWtgDzy-Dd5MHOxLkCIty08NkBW8kw-NkxVbQ,61
+agent_timelines-0.2.0.dist-info/top_level.txt,sha256=FXiuVJ4xhuD50j6flgk8iOOKvWdafikTpJBMMUFnV5Q,16
+agent_timelines-0.2.0.dist-info/RECORD,,

agent_timelines-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_timelines-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-timelines = agent_timelines.cli:main

agent_timelines-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 jasondasuki
+
+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.
+
+Bundled third-party assets (sprites and font) keep their own licenses:
+see src/agent_timelines/assets/LICENSES.txt.

agent_timelines-0.2.0.dist-info/licenses/src/agent_timelines/assets/LICENSES.txt

@@ -0,0 +1,98 @@
+tiny-dungeon.png  Kenney "Tiny Dungeon" 1.0 (www.kenney.nl), CC0 1.0. Source: https://opengameart.org/content/tiny-dungeon
+one-bit.png       Kenney "1-Bit Pack" 1.1 (www.kenney.nl), CC0 1.0. Source: https://opengameart.org/content/1-bit-pack
+PressStart2P-Regular.ttf  Copyright 2012 The Press Start 2P Project Authors, SIL Open Font License 1.1 (text below).
+Source: https://github.com/google/fonts/tree/main/ofl/pressstart2p
+
+Copyright 2012 The Press Start 2P Project Authors (cody@zone38.net), with Reserved Font Name "Press Start 2P".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

agent_timelines-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_timelines