History, Markers and Session

Fork the current node to create an independent branch. The fork becomes the new head.

Example prompt: fork the session and call it "take-2"

Returns: node_id

Move the session head to an earlier node. Does not delete any nodes.

Example prompt: revert to before the reverb

Returns: node_id

Generate a diff between two nodes: tracks added/removed, gain changes.

Example prompt: compare the current version with the one before normalization

Returns: tracks_added, tracks_removed, tracks_changed

Apply a computed diff from compare_nodes to the current session.

Example prompt: (used internally by the agent)

Returns: node_id

Set a human-readable label on the current head node.

Example prompt: name this state "final mix"

Returns: node_id

Add a named point marker or region annotation to the timeline.

Example prompt: mark the chorus at 1:05

Returns: annotation_id

Import Audacity-format label text into the session as annotations. Format: each line is 'start_sec TAB end_sec TAB name'.

Example prompt: import these Audacity labels

Returns: node_id

Export session annotations as Audacity-format label text (start_sec TAB end_sec TAB name, one per line).

Example prompt: export the markers as labels

Returns: label text

List the session's tracks, buses or markers a page at a time, in the same lines the session summary in the agent's prompt uses. A session too big for that summary has each list cut and says how many it left out; this is how the agent reaches the rest. Reads only — it changes nothing, so Plan first never holds it for approval.

Example prompt: list every track in this session

Returns: summary (what range it showed of how many), text (the lines), next_offset (only while there is another page)

A page ends at 100 items or 4,096 bytes, whichever comes first, so a model with a small context can take it: a thousand markers come in several pages, not one result. Local models are sent this tool whenever that summary was cut.

Prune old history and delete the audio the project made that only that history used. A file you loaded is never deleted, only the undo steps that named it. Reports what it would remove and changes nothing unless asked twice, because this removes undo steps permanently — the nodes are gone, not archived. The most recent nodes on the current chain are never pruned, so ordinary undo keeps working; what goes is the tail beyond them and any branches forked away from and never returned to.

Example prompt: this project is huge — reclaim some disk

Returns: prunable_nodes, reclaimable_bytes, reclaimable_files; removed_nodes, removed_files, kept_files and freed_bytes when applied

It deletes only files inside the project's own .audiograph/derived/ folder, where edits write their audio, and checks each one again just before deleting it. Anything else a pruned version named — a recording you loaded from elsewhere, clipboard audio, a cached preview — stays where it is, and the apply result counts it in kept_files. For space without losing history, nothing is needed: once a project's derived audio passes 2 GiB, the oldest audio only undo history holds is swept in the background — but only files a replay of their edits has just rebuilt, byte for byte, so undoing back to one rebuilds it. This tool is for what cannot be rebuilt that way, or for dropping history on purpose.

Report what the session costs on disk, split by category: audio the current version needs, audio only the undo history needs (and how much of that is rebuildable from recorded operations), audio nothing references at all, the bounded preview cache, and clipboard blobs. Every destructive edit writes a new file; audio nothing references goes when the project opens, and past 2 GiB the oldest audio only undo history holds is swept, once a replay has rebuilt it. Reads only — it deletes nothing.

Example prompt: how much disk is this session using?

Returns: total_bytes, live, history, unreferenced, preview_cache, clipboard_blobs

Pair it with compact_session, which does the reclaiming — this is the before-and-after measurement.