Metadata-Version: 2.4
Name: hansei-cli
Version: 0.1.0
Summary: Agent-readable session intelligence for local Codex JSONL traces.
Author: Hansei contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/sidduHERE/hansei
Project-URL: Repository, https://github.com/sidduHERE/hansei
Project-URL: Issues, https://github.com/sidduHERE/hansei/issues
Keywords: agents,codex,cli,sqlite,traces,token-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Logging
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Hansei

Agent-readable session intelligence for local Codex traces.

Status: public CLI alpha

Hansei turns local Codex session JSONL into bounded, evidence-backed summaries that an agent can use without reading raw logs. It helps answer:

- Where did tool output, search, failed commands, rereads, and subagent work spend tokens or time?
- Which facts are exact, estimated, inferred, or unknown?
- What evidence should the agent inspect next?

Hansei is not a token dashboard, an MCP-first server, or an LLM summarizer. It does not decide what was “waste” by itself. It exposes mechanical facts, attribution tiers, warnings, and evidence refs so the consuming agent can reason from the trace instead of guessing.

## Why The Name

`hansei` (反省) means structured self-reflection: look honestly at what happened, name what was weak or wasteful, and decide what to change next. This tool gives coding agents that same reflection step over local session traces.

## Install

From PyPI after the first publish:

```bash
pipx install hansei-cli
hansei --version
```

If you use `uv`:

```bash
uv tool install hansei-cli
hansei --version
```

Until PyPI is live, install from the GitHub release tag:

```bash
pipx install 'git+https://github.com/sidduHERE/hansei.git@v0.1.0'
hansei --version
```

GitHub release tag with `uv`:

```bash
uv tool install 'git+https://github.com/sidduHERE/hansei.git@v0.1.0'
hansei --version
```

From a checkout:

```bash
python3 -m pip install .
hansei --version
```

## Quickstart

```bash
hansei init
hansei ingest codex --since 7d --agent
hansei overview --window 7d --agent --budget 1500
hansei hotspots --window 7d --limit 20 --agent
hansei drill <hotspot_id> --agent --budget 2500
hansei evidence <evidence_id> --agent --max-chars 4000
```

For a machine-readable command map:

```bash
hansei manifest --agent
```

## Agent Skill

Print the bundled skill:

```bash
hansei skill print codex
```

Install it into the current repository:

```bash
hansei skill install codex
```

Install it for the current user:

```bash
hansei skill install codex --user
```

The repository also includes `.agents/skills/hansei-session-intelligence/SKILL.md` as the checked-in repo-local skill.

## Current CLI Surface

Setup and ingest:

```bash
hansei init
hansei doctor --agent
hansei doctor --schema-profile --agent
hansei sources list
hansei sources add codex --path ~/.codex/sessions
hansei ingest codex --since 7d --agent
hansei ingest codex --since 7d --dry-run --agent
hansei ingest codex --file <path> --agent
```

Investigation:

```bash
hansei overview --agent --budget 1500
hansei hotspots --agent --limit 20
hansei drill <hotspot_id> --agent --budget 2500
hansei pack <hotspot_id> --agent --budget 4000
hansei evidence <evidence_id> --agent --max-chars 4000
hansei search "<query>" --agent --budget 2000
hansei session <session_id> --agent --budget 2500
hansei timeline <session_id> --agent --budget 2500
```

Open-ended query primitives:

```bash
hansei find --kind tool_call --list-fields --agent
hansei find --kind command --where 'exit_code!=0' --agent
hansei stats --kind tool_call --metric output_generated_tokens_est --by command_family --agent
hansei dupes --window 7d --agent
hansei files --window 7d --agent
hansei context <session_id> --agent --budget 3000
hansei errors --window 7d --agent
hansei compare --window 7d --agent
```

Sequence and subagent views:

```bash
hansei sequences --agent --budget 2500
hansei sequences --refresh --agent --budget 2500
hansei subagents --agent --budget 2500
```

Eval gates:

```bash
hansei eval fixtures --agent
hansei eval detectors --agent
hansei eval corpus --agent
hansei eval corpus --refresh --agent
hansei eval all --agent
```

## Output Contract

Agent-facing commands emit `hansei.response.v1` JSON envelopes:

```json
{
  "schema": "hansei.response.v1",
  "ok": true,
  "query": {
    "command": "hansei hotspots",
    "window": "7d",
    "budget_tokens": 1500,
    "limit": 20
  },
  "budget": {
    "limit_tokens": 1500,
    "estimated_response_tokens": 1120,
    "truncated": false
  },
  "answer": {},
  "evidence_refs": [],
  "claims": [],
  "next_queries": [],
  "warnings": [],
  "truncation": {
    "truncated": false,
    "reason": null,
    "cursor": null,
    "how_to_continue": null
  }
}
```

The full CLI contract is in [docs/agent-cli/HANSEI_CONTRACT.md](docs/agent-cli/HANSEI_CONTRACT.md).

## What Hansei Tracks

Hansei ingests Codex JSONL into a local SQLite projection:

- sessions, turns, trace events, tool calls, command runs, and token observations
- exact token totals when Codex reports them
- estimated output sizes when only text is available
- inferred consumed-context attribution when following model-call token evidence supports it
- evidence refs back to bounded slices of local logs
- mechanical hotspots like large tool output, broad search, repeated failed commands, repeated file reads, cache drops, and post-compaction rereads
- sequence patterns and subagent lineage surfaces, with correlation and confidence warnings

The durable architecture is:

```text
Codex JSONL -> normalized trace IR -> SQLite facts -> claims/evidence refs -> bounded agent envelopes
```

Decision records live in [adr/README.md](adr/README.md).

## Safety And Privacy

Hansei is local-first:

- It reads local Codex logs.
- It stores a local SQLite DB, defaulting to `~/.hansei/hansei.sqlite`.
- It does not send traces to a remote service.
- It returns bounded summaries and evidence slices by default.
- It applies best-effort redaction to evidence slices.
- Raw evidence requires an explicit `--raw`.

Codex logs can contain private code, credentials, personal data, and sensitive tool output. Do not commit raw session logs or local Hansei databases. See [SECURITY.md](SECURITY.md).

## Mutation Rules

Read commands should not create or migrate a DB by surprise. If the DB does not exist, they return a typed `DB_NOT_FOUND` error with the next setup command.

Commands that may write local state:

- `hansei init`
- `hansei sources add`
- `hansei ingest codex`
- `hansei skill install`
- `hansei hotspots --refresh`
- `hansei sequences --refresh`
- `hansei eval corpus --refresh`

`hansei eval fixtures`, `hansei eval detectors`, and `hansei eval all` use a temporary eval DB and packaged fixtures.

## Development

Run the main checks:

```bash
python3 -m unittest discover -s tests -q
PYTHONPATH=src python3 -m hansei --db /tmp/hansei-eval.sqlite eval all --agent
PYTHONPATH=src python3 -m compileall -q src/hansei
```

Package smoke:

```bash
rm -rf dist /tmp/hansei-build /tmp/hansei-wheel /tmp/hansei-install-test
python3 -m venv /tmp/hansei-build
/tmp/hansei-build/bin/python -m pip install --upgrade pip build
/tmp/hansei-build/bin/python -m build --sdist --wheel
mkdir -p /tmp/hansei-wheel
cp dist/*.whl /tmp/hansei-wheel/
python3 -m venv /tmp/hansei-install-test
/tmp/hansei-install-test/bin/python -m pip install --no-index --find-links /tmp/hansei-wheel hansei-cli
python3 scripts/smoke_installed_cli.py \
  --hansei /tmp/hansei-install-test/bin/hansei \
  --python /tmp/hansei-install-test/bin/python
```

Release checklist: [docs/release.md](docs/release.md).
