lumen 2.25.0

lumen is a command-line tool that uses AI to generate commit messages, summarise git diffs or past commits, and more.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# lumen for Codex

Hook lumen into [OpenAI Codex](https://github.com/openai/codex)'s `Stop`
event. Codex finishes a turn → lumen pops up on the uncommitted diff
→ you annotate → press `s` → annotations are injected as the next user
message and Codex continues in the same turn.

```
agent stops → lumen opens → review → `s`
→ Codex sees your annotations as if you typed them → agent fixes them
```

**The agent never knows lumen exists.** It just receives feedback that
looks exactly like a user message.

## How it works

Codex `Stop` hooks can return:

```json
{ "decision": "block", "reason": "<text>" }
```

…which makes Codex *not* stop and instead inject `reason` as the next
user message. `lumen diff --hook codex-stop` handles this protocol:

| Lumen flow                       | Stdout                                            | Codex behavior      |
| -------------------------------- | ------------------------------------------------- | ------------------- |
| No uncommitted changes           | `{}` (TUI skipped entirely)                       | Turn ends normally  |
| User pressed `s`, sent feedback  | `{"decision":"block","reason":"<annotations>"}`   | Continues with text |
| User pressed `q`, dismissed      | `{}`                                              | Turn ends normally  |

## Install

Enable Codex hooks (experimental, behind a feature flag):

`~/.codex/config.toml` (or repo-local `.codex/config.toml`):

```toml
[features]
hooks = true
```

Register the hook — either copy [`hooks/hooks.json`](./hooks/hooks.json)
to `~/.codex/hooks.json`, or paste this:

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "lumen diff --hook codex-stop",
            "timeout": 345600
          }
        ]
      }
    ]
  }
}
```

Restart Codex. Done.

### Notes

- Use an absolute path to `lumen` (e.g. `/opt/homebrew/bin/lumen`) if
  you launch Codex Desktop — app-launched processes don't always
  inherit your shell `PATH`.
- `timeout` is in seconds; the large value lets you take your time
  reviewing without Codex killing the hook.
- Codex hooks are currently disabled on Windows in the official docs.

## Test it without Codex

The hook contract is `stdin = event JSON, stdout = response JSON`, so
you can drive it from a shell:

```bash
# Inside a repo with uncommitted changes:
echo '{"hook_event_name":"Stop"}' | lumen diff --hook codex-stop
```

- TUI opens (on `/dev/tty`, since stdout is captured).
- Annotate, press `s` → `Enter`.
- Stdout receives `{"decision":"block","reason":"# ...\n\n**file** line N\n\n...comment..."}`.
- Press `q` instead → stdout receives `{}`.

In a clean working tree the same command returns `{}` instantly without
opening the TUI.