Prompt iteration
Improve an Agent's prompt with Codex
Install Aniwaffle and its optional Codex skill, edit the Agent's Draft, replay old Sessions, compare and translate replies, then publish when ready.
Before you start
Work on an Aniwaffle Agent
Use this workflow for an Aniwaffle (Waffle / Animated Waffle) Agent whose wording, personality, instructions or prompt templates you want to improve. You need Node.js 20.3 or newer, CLI 0.10.0 or newer, and an account with Agent edit/run access and readable Sessions. To create an Agent first, follow Build your first talking Agent.
There are two versions to understand: Draft is the saved configuration you are editing; Published is the version used for live conversations. Codex, the CLI, the Lab page and the Dashboard all edit the same remote Draft. There is no extra local prompt copy or sync step. Prompt edits create saved Draft revisions immediately; Publish Draft makes the reviewed configuration live.
For Agents on another platform or in your own application, use that platform or repository's workflow. Installing this skill does not move them into Aniwaffle.
Step 1
Install Aniwaffle and the optional Codex skill
In a terminal on the machine where Codex works:
npm install -g @aniwaffle/cli
aniwaffle --version
aniwaffleThe first interactive run asks whether to install the Prompt Lab skill for Codex. Answer y or press Enter to skip; the choice is remembered. npm installation prints a setup hint; the question runs when you first start the CLI. Help, version, JSON, piped commands and CI never wait for it.
To install later:
aniwaffle skills install --input '{}'The bundled skill is installed in ~/.agents/skills/animated-waffle-prompt-lab/SKILL.md, without login or another download. A different existing skill is kept so your edits are not overwritten; review and back it up before replacing it. To uninstall, remove that specific skill folder. Existing waffle users can follow the migration guide.
Codex discovers the skill automatically; restart Codex if needed. Invoke $animated-waffle-prompt-lab, or ask naturally to change an Aniwaffle Agent's prompt. It checks the target's platform first and asks when ownership is unclear. See Codex skill discovery.
Step 2
Sign in and open the Agent's Draft
aniwaffle login
aniwaffle status
aniwaffle organizations list
aniwaffle organizations use -f organizationId='<WORKSPACE_ID>'
aniwaffle agents list
aniwaffle lab init --agent '<AGENT_UUID>'Approve the login in your browser and wait for the terminal to report success. Reuse the intended existing login. Copy IDs from the lists; names can be ambiguous. For a remote host, follow browser approval.
Enter the lab directory printed by init, or pass --dir to later commands. Reuse an existing lab instead of initializing it again. This folder contains your Session selection, replay results and notes; the Agent prompt stays in its remote Draft.
cd waffle-lab-<name>
aniwaffle lab status
aniwaffle lab serveLeave serve running. The page shows the current Draft and Published versions and receives live updates when Codex, another CLI or the Dashboard saves changes. A notification announces new Draft revisions. Unsaved text in an editor is preserved and must be reconciled before saving over a changed Draft. Disconnected pages reconnect and reread the current version.
On a remote host, forward the loopback port over SSH and open the printed link locally. Do not expose the Lab as a public website.
Step 3
Choose examples and regression cases
In another terminal, from the same lab directory:
aniwaffle lab sessions suggest
aniwaffle lab sessions add -f sessionId='<SESSION_UUID>'
aniwaffle lab sessions listSuggestions include negative feedback and team notes from the last 30 days. Add relevant cases plus Sessions that already work well. lab sessions suggest -f add=true adds all suggestions; lab sessions browse and the page's Sessions tab find other conversations.
Step 4
Ask Codex for a focused change
Use the Aniwaffle Prompt Lab skill for this Agent.
It repeats the same reassurance at the start of replies. Read the chosen
Sessions and feedback, update its Draft prompt to respond to the actual
context, and replay those Sessions. Preserve the good Session's behavior.
Show me the differences and stop before publishing.Codex reads the remote Draft and saves the requested edit directly to it. On the page, edit a prompt field and choose Save Draft. To do the same from the CLI:
aniwaffle lab prompt get --json
aniwaffle lab prompt set --input '{"path":"system_prompt.md","value":"Your revised instructions","expectedRevisionId":"<REVISION_ID_FROM_GET>"}'
aniwaffle lab diff
aniwaffle lab run -f label='Respond to the current context' --json
aniwaffle lab show --jsonpath is a field identifier returned by prompt get, not a local file. Each save requires the revision you read; if it changed, reread and reconcile. For full Character card edits, agents update also accepts the card and revision precondition. Preserve unrelated fields and extensions.
| Reply | Meaning |
|---|---|
| Original | Recorded reply from the old Session. |
| Published | Replay of the published Agent revision. Replies can be cached across runs. |
| Draft | Replay of the saved Draft revision recorded when this run started. |
An unpublished Agent compares Draft with Original. Later Draft edits do not change an earlier run's results. Each generated reply becomes history for that run's next turn.
Use Translate under messages or replies and choose a language, such as 中文(简体). Originals stay visible; translations use the same workspace service as Web and never edit Draft or replay inputs. The shared language selection applies across messages. Failed translations can be retried.
Rate replies better, same or worse and add notes. Codex reads them through lab show --json and uses them for the next edit. Marking a favorite is only a review note. Use this run’s prompt in Draft restores that run's prompt into a new Draft revision, preserving other Agent settings. Review and replay the restored Draft before publishing.
To hear replies, choose Regenerate text and audio, or add -f mode=both. -f mode=tts speaks recorded replies without generating new text. Audio requests are billed separately and cached by voice and text.
Step 5
Make the Draft live when ready
Select Publish… on the page. Review the displayed Draft version and changes, then confirm Publish Draft. This publishes the complete saved Agent configuration, including its prompt, voice, model and workflow. Review all settings in the linked Dashboard when needed.
Or explicitly ask Codex to publish the reviewed revision:
aniwaffle lab prompt get --json
aniwaffle lab publish -f expectedRevisionId='<REVIEWED_DRAFT_REVISION_ID>'Publication rejects a Draft that changed after your review. Read the new revision and review again. Editing, replaying, rating or translating never publishes. A prompt-edit request alone does not authorize Codex to publish.
What to verify
Understand the replay and saved evidence
Replay uses recorded User messages and generated replies; it cannot simulate how a real user would respond differently. Memory, tools and web search are off. Text replay omits opening greetings. Workspace Replay model overrides apply. Audio replay does not establish live streaming, interruption handling or latency.
Each generated turn and spoken reply is billed like Session Replay at supplier cost; Workspace BYOK deducts no credits. Start with representative Sessions and avoid unnecessary freshBase runs. Outputs vary, so check several cases before accepting a change.
Local runs/, cache/, candidates/, Session selections and notes contain private evidence and are excluded by the generated .gitignore. Keep them out of shared repositories and reports. Existing prompt/ and base/ folders from older CLI versions are ignored and left untouched; recover any wanted old edits by reading them and saving the intended changes with lab prompt set. Old lab push/pull commands are removed and never act as aliases for Publish.