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:

pipx install hansei-cli
hansei --version

If you use uv:

uv tool install hansei-cli
hansei --version

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

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

GitHub release tag with uv:

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

From a checkout:

python3 -m pip install .
hansei --version

Quickstart

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:

hansei manifest --agent

Agent Skill

Print the bundled skill:

hansei skill print codex

Install it into the current repository:

hansei skill install codex

Install it for the current user:

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:

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:

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:

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:

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

Eval gates:

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:

{
  "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.

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:

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

Decision records live in 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.

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:

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:

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.