Please enable JavaScript to view this site.

Navigation: Take Command

Annotations

Scroll Prev Top Next More

Take Command can attach free-form notes called Annotations to ranges of scrollback text in the tab window scrollback buffer. Annotations

let you mark interesting output — an error you want to return to, the command that produced a bad result, or a section worth explaining to

someone else, without altering the tab window contents.

 
Creating and Managing Annotations

 
Select a range of text in the terminal window and right-click it. The terminal context menu gains an Add Annotation item below the standard edit and

command-block actions. Choosing it opens a small dialog for the note text; the annotation is created when you confirm with a non-empty note.

 
Right-clicking directly on text that is already annotated replaces that item with Edit Annotation and Delete Annotation. Editing an existing note and

clearing all of its text is equivalent to deleting the annotation. Annotated cells are marked with a colored underline drawn beneath the normal text decorations.

 

Hovering the mouse over an annotated range shows the note text in a tooltip, so notes can be read without opening the edit dialog.

Multi-line notes wrap rather than being clipped, and the tooltip stays visible long enough to read longer notes.

 

Annotations do not modify the tab window's scrollback buffer, and they do not affect selection, command-block rendering, folding, or copied text.

 
Storage Model

 
Each annotation records an inclusive start row/column and end row/column in logical scrollback coordinates, plus the note text. Annotations are keyed by their

starting logical row, so a given row can host at most one annotation. Annotating a row that already carries an annotation replaces the previous note rather

than adding a second one. Because the coordinates are logical rather than physical, annotations survive scrolling and remain anchored to the text they describe.

When the terminal buffer is resized, annotations are remapped onto the new row numbering alongside the fold set and shell-integration marks. An annotation

whose start row scrolls out of the retained buffer is dropped; end rows and columns are clamped to the new buffer bounds.

 
Annotations live in the session and in recordings. They are not written to TCMD.INI, and do not persist across a restart of an ordinary (non-recorded) session.

 
Recording and Replay

 
Annotations are exported with asciicast terminal recordings so that a `.cast` file reproduces both the terminal output and the notes made about it. They are serialized

into the recording stream using the private-use `x` metadata event that Take Command also uses for shell-integration data:

 

•`{"event":"annotation_add","row":<start row>,"startCol":<col>,"endRow":<row>,"endCol":<col>,"text":"<note>"}`

•`{"event":"annotation_edit",...}` — same fields as `annotation_add`.

•`{"event":"annotation_delete","row":<start row>,...}` — only `row` is required.

 
The note text is JSON-escaped inside the payload, which the recorder escapes again for the enclosing asciicast string. This is the same double-encoding used by

the `cmd_start` payload. During playback Take Command  applies these events as they are reached, so annotations appear at the same point in the timeline where they

were originally created. Seeking clears the current annotation set and replays the metadata from the beginning of the recording, ensuring the displayed annotations

always match the selected timestamp. Malformed payloads are ignored rather than interrupting playback.

 
Because `x` is a private Take Command extension, other asciicast players that do not recognize it will ignore annotation events and play back the standard `o`/`i` events normally.