iTerm2 Saved State

Overview

iTerm2 supports window and session restoration: when the application quits or the system restarts, it saves the state of open windows, tabs, and sessions so they can be recreated on next launch. This state is written under ~/Library/Application Support/iTerm2/SavedState/. Because the saved state can preserve terminal buffer content — the scrollback that was on screen, including command output — it may retain evidence of what a user saw and did after the session that produced it has ended.

The saved-state files are an opaque binary format (a keyed archive / custom serialization); iTerm2 does not document their internal structure, and macfor does not decode it in full. The forensic value in the current version is twofold: (1) metadata for every saved-state file (name, size, modification and creation times), which establishes that sessions existed and when they were last saved; and (2) best-effort plaintext extraction, which recovers readable text runs (buffer content, prompts, output) embedded in the binary without needing to parse the container.

Forensic Significance

File Locations

macfor enumerates the directory recursively and records one metadata entry per file.

Best-Effort Text Extraction

Because the container format is undocumented, macfor recovers readable text heuristically rather than parsing the structure. It reads each saved-state file and extracts the longest contiguous run of printable UTF-8 text (graphic characters plus space, tab, and newline). A run must exceed 32 bytes to be reported, and the recorded excerpt is capped at 1024 bytes. This is deliberately conservative — it surfaces terminal buffer content and prompts without attempting to interpret the surrounding binary.

This is the same principle as running strings over the file, but scoped to the single longest coherent text region so the excerpt is a readable fragment rather than a scatter of short tokens.

# Manual equivalent: inspect readable text in a saved-state file
strings -n 32 ~/Library/Application\ Support/iTerm2/SavedState/* | less

Parsed Record Schema

macfor emits one iterm2_saved_state metadata record per file.

Raw copies of the saved-state binaries themselves are collected only when raw collection is enabled (opt-in), each with a SHA-256 hash recorded for integrity.

Timestamps

The modified_time and created_time fields come from filesystem metadata (mtime and birth time), not from a value inside the file, and are rendered as RFC 3339 strings. On APFS the birth time is reliable; treat modification time as an approximation of when the session was last active/saved.

Analysis Notes

• Post-session evidence: Recovered text_excerpt content can reveal commands and output from a session the user has since closed — the buffer was serialized to disk. This can corroborate or extend the command history.
• Timeline anchoring: modified_time approximates the last activity in a saved session; use it to place terminal usage on a timeline even when no command history exists.
• Opaque by design: Absence of text_excerpt does not mean the file is empty — only that no run longer than 32 printable bytes was found (content may be compressed or encoded). Collect the raw file for deeper analysis.
• Volatility: Saved state is overwritten as iTerm2 saves new sessions and may be cleared on clean quit with restoration disabled. Collect it early.
• Sensitive content: Buffer content can contain passwords, tokens, and command output. Treat the excerpt and any raw copies as sensitive.

Limitations

• The binary container is not decoded to structured session/tab/window records in the current version — only metadata and best-effort text are produced.
• Text extraction is heuristic. It will miss content that is compressed, encoded, or shorter than the 32-byte threshold, and it reports only the single longest run per file.

Tool Support

References

• iTerm2 Documentation — Restoration & Saved State
• Apple — About Window Restoration