Metadata-Version: 2.5
Name: witnox
Version: 0.1.0
Summary: Local-first observability and behavioral analytics for AI coding agents
Author: Isaac Yong
License-Expression: MIT
License-File: LICENSE
Keywords: analytics,claude-code,coding-agents,observability
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# Witnox

**Local-first observability and behavioral analytics for AI coding agents.**

Witnox is an independent, read-only project for understanding how coding agents use tools, time and tokens. It does not require Herdr or ORC. Early builds focus on safe local aggregation of Claude Code JSONL sessions; other agents, shell subcommand parsing, token attribution and cross-agent comparisons are planned, **not implemented yet**.

## Development status

**v0.1.0 initial release.** The supported command aggregates Claude Code tool-use counts; no shell subcommand parsing or automatic monitoring yet.

## Quick start

```sh
uv sync --extra dev
uv run witnox --version
uv run witnox report --days 7 --top 30
uv run witnox report --root /path/to/user-home --days 7 --json
uv run pytest -q
```

Windows PowerShell:

```powershell
uv run witnox report --root $HOME --days 7 --top 30
```

Progress is shown with tqdm when stderr is an interactive terminal. Use `--progress` to force it or `--no-progress` to suppress it. Progress is written only to stderr, so `--json` stdout remains machine-readable.

## Privacy and boundaries

- Local-first; no network requests, background services, or runtime telemetry.
- Reads `.claude*/projects/**/*.jsonl` but does not modify it.
- Only counts tool names. Does **not** save or print user prompts, raw commands, file paths, tool arguments, or tokens.
- CLI JSON contains aggregates only. Consider aggregate information potentially sensitive before sharing publicly.
- Repeated snapshots are deduplicated by tool-use ID within a file. Logs without stable identifiers may be skipped.
- No claims that a tool call equals a task, a successful result, or an actual subprocess execution.

## Roadmap

1. Validated tool-call aggregation with fixture tests.
2. Separate Claude Bash and PowerShell parser with conservative counting and measurable uncertainty.
3. Codex and Gemini adapters with documented schema and coverage limits.
4. Optional incremental local SQLite index and reproducible cross-agent efficiency comparisons.
5. Post-v0.1.0: add verified shell metrics and cross-agent comparison.

## Publishing

PyPI deployment is triggered by publishing a GitHub Release tagged exactly `v0.1.0` (matching `pyproject.toml`). The `.github/workflows/publish.yml` workflow tests with uv, builds distributions, and uploads using PyPI Trusted Publishing (OIDC). Configure the pending PyPI publisher for owner `NaNIsaac`, repository `witnox`, workflow `publish.yml`, and GitHub environment `release` (create it in the repository's Settings → Environments). The publish job references this environment. For a failed initial publication from an older release tag, use the manual `workflow_dispatch` on `main` after this change is merged; re-running an old release job would continue using the workflow stored at the old tag. No API token is required.

MIT licensed. See [LICENSE](LICENSE).
