Metadata-Version: 2.4
Name: nauro-ballast
Version: 0.1.0.dev1
Summary: Context audit for coding-agent transcripts: compaction events, absence findings, and the context bill (Claude Code + Codex CLI). Local, offline, share-safe by default.
License: Apache-2.0
Project-URL: Repository, https://github.com/Nauro-AI/ballast
Keywords: claude-code,codex,context,compaction,audit,transcripts
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Nauro Ballast

Context audit for coding-agent transcripts. Reads your local Claude Code and Codex CLI
session logs and produces your context bill: what filled your context windows, where
documented compactions happened, what survived them, and what did not.

Status: pre-release alpha. An open-source Nauro project (Apache-2.0).

## What it does

- `nauro-ballast census`: a share-safe census over `~/.claude/projects` and
  `~/.codex/sessions`: sessions, composition by category, peak context sizes, documented
  compaction events, context wall-hits, and inferred session-boundary structure. Counts
  only; no transcript content in the output.
- `nauro-ballast match`: the absence matcher. For every documented compaction boundary it
  reconstructs the post-compaction context exactly as the harness defines it and reports,
  per pre-boundary message, what remained lexically reachable.

## Claim discipline

Findings are tiered and the tiers are never pooled:

- DETECTED-ABSENCE (Claude Code documented boundaries): a message with no verbatim or
  near-verbatim match in the reconstructed context at the boundary. Lexical absence,
  reported as such; never a claim about model behavior. Re-supply later in the session is
  counted separately.
- AT-RISK (Codex): the compaction item is encrypted by design, so items not among the kept
  plaintext are reported as exposure, never as absence.
- INFERRED (both): heuristics (token discontinuities, rapid-successor sessions), always
  labeled.

## Privacy

Fully local, offline, zero network calls, no account. The default report is share-safe:
counts, categories, and truncated identifiers only. Verbatim excerpts require an explicit
`--with-excerpts` flag and pass a redaction filter (keys, tokens, emails, paths) first.

## Install

Not yet published. From a checkout:

```
uvx --from . nauro-ballast census
uvx --from . nauro-ballast match
```

Once published: `uvx nauro-ballast census`.

## License

Apache-2.0.
