What Undo AI reads and writes

To analyze an Undo recording, Undo reads the recording, the source code and debug symbols of the program that was recorded, and any GDB command files you supply (see Custom initialization).

Undo writes in the places described below. The tools Undo offers your AI agent do not take a destination path, so the agent cannot choose where Undo puts these files. The exception is a GDB command file you supply, since Undo runs whatever commands it contains, including any that write elsewhere.

Files in your working directory

Undo creates a .undo-ai directory (lazily, the first time it has a file to write) in the working directory it starts in: your AI agent’s working directory, or UDB’s when you use the ai command. It holds the files Undo writes for the AI agent to read, which are the responses of tools too large to return inline (see Long recordings and the model’s context) and, for the ai command, the instructions UDB gives the agent it starts.

The files have to be there: AI agents normally refuse to read anything outside their working directory and its descendants, so a temporary directory elsewhere would put them out of reach. They can contain source code and values from the recorded program, in the same way that your conversation with the AI agent can, and you may want to add .undo-ai to your .gitignore.

The directory goes away once the last session using it has exited. A session killed abruptly, by a crash or by the machine shutting down, leaves its files behind, so you may find the directory still there; you can delete it yourself whenever Undo is not running.

If the working directory cannot be written to, Undo falls back to its own temporary directory, and your AI agent may then need your permission to read those files, or refuse to read them at all.

Files in Undo’s temporary directory

Undo creates a temporary directory for each session, holding the files Undo needs to work and to replay the recording, such as extracted symbol files.

The directory is deleted when the session ends cleanly. To put it somewhere other than the default, see Temporary directory root.

Files in your home directory

Undo keeps the state it needs from one run to the next, such as your session state and usage statistics, in its own directories under your home directory, following the XDG Base Directory Specification. None of this is specific to AI use.

Recordings you ask for

If you ask your AI agent to capture a recording, it runs live-record as a command rather than through one of Undo’s tools, so the recording goes where the agent puts it: the location you asked for, or one the agent chooses if you did not say. This is the only file written outside the places above.

What Undo does not modify

Nothing in an investigation writes to the recording, to your source code, or to anything your build produced. Bookmarks that an AI agent sets are stored in the UDB session belonging to the recording rather than in the recording file; see UDB session commands for where session state is kept.

Files your AI agent writes

Your AI agent writes files of its own, such as its configuration and the transcript of your conversation, and it can write wherever you allow it to. None of that is under Undo’s control; see the documentation of your AI agent for what it writes and where.