clacky-ai--openclacky/docs/time_machine_design.md

Time Machine Design Documentation

Overview

Time Machine is a feature that allows users to navigate through the agent's task execution history, providing undo/redo capabilities and branch exploration. Users can access it via ESC key or /undo command to view an interactive menu of past tasks.

Core Data Structure Design

Task History Graph

The Time Machine uses a minimal tree-based data structure to track task relationships:

Three Core State Variables:

1. task_parents (Hash): Maps each task_id to its parent_id

   • Forms a tree structure where each task points to its predecessor
   • Root tasks have parent_id = 0
   • Enables traversal in both directions (parent→children, child→parent)

2. current_task_id (Integer): The latest created task ID

   • Always increments when new tasks are created
   • Never decreases, even during undo operations
   • Represents the "tip" of the execution timeline

3. active_task_id (Integer): The current active position in history

   • Can move backward/forward during undo/redo
   • Determines which messages are visible to the LLM
   • When active_task_id < current_task_id, we're viewing "past" state

Task Metadata Structure

Each task in the history contains:

• task_id: Unique identifier (auto-incrementing integer)
• summary: Brief description (first 80 chars of user's message)
• status: One of three states
  • :past - Task is before the current active position
  • :current - Task is the active position (marked with →)
  • :future - Task exists but is after active position (marked with ↯)
• has_branches: Boolean indicating if multiple children exist (marked with ⎇)

Snapshot Strategy

File State Preservation

Complete AFTER-State Snapshots:

• After each successful task execution, all modified files are saved
• Storage location: ~/.clacky/snapshots/{session_id}/task-{id}/
• Each file is stored with its full relative path from working directory
• Only files modified during that task are snapshotted

Why AFTER-state instead of BEFORE-state:

• Simpler restoration logic (just copy files back)
• No need to track "what changed" - the snapshot IS the state
• Easier to verify correctness (snapshot = expected state)

File Restoration Process:

• When switching to a task, iterate through all its snapshotted files
• Copy each file from snapshot directory to working directory
• File permissions and timestamps are preserved

Message Filtering

Active Messages Concept:

• Messages array contains ALL messages (past, current, future)
• active_messages() method filters out "future" messages
• LLM only sees messages with task_id <= active_task_id
• This creates the illusion of time travel without data deletion

Why Keep All Messages:

• Enables redo operations (future messages preserved)
• Allows branch switching (alternative futures available)
• Simplifies session serialization (single source of truth)

Session Persistence

State Serialization

Time Machine state is saved under :time_machine key in session data:

• task_parents hash (complete tree structure)
• current_task_id (latest task number)
• active_task_id (current viewing position)

Restoration Guarantees:

• Complete task tree is rebuilt
• Active position is restored
• Snapshot files remain available across sessions
• User can continue undo/redo from where they left off

Critical Test Scenarios

1. Basic Undo/Redo Flow

Test Focus:

• Sequential task creation increments task IDs correctly
• Undo moves active_task_id backward (current_task_id unchanged)
• Redo moves active_task_id forward
• File snapshots are correctly restored at each step
• Cannot undo beyond root task (task_id = 0)
• Cannot redo beyond current_task_id

Edge Cases:

• Undoing at root task should fail gracefully
• Redoing when already at tip should fail gracefully
• Multiple consecutive undos should work correctly

2. Branching Scenarios

Test Focus:

• After undo, creating new task creates a branch
• New branch starts from active_task_id, not current_task_id
• Original future branch is preserved (for potential redo)
• Parent task is marked with has_branches: true
• Child tasks list should include both branches

Branch Navigation:

• Switching between branches restores correct file states
• Each branch maintains independent history
• Message filtering correctly shows only relevant messages

3. Message Filtering and Task IDs

Test Focus:

• Every message is tagged with task_id (user, assistant, tool results)
• Active messages only include those with task_id <= active_task_id
• LLM never sees "future" messages during undo state
• After redo, future messages become visible again
• New tasks created after undo get fresh task IDs (not reused)

Message Consistency:

• Tool results are associated with correct task
• Multi-turn conversations maintain task association
• Error messages don't break task ID tagging

4. File Snapshot Integrity

Test Focus:

• Only modified files are snapshotted (not entire project)
• File content is exactly preserved (byte-for-byte)
• Nested directory structures are correctly recreated
• Multiple files in single task are all snapshotted
• Snapshot directory naming prevents collisions

Restoration Accuracy:

• After undo + file restore, file content matches expected state
• Subsequent task execution works with restored files
• Binary files are handled correctly (not corrupted)

5. Session Persistence and Recovery

Test Focus:

• Save session, restart, restore session preserves Time Machine state
• Task tree structure is fully rebuilt
• Active position is correctly restored
• Snapshot files are accessible after restart
• Undo/redo operations work identically after restore

Persistence Edge Cases:

• Empty task history (new session)
• Session with complex branching
• Session saved while in "undo" state (active_task_id < current_task_id)

6. AI Tool Integration

Test Focus:

• Tools are correctly registered in tool registry
• AI can invoke undo_task, redo_task, list_tasks
• Agent parameter is correctly injected (similar to TodoManager pattern)
• Tool execution returns success/failure messages
• Tools respect permission modes (confirm_all, auto_approve, etc.)

Tool Interaction:

• AI calling undo_task modifies agent state correctly
• Subsequent AI responses use filtered messages
• Tool results are included in task history
• Multiple tool calls in sequence work correctly

7. UI and User Interaction

Test Focus:

• ESC key triggers time machine menu
• /undo command works identically to ESC
• Menu displays correct task list with status indicators
• Visual markers: → current, ↯ future, ⎇ branches
• User selection triggers correct task switch
• Menu updates after undo/redo operations

User Experience:

• Task summaries are readable (truncated to 80 chars)
• Menu is responsive with large task histories
• Cancel/exit returns to normal operation
• Error messages are clear and actionable

8. Integration with Existing Features

Test Focus:

• Works with message compression (no dependency on tool_calls)
• Compatible with session serialization
• Doesn't interfere with cost tracking
• Works with both UI modes (UI1 and UI2)
• Subagent forking doesn't inherit Time Machine state

Feature Compatibility:

• Todo manager works normally during undo state
• Web search tools work correctly
• File tools (write, edit) trigger snapshots
• Shell commands can be undone via file snapshots

Design Principles

Minimal Invasiveness

• Only 3 new instance variables in Agent class
• No changes to core message structure (only adds task_id field)
• Existing tools unaware of Time Machine existence
• No performance impact when not in use

Data Integrity

• Never delete messages or snapshots (immutable history)
• File restoration is idempotent (can redo multiple times)
• Task IDs never reused (prevents confusion)
• Snapshot isolation (each task has independent directory)

User Control

• Explicit user action required (ESC or /undo)
• Clear visual feedback on current position
• Cannot accidentally lose work (future preserved)
• Can explore branches without commitment

Developer Friendly

• Simple tree data structure (easy to reason about)
• Comprehensive test coverage (55 test cases)
• Clear separation of concerns (module-based design)
• Well-documented edge cases

Future Enhancement Possibilities

Potential Improvements

• Automatic snapshot garbage collection (old sessions)
• Diff view between task states
• Named checkpoints (user-defined bookmarks)
• Merge branches functionality
• Export task history as replay script
• Snapshot compression for large files

Scalability Considerations

• Large file handling (incremental snapshots)
• Long session histories (pagination in UI)
• Multiple simultaneous branches (better visualization)
• Remote collaboration (shared task history)