jouet tells an agent which builds and tests are slow before it runs them, and turns what keeps going wrong into rules, tasks and routines for later sessions. It also has commands for the edits, searches, CI waits and PR reviews that agents otherwise script by hand.
mise use -g jouetLinux · macOS (Apple Silicon) · WindowsMore install options
Next: connect your agent, then ask it to use jouet-init in your project.
Early development. How much jouet helps depends on your project, and yours may need some configuration, or a fix in jouet, before it does. Commands and output may change incompatibly until 1.0. What to expect →
How it works
jouet keeps the timings, failures and corrections from past sessions, and uses them to steer the next one.
Examples
jouet also has commands for work agents usually script by hand: a code graph, searches and reads that stay within a budget, only the tests a change affects, edits that check before they write, and waits that poll for you. Three of them, next to the scripts they replace:
src/main.rs1 assert passes2 writtenCargo.toml3 AssertionError never runsEach file is written as soon as its own assert passes.
exit 1Half edited. src/main.rs changed, Cargo.toml did not, and the error does not say so.
inside python3 - <<'EOF'
for path, old, new in edits:
s = Path(path).read_text()
assert s.count(old) == 1, path
Path(path).write_text(s.replace(old, new))Traceback (most recent call last):
File "<stdin>", line 7, in <module>
AssertionError: Cargo.tomlsrc/main.rs1 matches once3 not writtenCargo.toml2 no match3 failed1 of 2 edits failed, so no file is written.
exit 4Refused, so nothing changed. The closest match shows that Cargo.toml moved on to 0.1.1.
the spec, on stdin
=== src/main.rs
<<<<<<< SEARCH
let x = 1;
=======
let x = 2;
>>>>>>> REPLACE
=== Cargo.toml
<<<<<<< SEARCH
version = "0.1.0"
=======
version = "0.2.0"
>>>>>>> REPLACEnot written src/main.rs 1 edit +1 -1
failed Cargo.toml 1 edit
edit 1: no match
closest at line 3 (94% similar), - spec / + file:
-version = "0.1.0"
+version = "0.1.1"
0 of 2 files writtenapp.loggrep reads from the top, so the last run's line counts.
done at 0sToo early: the old line matches before this server is up. If the line never comes, the loop never ends.
until grep -q 'Listening on' app.log; do
sleep 2
doneapp.logLines already in the file are skipped.
met at 10sIt prints the line that matched. If none comes by --timeout, it exits 124 instead of hanging.
jouet wait log app.log --match 'Listening on' --timeout 2m[0s] log app.log: following
[10s] log app.log: matched
MET log app.log: matched (10s)
12:06:31 Listening on http://localhost:30007 turnsEach turn re-reads the whole conversation. The failed job's log stays locked until the entire run ends, and a conflicted PR never gets CI, so the polling never stops.
sleep 60; gh pr checks 42
# …next turn: the same again
gh run view 41083340820 --log-failed1 turnIt returns with the failed step's log while the run is still going, and exits 4 straight away for a conflicted PR.
jouet wait ci 15195 --repo jdx/mise --check releaseFAIL jdx/mise#15195 @ 843cc16 0 pass, 1 fail, 0 skipped, 0 pending (3s)
FAIL release step "Require auto-merge on the release PR" required
https://github.com/jdx/mise/actions/runs/41083340820/job/124157989724
##[error]Enable auto-merge on this pull request to build and test the release tarballs.
##[error]Process completed with exit code 1.
full log: ~/.local/state/jouet/logs/jdx-mise-job-124157989724.logIllustrative timing: 60-second polls, a check that fails 3 minutes in, and a run that ends at 7.
Reference
Each replaces a script or loop that agents commonly write. When an agent writes one anyway, a hook points it to the command.
jouet editExact edits across files that all land or none dojouet searchrg, grouped by function and cut to a budgetjouet readA file's outline, one symbol, or a repository mapjouet graphCallers, dependencies and the tests a change reachesjouet diagThe lint findings in just the files you changedjouet docsA dependency's API at the version you lockedjouet depsCheck a package exists, and its advisories, before adding itjouet dbA schema in a few lines, and read-only queriesjouet httpThe status and only the JSON paths asked forjouet testOnly the tests a change affects, and one line when they passjouet waitCI, logs, ports and processes, in one calljouet jobA build or server in the background, with an optional ready checkjouet ci runRun a workflow's jobs here before pushingjouet ci explainTell a flaky CI failure from a real onejouet taskTurn a retyped command sequence into a mise taskConventions
Every jouet command handles prompts, exit codes, JSON and long output the same way.
Every command runs without a TTY: under an agent harness, in CI or in a pipe.
1 means the answer is no. 4 means jouet refused and changed nothing.
--json prints exactly one document on stdout, errors included.
Shortened output says so and names the log file that holds the rest.