Skip to content

Commit dabb9a6

Browse files
ahmadawaisCommandCodeBot
ahmadawais
and
CommandCodeBot
committed
docs: hi-in-five-languages demo, shorter README
Co-authored-by: CommandCodeBot <noreply@commandcode.ai>
1 parent 1225cd2 commit dabb9a6

2 files changed

Lines changed: 56 additions & 101 deletions

File tree

‎README.md‎

Lines changed: 53 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -2,135 +2,89 @@
22

33
![cmd-mod-jev-nudge](https://raw.githubusercontent.com/CommandCodeAI/cmd-mod-jev-nudge/refs/heads/main/.github/workflows/image.png)
44

5-
Agents stop too early. They finish one step, write "next I'll do X", and hand the prompt back.
5+
Agents stop too early. They do one step, say "next I'll do X", and hand the prompt back.
66

7-
This [Command Code](https://commandcode.ai) mod catches that. When a run is about to end, it asks
8-
[Jev](https://typesafe.ai) whether a nudge would help the agent keep working on what you asked for.
9-
Jev answers with a probability. A confident yes sends the agent back to work.
10-
11-
Two guards stop a bad nudge. One checks if the agent is waiting on you (permission, a decision,
12-
missing info). The other checks if the last nudge got anything done.
13-
14-
```
15-
model finishes turn (no tool calls)
16-
│
17-
▼
18-
onStop → state {user_requests, latest_assistant_message, recent_tool_calls, previous_nudges}
19-
│
20-
▼
21-
POST api.commandcode.ai/provider/v1/systemone ──► Jev
22-
nudge "would a gentle nudge help… right now?" → p
23-
waiting "needs permission / decision / info / event?" → p
24-
progress "moved on since the reply we nudged?" → p (2nd+ nudge only)
25-
│
26-
▼
27-
waiting ≥ .5 · progress < .5 · nudge < .5 · error/timeout ──► run stops as normal
28-
otherwise ──► {continue: true} + nudge turn ──► model keeps working
29-
(Command Code allows 8 of these per user turn, then ends the run)
30-
```
7+
This [Command Code](https://commandcode.ai) mod asks [Jev](https://typesafe.ai) at every stop:
8+
would a nudge help? Yes, and the agent keeps going. It won't nudge when the agent is waiting on
9+
you, or when the last nudge got nothing done.
3110

3211
## Install
3312

3413
```bash
35-
cmd login # skip if signed in
36-
cmd mods add cmd-mod-jev-nudge # add -g for all projects
14+
cmd login # skip if signed in
15+
cmd mods add cmd-mod-jev-nudge # add -g for all projects
3716
```
3817

39-
That's it. The mod uses your Command Code key, from `CMD_API_KEY` or `cmd login`. With no
40-
key it stays off and says so. If Jev fails or times out, the run stops like it would without the mod.
18+
That's it. Uses your Command Code key (`CMD_API_KEY` or `cmd login`). If Jev fails, the run stops
19+
as normal.
4120

42-
## Flags
21+
## See it
4322

44-
Pass with `--mod-option name=value`.
45-
46-
| Flag | Default | Meaning |
47-
|---|---|---|
48-
| `jev-nudge-threshold` | `0.5` | Minimum "a nudge would help" probability |
49-
| `jev-nudge-max` | none | Max nudges per run. `0` turns nudging off |
50-
| `jev-nudge-base-url` | `https://api.commandcode.ai` | API root, for a proxy or the fake server |
51-
| `jev-nudge-model` | `typesafe/jev` | Model id |
52-
| `jev-nudge-verbose` | `false` | Show declined stops in the feed too |
53-
54-
`DEBUG=true` prints every decision to stderr.
55-
56-
Why 0.5? I measured it. Jev says 0.5 to 0.8 when real work is left and 0.04 to 0.08 when the agent is
57-
done. 0.5 sits in the gap. At 0.6 the first nudge depended on how the model worded its status line.
58-
59-
Why no nudge cap by default? Stopping after N nudges without looking is the same "stopped too early"
60-
bug. The guards end runs on evidence instead. Command Code still caps stop-hook continues at 8 per
61-
user turn, and no mod can raise that. A task that needs more than 8 nudges should be split up anyway.
62-
63-
## Try it from a clone
64-
65-
```bash
66-
git clone git@github.com:CommandCodeAI/cmd-mod-jev-nudge.git
67-
cd cmd-mod-jev-nudge
68-
pnpm install # --mod doesn't install deps, cmd mods add does
69-
cmd --mod . # loads this mod for one session
7023
```
71-
72-
This prompt forces early stops on purpose:
73-
24+
say hi in five languages. ONE hi per reply, then stop and say how many done. after the fifth say "all done".
7425
```
75-
make smoke-1-ignite.txt … smoke-5-ash.txt (kindle, blaze, ember between), each file holds its word. ONE file per reply, then stop and say what's left. ignore other files. all 5 exist → say "all five files are done".
76-
```
77-
78-
One prompt, five replies. You type once. Percentages vary run to run.
7926

8027
```
81-
you ▸ make smoke-1-ignite.txt … smoke-5-ash.txt ...
28+
you ▸ say hi in five languages ...
8229
83-
agent ▸ write smoke-1-ignite.txt
84-
Created smoke-1-ignite.txt. Remaining: 2, 3, 4, 5.
85-
┊ stop → Jev: nudge 78% · waiting 6%
30+
agent ▸ Hola! 1 of 5 done.
8631
jev nudge 1: unfinished work found (78%), continuing
87-
88-
agent ▸ write smoke-2-kindle.txt
89-
Created smoke-2-kindle.txt. Remaining: 3, 4, 5.
90-
┊ stop → Jev: nudge 74% · waiting 5% · progress 91%
32+
agent ▸ Bonjour! 2 of 5 done.
9133
jev nudge 2: unfinished work found (74%), continuing
92-
93-
agent ▸ write smoke-3-blaze.txt ... (nudge 3)
94-
agent ▸ write smoke-4-ember.txt ... (nudge 4)
95-
96-
agent ▸ write smoke-5-ash.txt
97-
all five files are done
98-
┊ stop → Jev: nudge 5% → no nudge, run ends
99-
34+
agent ▸ Ciao! 3 of 5 done.
35+
jev nudge 3 ...
36+
agent ▸ Hallo! 4 of 5 done.
37+
jev nudge 4 ...
38+
agent ▸ Konnichiwa! all done.
39+
← Jev 5%, no nudge, run ends
10040
you ▸ _
10141
```
10242

103-
Tell it "do one step, then wait for my go-ahead" instead and the waiting guard blocks the nudge:
43+
You type once and get five replies. Add "then wait for my go-ahead" to the prompt and it stops after
44+
one, because the agent is now waiting on you.
45+
46+
## How it works
10447

10548
```
106-
agent ▸ Created smoke-1-ignite.txt. Want me to go on?
107-
┊ stop → Jev: nudge 41% · waiting 88%
108-
jev-nudge: turn 2, no nudge (waiting on the user (88%)) ← only with jev-nudge-verbose=true
109-
you ▸ _
49+
agent stops
50+
│
51+
▼
52+
POST api.commandcode.ai/provider/v1/systemone (typesafe/jev)
53+
nudge would a nudge help right now? p
54+
waiting needs you: permission, info, choice? p
55+
progress did the last nudge get anywhere? p (2nd nudge on)
56+
│
57+
▼
58+
waiting ≥ .5 · progress < .5 · nudge < .5 · error → stop
59+
otherwise → nudge, keep going
11060
```
11161

112-
The `┊ stop → Jev` lines show what happens under the hood. The feed shows only the `jev nudge`
113-
rows. Add `DEBUG=true` to print every decision to stderr.
62+
Command Code allows at most 8 nudges per user turn.
11463

115-
### Offline
64+
## Flags
11665

117-
`scripts/fake-jev.mjs` fakes the API with fixed rules. It nudges unless the reply says it's done,
118-
reports waiting when the reply ends in a question, and counts progress when tools ran since the last
119-
nudge. Every request lands in `jev-log.jsonl`.
66+
`--mod-option name=value`
12067

121-
```bash
122-
node scripts/fake-jev.mjs &
123-
CMD_API_KEY=x cmd --mod . --mod-option jev-nudge-base-url=http://127.0.0.1:4711 --mod-option jev-nudge-verbose=true
124-
```
68+
| Flag | Default | Meaning |
69+
|---|---|---|
70+
| `jev-nudge-threshold` | `0.5` | Min probability to nudge |
71+
| `jev-nudge-max` | none | Max nudges per run, `0` = off |
72+
| `jev-nudge-verbose` | `false` | Show skipped nudges too |
73+
| `jev-nudge-base-url` | `https://api.commandcode.ai` | API root |
74+
| `jev-nudge-model` | `typesafe/jev` | Model id |
75+
76+
`DEBUG=true` logs every decision to stderr.
77+
78+
The 0.5 threshold is measured. Jev says 0.5 to 0.8 with work left and under 0.1 when done.
12579

12680
## Develop
12781

12882
```bash
129-
pnpm install
83+
git clone https://github.com/CommandCodeAI/cmd-mod-jev-nudge.git
84+
cd cmd-mod-jev-nudge && pnpm install
85+
cmd --mod . # run it
13086
pnpm test
131-
pnpm typecheck
132-
pnpm lint
13387
```
13488

135-
`src/protocol.ts` builds the state, questions, and decision with no I/O. `src/client.ts` makes the
136-
HTTP call. `src/index.ts` registers the hooks.
89+
Offline, run `node scripts/fake-jev.mjs` and add
90+
`--mod-option jev-nudge-base-url=http://127.0.0.1:4711`. It logs requests to `jev-log.jsonl`.

‎scripts/fake-jev.mjs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// Local stand-in for Jev, for trying the mod offline. Serves Command Code's POST
22
// /provider/v1/systemone and answers with fixed rules instead of a model: nudge 86% unless the reply
33
// says the work is done, waiting 92% when the reply ends with a question, progress 90% when
4-
// tools ran since the last nudge. Every request is appended to jev-log.jsonl so you can see
4+
// tools ran or the reply changed since the last nudge. Every request is appended to jev-log.jsonl so you can see
55
// exactly what the mod sent.
66
//
77
// node scripts/fake-jev.mjs
@@ -15,7 +15,8 @@ const judge = state => {
1515
const finished = /\b(all done|everything is done|all (three|five|the) (files|steps) are done|nothing (else|more) to do)\b/i.test(text);
1616
const nudge = finished ? 0.08 : 0.86;
1717
const last = state.previous_nudges?.at(-1);
18-
const progress = last ? (last.tool_calls_after > 0 ? 0.9 : 0.1) : undefined;
18+
const moved = last && (last.tool_calls_after > 0 || last.assistant_text_at_nudge !== text);
19+
const progress = last ? (moved ? 0.9 : 0.1) : undefined;
1920
return {nudge, waiting, progress};
2021
};
2122

0 commit comments

Comments
 (0)