Metadata-Version: 2.5
Name: tartifacts
Version: 0.4.0
Summary: Live terminal artifacts — dashboards that stay open, stay fresh, and stay findable
Project-URL: Homepage, https://github.com/tg1482/tart
Project-URL: Source, https://github.com/tg1482/tart
Project-URL: Issues, https://github.com/tg1482/tart/issues
Project-URL: Changelog, https://github.com/tg1482/tart/blob/master/CHANGELOG.md
Author-email: Tanmay Gupta <tg1482@stern.nyu.edu>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,cli,dashboard,rich,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: User Interfaces
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# tart

Live terminal artifacts: dashboards that stay open, keep their own data
fresh, and can be found again by name.

![claude-swarm](examples/images/claude-swarm.png)

```bash
uv tool install tartifacts   # the command is `tart`
```

## An artifact is three files

```
spend.json     manifest: what runs it, what produces its data, when that data expires
fetch.py       writes JSON to tartifacts.data_path()
show.py        render(state, console) returns any rich renderable
```

```json
{
  "title": "Cloud spend",
  "run":   "$TART_PYTHON show.py",
  "data":  "data/spend.json",
  "fetch": "$TART_PYTHON fetch.py",
  "stale_after": "4h",
  "auto_refresh": true
}
```

`$TART_PYTHON` is tart's own interpreter — it already has `rich` and
`tartifacts`, so most artifacts need no uv environment of their own: one
~20 MB process instead of a resident `uv run` supervisor holding open a
second Python. Need more libraries? Any command works there, `uv run
--with pandas ...` included.

```python
from tartifacts import app, widgets

def render(state, console):
    return widgets.stack(
        widgets.header(f"{len(state['data']['rows'])} rows"),
        widgets.trend(state["data"]["daily"], style="green"),
    )

app.run(render=render)
```

`render()` can return any rich renderable. `tartifacts.widgets` adds the
few things rich lacks for a live dashboard: a scrolling cursor, sparklines,
height budgeting, key bindings. Use them or don't.

## Quick start

```bash
tart register path/to/spend.json
tart run spend                      # from any directory
```

Registering a manifest trusts it. One that tart finds by scanning needs
`tart trust <name>` first, and editing either asks again.

## CLI

```bash
tart list                    # what's declared, what's live
tart run <name>              # launch, fetching first if stale
tart render <name> [--json]  # one frame headless, or the numbers as JSON
tart fetch <name>            # re-run its data command
tart logs <name>             # the last fetch's outcome and output, even from cron
tart cron --sync             # standing cron block: auto_refresh artifacts stay fresh unattended
tart restart --all           # re-exec live artifacts in place — same pane, new code
tart register <path>         # adopt a manifest from anywhere
tart trust <name>            # approve a scanned manifest
tart roots add <path>        # a workspace to scan
tart --skill                 # full reference, written for agents
```

## Examples

Eight working artifacts in [`examples/`](examples/): local Claude Code
agents, ad spend, newsletters, open issues, battery, Wi-Fi, cron, disk.
Copy one, change the fetch.
