Metadata-Version: 2.4
Name: adash-cli
Version: 0.1.0
Summary: htop-style monitor for Claude Code and Codex CLI agent sessions
Author: Anthony Maio
License: MIT
Project-URL: Homepage, https://github.com/anthony-maio/adash
Project-URL: Repository, https://github.com/anthony-maio/adash
Project-URL: Issues, https://github.com/anthony-maio/adash/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.60
Requires-Dist: psutil>=5.9
Requires-Dist: rich>=14
Provides-Extra: dev
Requires-Dist: pytest>=9; extra == "dev"
Dynamic: license-file

# adash

**AI agent monitor for Claude Code and Codex CLI** — a local-first triage dashboard for session health, cost, and utility.

Inspired by and data format compatible with [graykode/abtop](https://github.com/graykode/abtop) (MIT).
adash is a cleaner Python rewrite using [Textual](https://textual.textualize.io/) rather than a btop pastiche.

A sibling to [mnemos](https://github.com/anthonymaio/mnemos), [pulldown](https://github.com/anthonymaio/pulldown), [cartograph](https://github.com/anthonymaio/cartograph), and [synthesis](https://github.com/anthonymaio/synthesis).

---

## What it shows

- Summary strip: active sessions, attention count, live burn/hour, today estimate, hottest context/quota, orphan count
- Ranked attention queue: title, project, model, ctx %, token total, estimated cost, burn/hour, age
- Inspector: overview, token/cost breakdown, recent trend, alerts, ports/subagents, and safe actions
- JSON snapshot output with raw sessions plus derived summary, alerts, and insights

## Install

```bash
pipx install adash-cli
# or
pip install adash-cli
```

For local development and test runs:

```bash
pip install -e ".[dev]"
python -m pytest -q
```

If you want the latest repo state before a PyPI release lands:

```bash
pipx install git+https://github.com/anthony-maio/adash.git
```

## Usage

```
adash              # TUI (default)
adash --once       # Snapshot table to stdout, exit
adash --json       # JSON snapshot to stdout, exit
adash --setup      # Print Claude StatusLine hook setup instructions
adash --version    # Print version
```

## Keybindings

| Key | Action |
|-----|--------|
| `↑` / `↓` or `j` / `k` | Select session |
| `enter` | Copy session ID to clipboard |
| `o` | Open selected session cwd |
| `t` | Open selected transcript |
| `x` | Kill selected session (SIGTERM) |
| `X` | Kill all orphan port processes |
| `f` | Toggle all vs risky sessions |
| `s` | Cycle sort mode (severity, cost, recency) |
| `r` | Force refresh |
| `q` | Quit |

## Claude rate limit hook setup

adash reads `~/.claude/adash-rate-limits.json` (also reads legacy `~/.claude/abtop-rate-limits.json` for back-compat) for Claude quota data. This file is written by a shell hook you add to your Claude Code setup.

Run `adash --setup` to print the hook snippet. Add the function to your shell and configure it via Claude Code's `hooks` setting in `~/.claude/settings.json`.

## Codex rate limit data

Codex rate limit data is extracted directly from the session JSONL files that Codex writes during its `token_count` events. No hook needed — just run Codex normally and adash picks it up.

Rate limit cache is stored at `~/.cache/adash/codex-rate-limits.json`.

## Pricing overrides

adash includes built-in approximate pricing rules for common Claude and GPT-5 model families. To override them locally, create:

- `$ADASH_PRICING_FILE`, or
- `~/.config/adash/pricing.json`

File shape:

```json
{
  "models": [
    {
      "pattern": "claude-sonnet-4*",
      "agent_cli": "claude",
      "input_per_million": 3.0,
      "output_per_million": 15.0,
      "cache_read_per_million": 0.3,
      "cache_write_per_million": 3.75
    }
  ]
}
```

Estimated USD values are intentionally approximate and secondary to token/quota signals.

## Data compatibility

adash reads the same session files as abtop:
- Claude sessions: `~/.claude/sessions/*.json` + transcripts in `~/.claude/projects/`
- Codex sessions: `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`

The transcript encoding rule (Claude): `/`, `_`, `.` → `-`.

## Attribution

Inspired by [graykode/abtop](https://github.com/graykode/abtop) (MIT License).
Data format, JSONL parsing logic, and session discovery strategy are derived from abtop.

## License

MIT — see [LICENSE](LICENSE).

## Development

- CI runs the test suite on Linux and Windows to keep the collector and path-handling logic portable.
- `adash --json` now returns structured JSON errors with a non-zero exit code when collection fails, which makes automation safer than relying on a traceback.
