diff --git a/README.md b/README.md index d9b9167..9587563 100644 --- a/README.md +++ b/README.md @@ -95,88 +95,8 @@ export EDITOR=nvim # or vscode, nano, vim, emacs, etc. *Note: If neither `VISUAL` nor `EDITOR` is set, the harness will refuse to launch the editor and throw an error instead.* -## 📜 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: - -```bash -./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: - -``` - [] -``` - -**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: -```bash -./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.* +For detailed documentation on history editing, see [docs/history-editing.md](docs/history-editing.md). ## 🐳 Docker Isolation diff --git a/docs/history-editing.md b/docs/history-editing.md new file mode 100644 index 0000000..92e0b0e --- /dev/null +++ b/docs/history-editing.md @@ -0,0 +1,83 @@ +## 📜 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: + +```bash +./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: + +``` + [] +``` + +**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: +```bash +./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.* +