Metadata-Version: 2.4
Name: zeno-cli
Version: 1.0.1
Summary: Zeno CLI - measure the supervision cost of AI-assisted work
Project-URL: Homepage, https://zeno.center
Project-URL: Repository, https://github.com/Marwan01/zeno
Author-email: Mar Helali <mar@1dev.space>
License-Expression: Apache-2.0
Keywords: ai,claude-code,cognitive-load,rtlx-s,session-analytics,supervision
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: alembic>=1.13.2
Requires-Dist: keyring>=25.3.0
Requires-Dist: matplotlib>=3.9.2
Requires-Dist: numpy>=2.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: rich>=13.8.1
Requires-Dist: scipy>=1.14.1
Requires-Dist: textual>=0.86.1
Description-Content-Type: text/markdown

# zeno-cli

Measure the supervision cost of AI-assisted work, from your terminal. `zeno`
records RTLX-S load probes + session activity, fits your personal "babysitting
tax" curve, and surfaces where your optimal number of parallel agents sits.

## Install

`zeno-cli` is live on PyPI. It is one self-contained package: the SDK, core,
adapters, session-intelligence engine, and SQLite migrations all ship inside it.

```sh
uv tool install zeno-cli
```

Lead with `uv` - it ships its own Python, so this works on a stock Mac. `uv`
not installed? `curl -LsSf https://astral.sh/uv/install.sh | sh`. On Python
3.12+ you can also `pip install zeno-cli` or `pipx install zeno-cli`; the wheel
requires 3.12+, so bare `pip` fails on the 3.9 that ships with macOS. **Update**
with `uv tool upgrade zeno-cli` (or `pipx upgrade zeno-cli`).

### Install channels (staged)

The distribution channel widens as the audience does. Use the one that matches
where the project is, not the most convenient:

| Stage | Channel | Command | Status |
| :--- | :--- | :--- | :--- |
| Now | PyPI | `uv tool install zeno-cli` (or, on 3.12+, `pip install zeno-cli` / `pipx install zeno-cli`) | Live (v1.0.0) |
| Dev | monorepo / git+ssh | `uv run --project /path/to/zeno zeno` or `uv tool install --from "git+ssh://git@github.com/Marwan01/zeno.git@cli-v1.0.0#subdirectory=apps/cli" zeno-cli` | For contributors with repo SSH access |
| Later | Homebrew | `brew install zeno-cli` | Formula not written yet |

The PyPI publish is OIDC Trusted-Publishing gated and fires on a published
GitHub release - see `.github/workflows/publish.yml`.

**From a built wheel** (offline / air-gapped; the wheel is fully self-contained):

```sh
uv build --wheel --package zeno-cli          # -> dist/zeno_cli-*.whl
uv tool install ./dist/zeno_cli-1.0.0-py3-none-any.whl
```

**From source** (development inside the monorepo, no install):

```sh
uv run --project /path/to/zeno zeno <cmd>
```

New here? Follow `docs/ADOPT.md` for the 10-minute install -> capture -> survey loop.
Requires Python 3.12+ (or use `uv`, which brings its own).

## Use

```sh
zeno survey        # log how a session felt (~6s, RTLX-S 5-item probe)
zeno status        # tier, streak, tax curve, cognitive state, today's survey
zeno curve         # render the babysitting-tax curve (needs ~10 sessions of data)
zeno weekly        # 7-day rollup
zeno doctor        # health check: API reachability + identity
zeno login         # browser sign-in; stores a Clerk JWT in the OS keyring
zeno whoami        # show the identity + tier the API sees for your token
zeno logout        # clear the stored token
```

### Authentication

`zeno login` runs a browser + loopback sign-in and stores the resulting Clerk
JWT in your OS keyring; the CLI sends it as a `Bearer` token so the API
attributes requests to your user. Token resolution order, used by every
command: `ZENO_API_TOKEN` env override first, then the keyring token from
`zeno login`, then none (local-only). Use `zeno login --no-browser` for SSH /
headless (prints the URL), and `--authorize-url` / `ZENO_LOGIN_AUTHORIZE_URL`
to target a non-default bridge.

> The dashboard `/cli/authorize` bridge page is shipped: it requires Clerk
> sign-in, mints a `zeno-api`-audience JWT, and redirects back to the CLI's
> loopback callback (validating the CSRF `state`, refusing any non-loopback
> target). See `src/zeno_cli/login.py` for the callback contract.

Full daily-loop guide: `docs/CLI_QUICKSTART.md`.

## Cognition HUD add-on

`zeno-hud-bar` is the single differentiated cognition line (`att / eff / drv`) that
stacks UNDER whatever popular HUD you already run, instead of replacing it. Claude Code
has one statusLine slot, so zeno rides the HUD you have:

```sh
zeno hud install            # auto-detect: ccstatusline (native widget) or claude-hud (wrapper)
zeno hud install --dry-run  # print what would change, write nothing
zeno hud status             # what is detected + whether the line is wired in
zeno hud uninstall          # remove from both adapters (idempotent; --restore for byte-for-byte)
```

`--target {auto,ccstatusline,claude-hud}` forces an adapter (auto prefers ccstatusline
when both are present). Every edit is backed up and reversible. The bar is crash-safe: on
any error it prints an empty line and exits 0, so it never breaks the host HUD. Full model
and both recipes: `docs/HUD_ADDON.md`.

## Packaging notes

- **sdist-clean via a build hook.** `apps/cli/hatch_build.py` (a custom hatchling
  build hook, enabled on BOTH the `wheel` and `sdist` targets) vendors the four
  workspace packages (`zeno_core` / `zeno_sdk` / `zeno_adapters` /
  `zeno_session_intel`) plus the SDK alembic tree into an in-root, gitignored
  `_vendor_build/` stage at build time. The wheel target flattens them to the
  archive top level (the exact layout the old static `force-include` produced, so
  absolute imports resolve unchanged); the sdist target ships the whole
  `_vendor_build/` stage inside the tarball so a wheel built FROM the sdist finds
  the sources locally. This replaced the static `[tool.hatch...force-include]` of
  `../../packages/...` relative-parent paths, whose `..` escaped the sdist root and
  were silently dropped - a wheel from that sdist died with "Forced include not
  found". Repo source under `packages/*` is never moved, so the uv workspace, the
  API, and the test suite keep importing the editable members unchanged; the
  vendored copy is purely a build artifact.
- `zeno ingest` / `zeno usage` are backed by `zeno_session_intel`, vendored
  alongside the other internal packages by the build hook. It is stdlib-only with
  relative-only internal imports, so it flattens into the wheel with zero import
  rewrites. Omit it and both subcommands abort with a "not bundled" hint at runtime
  (the regression fixed in 0.3.3); `scripts/install-smoke.sh` now exercises every
  advertised subcommand so this cannot ship silently again.
- Agent-framework adapters (`zeno_sdk.adapters` -> crewai / openai / anthropic /
  langgraph) are off the CLI path and pull heavy framework deps; they are kept
  optional and will be exposed as extras (e.g. `zeno-cli[crewai]`) in a later stage.
