zago: An Editor for the Many Natures of Text

AI-generated documents rarely have one fixed nature. A single piece of text may contain prose, code, a table, a diagram, an instruction, and a suggestion that still needs to be checked. Human beings then have to read it, reorganize it, draw in it, execute parts of it, and decide what it should become.

Most tools respond by sending each nature of text to a different application. zago takes the opposite approach: keep the text in one visible space, and let the editor expose a different property of that text when the work requires it.

Text Mode treats it as a stream. Table Mode treats it as structure. Canvas Mode treats it as a two-dimensional space. The buffer remains ordinary, readable text throughout.

zago is a terminal editor for this kind of work: writing, structuring, drawing, transforming, and collaborating with AI around the text currently in focus. The human chooses the focus; AI can inspect that text and propose an operation without taking over the document.

zago is for people who do not want to split a mixed document between a text editor, a table tool, a diagram app, and an AI chat window just to make one piece of work understandable. It keeps the surrounding context present while the editing model changes.

zago does not replace your existing code editor, such as vim, emacs, VSCode and so on. It is an alternative tool to help you to edit mixed documents.

• AI-agent users who write Markdown instructions, specs, notes, and review context from the terminal.
• Markdown writers who want prose, headings, links, tables, and diagrams in one terminal tool.
• Technical writers who prefer plain-text documents that remain readable in Git diffs, SSH sessions, pull requests, and README files.
• People drawing text diagrams who do not want to leave the document just to open a diagramming app.
• CJK and emoji perfectionists who need terminal display width to be correct when boxes, status-icon tables, rulers, and wrapped prose are involved.
• Keyboard-first document builders who like nano-style editing, but want a sharper toolbox for mixed plain-text work.

• zago: An Editor for the Many Natures of Text
  • Why zago?
  • Who is zago for?
  • Features
  • Requirements
  • Quick Start
    • Install on macOS / Linux from Homebrew tap
    • Install with Mint
    • Install on Linux (x86_64 / arm64)
    • Install on Arch Linux
    • Install on Windows (PowerShell)
  • Build
    • macOS
    • Linux
    • Windows / Developers
  • Text Mode & 2D Canvas Mode
  • Table Mode
  • Text Processing in Text Mode
  • IPC Mode to Interact with AI Agents
  • Command Examples
  • LOGO Environment
  • CLI Usage & Headless Scripting
    • 1. Interactive Editor & System $EDITOR Mode
    • 2. Headless Scripting & Unix Pipe Filter
    • Command-Line Options
  • FAQ, Sort Of
    • How do I preview rendered HTML?
    • Why a TUI app when Electron apps exist?
    • Why not Vim or Emacs?
    • Why not Rust?
    • Isn't LOGO for 80s kids?
    • How do I erase a wrong line or box in Canvas Mode?
  • Documentation
  • Tests
  • License

• Markdown-first editing: write prose, jump through local document links, navigate headings, and keep README-style documents close to their final form.
• Table-aware editing: format Markdown pipe tables, move between table cells, and edit table content without breaking borders.
• Plain-text diagramming: draw boxes, arrow connector lines, fills, and table layouts directly in the buffer.
• Text processing for writers: count chars, words, lines, CJK chars, and emojis; normalize CJK/ASCII spacing; transform selected text between scripts.
• Unicode-aware layout: CJK and emoji such as ✅, ❌, and ⚠️ keep boxes, tables, fills, rulers, and connector lines aligned.
• Modeless typing & dual spatial modes: Ordinary typing always inserts text directly. Press M+V to toggle between standard text stream mode and 2D Canvas Mode for freeform grid navigation and block editing.
• Nano-compatible controls: ^O save, ^X exit, ^W search, M+W copy, ^K cut, ^U paste, ^J justify, ^Z undo.
• Dynamic softwrap, visual paragraph reflow, syntax highlighting, and Nano .nanorc syntax loading.
• Multi-buffer editing, file auto-reload.
• Natural command prompt: press Esc and run editing commands such as BOX 30 4, LINE, FILL "hi, or REPEAT 5 [...].
• Lightweight automation: reuse command sequences with variables, loops, and procedures when editing becomes repetitive.

• macOS 14.0+, Linux, or Windows
• On Windows, use Windows Terminal or another VT-enabled console with UTF-8 input enabled (Note: Ctrl+Shift+Up and Ctrl+Shift+Down may be intercepted by Windows Terminal's default hotkeys; disable them in Settings -> Actions to avoid conflicts with Canvas Mode arrow drawing)
• Swift 6.0+
• VT100 / ANSI-compatible terminal

brew tap zonble/zago
brew tap --trust zonble/zago  # allow this third-party tap
brew install zago
zago notes.txt

If Homebrew refuses to install from an untrusted third-party tap, run the brew tap --trust zonble/zago line and install again.

On Linux, the Homebrew formula builds zago with Homebrew's swift package. Without Homebrew, install Swift 6 from your distribution or Swift.org and use the source build commands below.

mint install zonble/zago
zago notes.txt

Or run without installing:

mint run zonble/zago notes.txt

curl -fsSL https://raw.githubusercontent.com/zonble/zago/main/install.sh | sh
zago notes.txt

This downloads the pre-built static binary for your architecture (x86_64 or aarch64) to ~/.local/bin. No Swift toolchain required.

To install to a custom path, set INSTALL_DIR:

INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/zonble/zago/main/install.sh | sh

You can install the package by cloning the packaging source and building it locally:

git clone https://github.com/cawa0505/aur-zago.git zago-bin
cd zago-bin
makepkg -si

This package installs a precompiled static binary. It is maintained and automatically updated to track upstream releases via GitHub Actions at cawa0505/aur-zago.

irm https://raw.githubusercontent.com/zonble/zago/main/install.ps1 | iex

This downloads the pre-built zago.exe to %LOCALAPPDATA%\Programs\zago and configures your User PATH automatically. No Swift SDK required.

git clone https://github.com/zonble/zago.git
cd zago
swift build -c release
.build/release/zago notes.txt
.build/release/zago notes.txt --wrap 80
.build/release/zago notes.txt --ruler
.build/release/zago --init        # optional: create a starter ~/.zagorc

1. Install Swift 6.0+ toolchain using your distribution package manager, swiftly, or from Swift.org:

   # On Linux with Homebrew:
   brew install swift
   
   # Or install via swiftly:
   curl -O https://swiftlang.github.io/swiftly/swiftly-installer.sh
   bash swiftly-installer.sh
   swiftly install 6.0

2. Clone and build:

   git clone https://github.com/zonble/zago.git
   cd zago
   swift build -c release

3. Run the binary or install using build.sh:

   .build/release/zago notes.txt
   
   # Or install to ~/.local/bin (or /usr/local/bin):
   PREFIX="$HOME/.local" ./build.sh

(Note: End users do not need to build from source or install Swift SDK. Use the PowerShell irm command above to install the pre-built binary.)

1. Install the Swift SDK using winget:

   winget install Swift.Toolchain

2. Run PowerShell or Command Prompt as Administrator (required because dependencies such as swift-argument-parser create symbolic links on Windows during the build process).

3. Clone and build:

   git clone https://github.com/zonble/zago.git
   cd zago
   swift build

   To build a release version:

   swift build -c release

   Then run the executable:

   .build\release\zago.exe notes.txt

zago provides two complementary spatial editing modes. In both modes, typing remains modeless and inserts characters directly:

• Text Mode (Default): Standard linear text editing for prose and code. Selections follow linear text streams.
• Canvas Mode (F8 or M+V): Unlocks 2D virtual space navigation beyond line ends. Supports 2D lines (Shift+Arrows), lines with arrows (Ctrl+Shift+Arrows or Ctrl+Arrows), block copy (M+W), block cut (^K), and block paste (^U) without distorting surrounding text layout.

For details on selection rules and clipboard separation, see Mark, selection, and canvas behavior.

You can use the F7 or M+T to enter Table Mode. In Table Mode, the cursor moves between table cells, and the table borders are preserved. Press F7 again to exit Table Mode and return to Text Mode or Canvas Mode.

zago is still a text editor. The diagram tools sit on top of ordinary prose editing rather than replacing it:

• Linear text selection in Text Mode and Table Mode, including Shift+Arrow and Shift+Home / Shift+End, with selected text replaced by typing.
• Nano compatible syntax highlight: You can use the syntax highlight configuration files for Nano in zago, just edit .zagorc like .nanorc.
• Paragraph justification (^J) for mixed CJK and Latin prose, using display width instead of byte or scalar counts.
• Selection-based text transforms from the Tools menu: Traditional/Simplified Chinese conversion, Latin/Hiragana/Katakana/Romaji transliteration, and CJK/ASCII spacing normalization.
• Text counts from the Tools menu. With a selection, Word Count reports that selection; without a selection, it reports the whole document. The status includes chars, words, lines, and only shows CJK chars or emojis when present.
• Optional sub line numbers for fixed-width prose drafting: when a wrap column is set, long physical lines can show visual-row numbers and paragraph character counts.
• Document link navigation with M+O for local Markdown, Org, reStructuredText, and AsciiDoc links.
• Heading navigation and outline picker for Markdown, Org, reStructuredText, and AsciiDoc documents.

zago supports a simple IPC protocol for AI agents to inspect the current buffer and propose LOGO commands to transform it. The let AI agents know how to interact with zago, please install the skill and mcp server:

zago --install-skill

To enable IPC mode, run zago with the --ipc flag.

zago --ipc notes.txt

Then, you can use prompts like Write a summay of the current file using zago skill to let the AI agent propose an update. When the AI agent sends the proposal, you can use Meta+A key to accept the proposal and apply the changes to the buffer.

Press Esc to enter the command prompt. Commands use Editor LOGO syntax for editing actions, shape generation, and turtle graphics:

• Box & Fill:

  BOX 30 5 CENTER ROUND
  DRAWBOX 30 4 ROUND
  GOTO 2 2
  FILL "hi
  

• Movement & Text Insertion:

  MOVE HOME  TYPE "Hi MOVE END
  

• Loops & Lists:

  REPEAT 5 [ TYPE :# ". List item" NL ]
  

• Procedures:

  TO TITLE :text
    BOX :text CENTER ROUND
  END
  

• ASCII Architecture Diagram:

  DRAWBOX 18 3 "client" CENTER GOTO 3 11 VLINE 3
  GOTO 5 1
  DRAWBOX 18 5
  GOTO 6 2 TYPE "     server     "
  

  ┌────────────────┐
  │     client     │
  └─────────┬──────┘
            │
  ┌─────────┴──────┐
  │     server     │
  └────────────────┘
  

For the complete command reference, see Editor LOGO Documentation and the User Manual (繁體中文手冊).

zago has the feature to debug LOGO code and lookup built-in primitives and custom procedures. By default the debugger and error output are hidden, but you can type set debug on in the command bar to enable them.

You can use the logo break command in the command bar to add or remove a break point. When the program stops on a break point, you can use commands like logo continue, logo step, logo abort and logo eval to control the debugger.

To know the details of a LOGO primitive, just type help-cmd in the command bar. For example: help-cmd BOX.

zago operates as an interactive TUI editor, a system $EDITOR, and a headless Unix pipe filter.

Open files, jump to specific lines, edit piped stdin streams, or use zago as export EDITOR=zago:

# Open one or more files in the terminal TUI editor
zago notes.txt file2.txt --wrap 80 --ruler

# Open file and jump directly to line 42, column 10
zago +42:10 notes.txt

# Open files in read-only mode
zago -R /var/log/syslog

Execute LOGO scripts or inline LOGO code on stdin piped text or files without opening a TUI window, printing the resulting ASCII output directly to stdout:

# Pipe stdin text into LOGO filter and wrap it in an ASCII box
uptime | zago -e "box buffertext"

# Execute inline LOGO code and print output
zago -e "BOX 20 4 GOTO 2 2 INSET \"Hello World\""

# Process input file with a LOGO script and redirect output
cat data.txt | zago -s format_report.logo > diagram.txt

# Pipe generated diagram directly to clipboard
zago --run generate_architecture.logo | pbcopy

You probably don't.

In agent-facing Markdown, the source is the interface. AI agents read the Markdown itself; they do not need a rendered HTML preview. zago focuses on making that source easier to write, shape, and maintain.

For the same reason AI agent CLIs exist: the terminal is still the shortest path between code, files, tools, and remote machines.

The features I want are not just Markdown syntax helpers. They touch the editor's interaction model: Text Mode and Canvas Mode, table-cell editing, rectangular canvas blocks, LOGO commands, selection-based text tools, status lines, menus, and key bindings.

In a powerful plugin ecosystem, that kind of opinionated workflow can easily fight the host editor, existing user habits, and other plugins. zago keeps the surface smaller so these pieces can be designed as one coherent Markdown writing flow.

因為我不會。

Yes. BTW, I am an 80s kid. :p

Also, LOGO is still a pretty good little language for movement, repetition, shapes, and text macros.

Type spaces over it, or use Canvas Mode block cut when the shape is rectangular.

• User Manual / 繁體中文使用手冊
• Editor basics
• Search behavior
• Mark, selection, and canvas behavior
• Editor LOGO command language
• Configuration and key bindings
• Pen mode and turtle drawing
• Diagram snippets & menu rules
• Spell checker architecture & plan
• File encoding & auto-detection
• Homebrew tap
• Release & preview builds
• Changelog

Run swift test.

MIT License. Copyright (c) 2026 Weizhong Yang a.k.a. zonble.

Note: The name zago stands for "zonble's nano + LOGO".