Keep related work in one session so you can review its objective, conversation and results. Start another session when the task, workspace or access boundary changes.
For extended work, manage a long session and review the context and compaction boundaries before treating saved history as proof that a detail remains in the next request. This guide is for a terminal user who has completed Getting started . It covers Sonny 0.12.7 on Linux; desktop/editor controls and mesh ownership are separate interfaces.
For a structured research, review and approval workflow, follow Plan, review and approve work .
Use Memory for a deliberate durable fact or decision beyond a conversation, and inspect its scope separately from session history.
Before you start
Configure a model and review the selected Recipe’s tool policy. The interactive controls below do not disable tools. A request to “only draft” is an instruction, not a filesystem or network boundary. Use the tool-free cookbook if you want its explicitly disabled-tool headless setup.
For this disposable example, use the cookbook’s public review Recipe. Download it in an empty directory and inspect the YAML before registering it:
mkdir sonny-session-review
cd sonny-session-review
mkdir approved-recipes
curl --fail --location https://sonny.sh/examples/cookbook/review-work.yaml --output approved-recipes/review-work.yaml
sonny recipe validate ./approved-recipes/review-work.yaml
sonny recipe list
sonny recipe add ./approved-recipes --name sonny-docs-review --no-model-catalog --update-policy manual
Choose a different source name if sonny-docs-review already exists. Registration
snapshots this local directory into Sonny’s Recipe cache and records a source in
its configuration. It does not alter the original directory. This example adds no
model catalog, routing approval or MCP server approval; your configured model is
still required. Honor any trusted-policy refusal rather than disabling it. Registering makes the Recipe available to the daemon’s catalog
for branching, as well as selecting the file for your current session.
Start a new task
This creates a fresh session using the reviewed file:
sonny run --file ./approved-recipes/review-work.yaml --new
Confirm the workspace and Recipe shown by the TUI. Paste these approved fictional notes and ask for a comparison:
Note A: 40 support requests, 30 answered within one day. Note B: 50 requests, 35 answered within one day. No satisfaction survey was supplied. Compare the rates, cite A or B for each number, and keep missing evidence visible. Return a draft for review; do not send or publish anything.
Check 75%, 70%, a decrease of five percentage points, and no invented satisfaction result. The analysis tutorial includes an independent checker. A response is complete only when your requested checks and artifacts are satisfied; the session remaining in history says nothing about that.
Find and select earlier work
/sessions or Ctrl+S opens the session manager. Inspect the title, identifier
and workspace before selecting a row. Type to filter and use the arrow keys.
Enter opens the selected session according to the client settings; Ctrl+R in the
manager requests replacing the current tab. Escape closes the manager. Ctrl+R
outside the manager has a different purpose: command-history search.
At a later launch, the recent-session chooser can offer local rows and reachable mesh rows. Choose the exact local task for ordinary continuation. A remote row is an attachment to another owner, not a local copy. The qualified fixture completed two separate TUI processes with one stored conversation; the second provider request contained the earlier user and assistant turns.
For an explicit identifier, use the full UUID from the selector. This is syntax with a placeholder, not a literal session identifier:
sonny run --file ./approved-recipes/review-work.yaml --session <full-local-session-id>
Confirm the selected identity if a chooser is shown. --continue requests recent
history and can select work outside your current directory; an explicit ID is
clearer when several tasks exist. The run reference
records the
qualified TUI flow and the observed failed completed-headless replay cases. Do not
assume that adding --prompt makes every stored session executable again.
sonny session is the evaluation/optimization command family, not a session-list
or delete CLI. Do not invent sonny session list or copy a database to bypass a
selection or authority error.
Interrupt and inspect
Press Ctrl+C to cancel an active local response, then inspect what finished.
The runtime fixture retained partial assistant text marked [response interrupted].
That marker is not evidence that a requested tool action never took effect.
Inspect files or service records before retrying any operation with an uncertain
outcome. A subsequent Ctrl+C when idle can quit; read the displayed quit options.
A saved transcript can be durable while an in-flight request, live connection or uncommitted tool result is transient. Session history, local traces, project files, provider retention and durable service records have different lifetimes. Clearing a conversation or deleting one session does not establish deletion from all of them.
Rename, copy and review
When the task is idle, these are TUI commands:
/rename Pilot review
/branch Pilot comparison copy
Rename changes the title while preserving the session identity. Branch creates a distinct conversation copy; it is not a live split peer and does not transfer execution authority or credentials. Inspect the manager afterward rather than assuming which tab is active. In the fixture, a copy with its own ID remained after deleting the originally selected session.
If branching reports that the Recipe is unavailable, inspect its registered source and selected ID. A Recipe passed only as a file need not be available in the daemon’s catalog. The setup above addresses that prerequisite without changing the Recipe or copying state.
Delete only the intended session
Before deletion, inspect the current title/ID and any unfinished work. Wait until the session is idle; cancel or finish active work first. For a readable archive, first follow export and portability and inspect the output’s contents and destination.
/delete-session
The confirmation shows a session label. N or Escape cancels; Y confirms the requested deletion. In the disposable fixture, cancellation retained both conversations and confirmation removed the intended local row while the branch copy and its transcript remained. Deletion is not an undoable archive toggle and does not delete another conversation’s copy or a separately exported file.
The daemon also has an archive metadata operation for capable clients; it does
not end execution. This TUI walkthrough does not provide an /archive command or
claim a tested desktop archive button. Hiding older rows, closing a tab, canceling
a turn, archiving and deleting are different operations.
Data effects and recovery
Prompts and selected context go to your configured provider. Sonny retains session
state and can retain traces/audit records; --no-trace does not erase history or
control provider retention. Exports can contain sensitive instructions and messages.
Keep the original workspace and integration-owned child worktrees until review and
integration are confirmed.
Use the local recovery runbook before replacing a database. It preserves committed WAL data and tests a restored TUI conversation without replacing the original backup. The privacy inventory explains the separately retained records and key material.
If two clients change the same session, a stale revision or authority conflict requires re-reading the current state, not forcing the old operation through. Source contract tests exercise stale updates and idempotency; this local fixture does not certify a live multi-node deployment. For a timeout, inspect the manager and target before repeating a create, branch, delete or service write.
If you registered the example source only for this exercise, inspect its name and
use sonny recipe remove sonny-docs-review to remove that source/cache. It does
not remove your original example files or serve as session deletion. Do not remove
a source that other sessions still need to load.
Continue with goals and delegated work or mesh sessions and ownership .