Wind-up tools for coding agents

jouet (pronounced "zhweh", French for "toy") is a command-line toolkit for coding agents such as Claude Code and Codex. It does two things:

• It records what sessions cost. Hooks time every build, test and lint, and at session start the agent is told which ones are slow, so it can finish its edits and build once instead of after every change. Across sessions, jouet looks for commands that keep failing and corrections that keep coming back, and drafts a rule, a mise task or a routine for each.
• It replaces scripts agents write by hand. Exact edits across files, searches and reads within a budget, CI waits in one call, and running only the tests a change affects. When an agent writes the script anyway, a hook points it to the command.

[!CAUTION] jouet is in early development. How much it helps depends on your language, test runner and agent, and your setup may need some configuration, or a fix in jouet, before you see any savings. Commands, flags, exit codes and JSON output may change incompatibly between releases until 1.0.

Quick start

1. Install jouet with mise:

   mise use -g jouet
   

   Or run cargo install jouet --locked, or unpack a release archive for Linux, macOS (Apple Silicon) or Windows. All installation options →

2. Connect your agent. This installs jouet's hooks, which time the checks and brief each session, and the jouet-init skill:

   jouet setup claude   # or: codex, cursor, gemini, copilot
   

3. Start your agent in a project and ask it to use the jouet-init skill: /jouet-init in Claude Code, $jouet-init in Codex, or "Use the jouet-init skill to configure jouet for this project." The agent reads the project's checks and timing history, adjusts jouet's configuration where the project needs it, and checks what it changed. Initializing a project →

Learning from past sessions

The hooks time each build, test and lint, and jouet cost lists the timings. The primer names the slowest checks, so the agent can batch its edits before a long run, or pick a narrower check while it iterates.

jouet wind looks across sessions for a command that keeps failing, long sleeps, or the same commands run over and over, and drafts a rule or a mise task for each. Session review, once you turn it on, reads whole sessions for the user's corrections and abandoned approaches, and proposes rules, tasks, routines and notes. You or the agent decide what to adopt. A drafted rule only warns until it is promoted (automatic promotion is off unless you turn it on), and jouet unwind proposes retiring rules that aren't helping.

A routine is a procedure the agent calls once instead of working through each step: a short, tested Luau program, something like a skill that runs. joue land waits for CI and merges a PR once it is ready.

jouet audit reads your Claude Code and Codex transcripts and shows where the tokens and time went, and jouet stats estimates the tokens jouet saved and the tokens it cost, and the net, against your own history. Those are estimates, not benchmark results; the comparative benchmarks are still being built.

Example: editing a file

An agent shouldn't need a Python program to change one string:

python3 - <<'EOF'
from pathlib import Path
p = Path("src/main.rs")
s = p.read_text()
assert s.count("let x = 1;") == 1
p.write_text(s.replace("let x = 1;", "let x = 2;"))
EOF

With jouet:

jouet edit replace src/main.rs --old 'let x = 1;' --new 'let x = 2;'

The old text has to match exactly once. With several files or replacements, jouet checks all of them before it writes anything, so a stale match leaves every file alone and shows the closest match instead. See a multi-file failure →

Commands

Code and data

Command	Instead of
jouet edit	heredoc edits with a hand-written assert s.count(old) == 1
jouet search	rg printing every match; grouped by function, budgeted, and skipping what the session already saw
jouet read	reading a whole file to find one definition; --map gives a repository map, on the code graph
jouet graph	repeated searches for callers, dependencies and the tests a change reaches
jouet diag	a full lint run to check the files you just changed
jouet docs	recalling a dependency's API from memory; its signatures and docs at the locked version
jouet deps	adding a dependency from memory; whether it exists, its latest version, licence and OSV advisories
jouet db	sqlite3 and psql -c printing whole tables; schemas and read-only queries, cut to a limit
jouet http	curl piped into jq; the status and only the JSONPaths asked for, with credentials redacted

Running and waiting

This is the beginning of the README. Read the rest at the original. Read the full README ↗