The annot8 manual.

01. Install from source

This is an early prototype, built with Python and Textual. You can edit plain text in any language. Python 3.10 or later runs the editor itself; Git provides commit comparisons.

Download the source .zip, extract it, then open a terminal in the extracted annot8 folder.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
annot8 --demo

The activation command above is for macOS and Linux. In Windows PowerShell, use python -m venv .venv and .venv\Scripts\Activate.ps1. The prototype has been tested on macOS; Linux and Windows have not yet been verified.

Activating the environment makes annot8 available from any directory in that shell. For a permanent command on macOS or Linux, you can link its launcher into a directory already on your command path, for example:

mkdir -p "$HOME/.local/bin"
ln -s "$PWD/.venv/bin/annot8" "$HOME/.local/bin/annot8"

Run this from the project folder. It requires ~/.local/bin to be on your PATH, and the project folder to stay in place. The launcher does not change your working directory.

02. Open, type, save, leave

annot8 notes.txt
annot8 "new note.txt"
annot8 /path/to/project

Relative filenames are relative to the directory you are in. A new filename opens an empty buffer; the file is created when you save. Its parent folder must already exist.

There is no insert mode. Just type. Ctrl + S saves; Ctrl + Q returns you to your shell. Unsaved edits prompt you to save, discard, or cancel.

Use Ctrl + O for the file picker. Type to narrow the list, use the arrows to choose, and press Enter to open. Escape cancels without switching files.

03. A small set of shortcuts

These are Ctrl shortcuts, including on a Mac. Apple Terminal reserves many Command combinations. Word movement also accepts Ctrl + ← / → where your terminal forwards it; Option-word movement supports both arrow sequences and the traditional Alt+B / Alt+F sequences. Clipboard access and modified keys depend on the terminal.

Escape closes the active picker or search. In the plain editor, it hides the sidebar and Change Desk and puts typing focus back in your text.

04. Read your Git changes

Open Changes with Ctrl + G, then choose Git changes. The current document is compared with HEAD, including staged, unstaged, and unsaved edits together.

The review uses line numbers, BEFORE / AFTER labels, and character highlights. Three unchanged context lines surround each edit; Context expands the rest. Use F4 to move to the next change.

This is a review view. It does not stage changes, modify the index, or create commits.

05. Keep your work separate from an agent’s

A snapshot gives the agent’s session a starting line without requiring a clean Git tree.

1. Save your own edits with Ctrl + S.
2. Open Changes and choose Take snapshot, or find it in Actions.
3. Run your agent in another terminal or app.
4. Return to annot8 and press Ctrl + R to refresh.
5. Choose Agent changes to compare against the snapshot.

Existing personal edits are included in the snapshot, so they are not mixed into the new comparison. Every edit made after that checkpoint appears, whoever made it. This is a baseline comparison, not automatic authorship detection.

One snapshot is kept in .annot8/snapshot.json. Choose New agent baseline in Actions to replace it. Add .annot8/ to your project’s .gitignore.

Snapshots contain full text copies of eligible files. Git-ignored files, binary files, symlinks, common generated directories, and files over 2 MB are excluded. Without Git, generated directories are excluded but Git ignore rules are not interpreted.

06. Make yourself at home

Ctrl + P opens a small colour picker: Ink, Paper, or Moss. Choose with the arrows, Enter to apply, Escape to cancel.

The Settings button also controls line wrapping, line numbers, and indentation width. Preferences are saved per workspace in .annot8/settings.json. Demo preferences disappear when the disposable demo closes.

Fonts and font size come from your terminal. In macOS Terminal, open Settings → Profiles → Text → Font.

07. Prototype notes

• One open buffer at a time.
• UTF-8 plain text, up to 2 MB per file.
• Manual refresh for files changed outside the editor.
• Diff review only: no hunk accept/revert or staging yet.
• One agent snapshot, with no history.
• Intended for small to medium projects; workspace scans run on the interface thread.

Saving checks for changes made outside annot8 and stops if the file differs from the version you loaded. Keep a copy of your buffer before discarding it and reopening the external version.

Named checkpoints, line comments, and review bundles are ideas for the next iteration. They are not shipped features.