Metadata-Version: 2.5
Name: iiwi
Version: 0.12.0
Summary: Agent Session Intelligence for engineering work
Author: Mike
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: platformdirs<5,>=4
Requires-Dist: pydantic-settings<3,>=2.7
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich<15,>=14
Requires-Dist: typer<1,>=0.16
Provides-Extra: dev
Requires-Dist: pyright>=1.1.400; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# Iiwi

**Iiwi** · /ˈiː.wiː/ "ee-wee" — turns your coding-agent sessions into a weekly
engineering report, without anything leaving your machine.

[![CI](https://github.com/mike840609/iiwi/actions/workflows/ci.yml/badge.svg)](https://github.com/mike840609/iiwi/actions/workflows/ci.yml)
[![Release](https://github.com/mike840609/iiwi/actions/workflows/release.yml/badge.svg)](https://github.com/mike840609/iiwi/actions/workflows/release.yml)
[![PyPI](https://img.shields.io/pypi/v/iiwi)](https://pypi.org/project/iiwi/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://pypi.org/project/iiwi/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mike840609/iiwi/blob/main/LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/mike840609/iiwi/pulls)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mike840609/iiwi)

English | [繁體中文](https://github.com/mike840609/iiwi/blob/main/README.zh-TW.md)

![Iiwi — see what your agents did](https://github.com/mike840609/iiwi/raw/refs/heads/main/docs/assets/iiwi-banner.jpg)

The weekly status update is work you already did once. Iiwi reads the sessions
your coding agent already recorded, synthesizes evidence-backed outcomes, and lets
you review the result before it writes the report. Quick Review targets a 30–60
second pass from candidate outcomes to a shareable update. Works with OpenCode,
Claude Code, and Codex.

- **Nothing leaves your machine.** Your local `opencode run` writes the narrative — no network, no API key.
- **Finds your sessions anywhere.** Every project, whichever folder you run from.
- **Groups by repository.** Worktrees collapse into one entry; child and subagent sessions stay with it.
- **Redacts first.** Common secret patterns are stripped locally before anything is written.

## Quick start

Needs Python 3.11+ and `git`. Plus one transcript source: OpenCode (the default,
needs an `opencode` executable) or a readable Claude Code / Codex transcript store
at `~/.claude/projects` or `~/.codex` (their CLIs are not needed for reading).
Quick Review outcome synthesis still uses your local `opencode run` for every
transcript source; if it is unavailable, the recovery screen offers Retry and an
explicit session-based report fallback.

```bash
pipx install iiwi                 # or: pip install iiwi

iiwi doctor                       # is the harness ready?
iiwi daily                        # review yesterday, today, and blockers
iiwi report --period last-week    # write the report
```

The report lands under `reports/`.
Pass `--dry-run` to print the report to the terminal instead of writing a file.

## The interactive menu

Run `iiwi` with no arguments if you would rather not remember flags:

```text
$ iiwi
 ___ _        _
|_ _(_)_ __ _(_)
 | || \ V  V / |
|___|_|\_/\_/|_|                                v0.9.1
══════════════════════════════════════════════════════
Turn coding-agent sessions into engineering reports
github.com/mike840609/iiwi

▶ Review Activity
  Daily Standup
  Generate Report
  History
  Check Setup
  Settings                       # full-screen editor, every choice listed

↑↓ jk │ Enter Select │ 1-6 │ ? Help │ q Quit
```

Choosing **Generate a report** shows every setting at once instead of asking one
question at a time — `↑↓` moves, `←→` changes a value, and a line under the list
explains the setting you are on. Press `g` to generate, or `r` to open
**Review sessions** first, which weighs each repository by how much of the period
it actually accounts for:

```text
Review Sessions   6 / 6 selected │ 252 / 252 msgs
══════════════════════════════════════════════════════
Select sessions to include in the report:

  1. ▾ ████████████  71% ● iiwi   3 / 3    Aug 5 │ 180 msgs
▶      ████░░░░░░░░  24% ● Add the interactive menu Aug 5 │ 60 msgs
       ████░░░░░░░░  24% ● Redact before writing    Aug 5 │ 60 msgs
       ████░░░░░░░░  24% ● Group worktrees          Aug 5 │ 60 msgs
  2. ▸ ████░░░░░░░░  24% ● obsidian-wiki   2 / 2    Aug 4 │ 60 msgs
  3. ▸ █░░░░░░░░░░░   5% ● dotfiles   1 / 1         Aug 3 │ 12 msgs

↑↓ jk │ ←→ hl │ Space Toggle │ p Preview │ e Exclude │ a All │ g Generate │ / Search │ ? Help │ b Back
```

Choosing **History** lists every report the tool has written, newest first.
`↑↓` moves; Enter shows the row's full output path.

Choosing **Daily Standup**, or running `iiwi daily`, scans every enabled harness
from yesterday's local midnight through now and opens a three-section Quick
Review for Yesterday, Today, and Blockers. Preview and Generate use the same
reviewed Markdown, written as `daily-standup-YYYY-MM-DD.md`. See the
[Daily Standup guide](https://github.com/mike840609/iiwi/blob/main/docs/daily-standup.md)
for source warnings, suggested Today work, and same-day review persistence.

`Space` toggles a repository or a single session, `p` previews a transcript
(redacted), and `e` excludes a repository from every future scan. Your selection
is remembered per period. Press `g` to synthesize the selected sessions into
Quick Review instead of writing the session-based report immediately.

Quick Review keeps the evidence traceable while you decide what belongs in the
update. The first five candidates are selected; additional work stays under
**More candidates**, and extraction failures stay visible under **Ungrouped
candidates**. User-added outcomes, optional Blockers, and optional Next week text
are included in the same in-memory draft.

```text
Space Include/exclude │ e Edit │ J/K Reorder │ v Evidence │ s Split │ a Add
p Preview │ g Generate │ b Back
```

`p Preview` renders the current draft without writing a file. `g Generate` writes
that reviewed draft. If synthesis fails, retry it or explicitly use the labeled
session-based report fallback. See the
[evidence-first Quick Review guide](https://github.com/mike840609/iiwi/blob/main/docs/evidence-first-quick-review.md)
for the full flow and the Manager/Engineering and Brief/Full responsibilities.

## Commands

```bash
iiwi doctor                       # is the harness ready?
iiwi daily                        # review yesterday, today, and blockers
iiwi scan --period last-week      # preview how sessions group
iiwi report --period last-week    # write the report
iiwi history                      # reports already written
iiwi update                       # check PyPI for a newer release
iiwi run                          # the same questions, one at a time
```

| Flag | What it does |
|---|---|
| `--harness claude-code` / `--harness codex` | Read another harness's sessions — the narrative still comes from your local `opencode run` |
| `--no-llm` | Deterministic structured report; works whether or not OpenCode is installed |
| `--sanitize` | OpenCode's stronger redaction, which intentionally removes most work evidence |
| `--dry-run` | Print the report instead of writing a file |
| `--json` | Redacted machine-readable output for `scan`, `doctor`, `history`, and `update` (the default when stdout is piped) |

`iiwi --help` lists everything, and `run` is the linear wizard if you prefer being
asked. In scripts, name a subcommand directly — with no terminal to prompt at, the
menu exits with status 3 rather than reading stdin.

## Configuration

Settings come from an environment variable first, then the settings file, then the
default:

```bash
iiwi config init                                          # walk through all
iiwi config set harnesses.opencode.cli.model deepseek-r1  # write one
iiwi config list                                          # show all, with sources
iiwi config unset report.timezone                         # back to the default
```

Every setting and its environment-variable name is in the
[configuration guide](https://github.com/mike840609/iiwi/blob/main/docs/configuration.md).

## Privacy

Everything happens on your machine: sessions are read from disk, common secret
patterns are redacted, and the redacted transcript is handed to your locally
installed `opencode run`. No API key, and `update` is the only command that touches
the network.

Reports may still contain private goals, filenames, commands, and full working
paths — always review one before sharing it. See
[Privacy and security](https://github.com/mike840609/iiwi/blob/main/docs/privacy.md)
for the full data flow and current limits.

## Documentation

| Page | What's in it |
|---|---|
| [CLI reference](https://github.com/mike840609/iiwi/blob/main/docs/cli-reference.md) | Every command, option, and exit code |
| [Daily Standup](https://github.com/mike840609/iiwi/blob/main/docs/daily-standup.md) | Yesterday/Today/Blockers review, refresh, warnings, and output |
| [Evidence-first Quick Review](https://github.com/mike840609/iiwi/blob/main/docs/evidence-first-quick-review.md) | Outcome review keys, report modes, recovery, and current exclusions |
| [Configuration](https://github.com/mike840609/iiwi/blob/main/docs/configuration.md) | Settings file, environment variables, precedence |
| [Privacy and security](https://github.com/mike840609/iiwi/blob/main/docs/privacy.md) | Data flow, redaction boundary, what reports still contain |
| [Security policy](https://github.com/mike840609/iiwi/blob/main/SECURITY.md) | Threat model and how to report a vulnerability |
| [Usage guides](https://github.com/mike840609/iiwi/blob/main/docs/guides.md) | Reporting periods, subagents, repository grouping, output handling |
| [Usage statistics](https://github.com/mike840609/iiwi/blob/main/docs/usage-statistics.md) | How the usage section is built, and its window caveat |
| [Support and limits](https://github.com/mike840609/iiwi/blob/main/docs/limitations.md) | The per-harness caveat list |
| [Architecture](https://github.com/mike840609/iiwi/blob/main/docs/architecture.md) | How a report is produced, end to end |
| [Releasing](https://github.com/mike840609/iiwi/blob/main/docs/releasing.md) | How a release is cut |

## The name

The ʻiʻiwi is a scarlet Hawaiian honeycreeper whose long curved bill reaches nectar
others cannot — which is what this tool does with the sessions your agent left
behind. Pronounced the anglicised way, "ee-wee".

## Development

```bash
git clone https://github.com/mike840609/iiwi.git
cd iiwi
uv sync --locked --extra dev                    # install the project and its dev tools

uv run iiwi                                     # run your working copy
uv run pytest --cov=iiwi --cov-fail-under=80    # tests, with the coverage gate CI enforces
uv run ruff check .                             # lint
uv run pyright                                  # type check
```

The last three are exactly what CI runs, so a green local run means a green PR.

### Name forms

The name is cased by where it appears:

| Context | Form |
|---|---|
| Distribution, CLI, URLs, application directories | `iiwi` |
| Python package and imports | `iiwi` |
| Prose | `Iiwi` |
| Environment variables | `IIWI_` prefix |
| Error base class | `IiwiError` |

## License

MIT
