Live example: Test Ledger
The repository includes a small real project called Test Ledger. It is a dependency-free Python 3 command-line task ledger with durable JSON state and a test suite. It is small enough to understand in one sitting, but it exercises the workflow that matters: inspect a specification, make a bounded change, run tests, and inspect what rupi recorded.
The source lives at
docs/cases/2026-09-20-task-ledger/toy-project.
The package is named tasklog, so the Python commands below use python -m tasklog.
1. Prepare a disposable copy
Clone rupi if you have not already:
git clone https://github.com/SaehwanPark/rupi.git
cd rupi/docs/cases/2026-09-20-task-ledger/toy-project
The example requires Python 3 and no third-party packages. If you plan to let the
model edit files, work in a copy or a version-controlled branch. The checked-in
example config enables mutations because it was used for the original case study;
set tools.auto_approve_mutating to false before your first read-only request.
2. Verify the project without a model
Run the project’s own tests and a small command sequence first:
python -m unittest discover -s tests -p "test_*.py" -v
python -m tasklog add "write the release notes"
python -m tasklog add "run the tests"
python -m tasklog list
python -m tasklog done 1
python -m tasklog list --all
The independent acceptance oracle starts a fresh Python process for every command:
cd ..
python -m unittest discover -s acceptance -p "test_tasklog_subprocess.py" -v
cd toy-project
On Windows PowerShell, the same Python commands work. Use Set-Location or cd
to change directories; do not paste Bash line-continuation backslashes into a
PowerShell command.
3. Ask rupi for a read-only review
Start the local model described in the quickstart, then ask for one narrow, read-only inspection:
rupi run --config rupi.config.json --cwd . \
--prompt "Read SPEC.md and the project files. Do not change anything. Summarize the contract, the state-file safety rules, and the tests that prove them."
The assistant answer is on stdout; the execution transcript and diagnostics are
on stderr. This separation lets you save the answer without losing the evidence
about what the agent did.
For a controlled edit, make a backup or commit first, set
auto_approve_mutating to true only in this disposable workspace, and ask for one
small change followed by the test command. Keep the request bounded; a first task
does not need to redesign the whole project.
4. Inspect and replay the evidence
The run creates .rupi-state/ in the example directory. Find the session id in
the run output, then inspect it without starting the provider or executing old
commands:
rupi trace --config rupi.config.json --quiet --no-reasoning
rupi replay .rupi-state/sessions/<session-id>.trace.jsonl --tools --sequence
Replay is read-only. If a turn is interrupted, use the session id with
--resume after inspecting the trace and make the next prompt a small completion
slice. A partial workspace is not the same thing as a verified project; run the
Python suite independently before calling the work complete.
What this example demonstrates
- a clear specification and a bounded workspace;
- safe read-only inspection before enabling mutations;
- durable state that survives separate Python processes;
- independent verification rather than trusting the model’s final prose;
- trace and replay as recovery and audit tools.
The example is deliberately not a framework tutorial. It is a concrete first project for learning the rupi workflow.