Animated WaffleDocsLog in

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:

bash
npm install -g @aniwaffle/cli
aniwaffle --version
aniwaffle

The 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:

bash
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

bash
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.

bash
cd waffle-lab-<name>
aniwaffle lab status
aniwaffle lab serve

Leave 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:

bash
aniwaffle lab sessions suggest
aniwaffle lab sessions add -f sessionId='<SESSION_UUID>'
aniwaffle lab sessions list

Suggestions 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

text
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:

bash
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 --json

path 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.

ReplyMeaning
OriginalRecorded reply from the old Session.
PublishedReplay of the published Agent revision. Replies can be cached across runs.
DraftReplay 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:

bash
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.