drharness/docs/history-editing.md

📜 History Editing

If a conversation goes off track, you can surgically edit your conversation history using the interactive history editing mode. This allows you to rewind to a specific point, modify messages, or remove problematic exchanges without starting over.

Invoking History Editing

Use the -b or --edit-history flag along with -F to specify your chat file:

./build/drharness -F conversation.json -b

Note: The -F flag is required because editing requires an existing chat file.

The Rebase Editor Format

When invoked, the harness opens your configured editor with all messages in your conversation listed in order. Each line follows a git rebase-style format:

<command> <index> [<role>] <display_content>

Commands:

• pick: Keep the message unchanged
• edit: Modify the message content and/or role
• drop: Delete the message (or simply remove the line)

Role: (optional, only for edit commands)

• [user]
• [assistant]
• [tool]

Display content: The first line of the message (for reference only)

Lines starting with # are comments and are ignored. Empty lines are treated as drops.

Editing Message Content and Roles

When you mark a message with edit, the harness will open your editor again to let you modify the content. The edit prompt shows:

• The previous message as context (for reference)
• The >8 separator
• The message content you can edit

You can change the role by modifying the role in the rebase line (e.g., edit 2 [user]).

Common Workflows

Editing a single message:

pick 0 [user] Hello, can you help me?
pick 1 [assistant] Sure! What do you need?
edit 2 [assistant] I misunderstood. Let me try again.
pick 3 [user] That's better, thanks!

Then, when editing message 2, you'll be prompted to enter the new content.

Dropping unwanted messages:

pick 0 [user] Start the project
drop 1 [assistant] Wrong approach
pick 2 [user] Let me try a different way

Or simply delete the line:

pick 0 [user] Start the project
# pick 1 [assistant] Wrong approach
pick 2 [user] Let me try a different way

Modifying message roles:

pick 0 [user] Write a function
edit 1 [user] I meant write a class instead

Continuing a conversation after editing: After saving and exiting the editor, your changes are persisted to the chat file. The program exits, allowing you to inspect the result. To continue the conversation:

./build/drharness -F conversation.json -m "Continue from where we left off"

Note: The history editor uses strict validation. Any syntax error (invalid command, out-of-range index, invalid role) will cause the editor to abort with an aggregated error message. No partial changes are applied.