leo-cub

leo-cub is an experimental Rust library and command-line tool for reading, validating, browsing, and modifying Leo Editor outlines.

The installed command is cub; the Rust library namespace is leo.

Screenshot

image

Why

Leo outlines are not ordinary XML trees. A GNX identifies shared vnode content, while an outline position identifies one occurrence of that vnode. Cloned nodes can therefore appear in several places. leo-cub keeps those concepts separate and exposes transactional operations intended for scripts and AI tools.

Current features

  • Parse and validate .leo XML outlines.
  • Preserve XML outside the rewritten <vnodes> and <tnodes> sections.
  • Represent clone identity separately from outline positions.
  • Apply atomic JSON operation batches with optional text preconditions.
  • Parse Leo 5 thin derived-file sentinels.
  • Reconstruct @file, @thin, and @file-thin hierarchies and bodies.
  • Resolve ancestor @path directives in the TUI.
  • Browse outlines with a small Ratatui interface.
  • Highlight node bodies with Syntect, using @language, @rst ancestors, or source extensions, including bundled reStructuredText syntax support.
  • Open a derived node's full source file at its sentinel line using $VISUAL or $EDITOR.

Install

The recommended installation method is uv:

uv tool install leo-cub

This installs the cub command. You can also use pip install leo-cub, or download the appropriate archive from the latest GitHub release.

Installation from source

From the repository root, install the cub command with Cargo:

cargo install --path .

Install the bundled local agent skill after installing the command:

cub install-skills

This writes ~/.claude/skills/leo-cub/SKILL.md and overwrites an existing copy, so it is safe to rerun after upgrading.

TUI

cub tui outline.leo

The browser resolves external thin files in memory. Outline headlines highlight Leo directives, external-file names, and section-reference markers. A red * marks each node changed since the outline was loaded or last saved; saving or reloading clears the markers.

TUI keybindings

Browsing and display

Key Action
↓ / ↑ Select next/previous node
→, Enter Expand selected node
← Collapse selected node
Home / End Select the first/last visible node
PageUp / PageDown Scroll the selected node's body by one page
f Toggle a full-width body pane
Shift-F Toggle a full-width outline pane
↑ / ↓ in full-width mode Scroll the body vertically by one line
← / → in full-width mode Scroll the body horizontally
Ctrl-P Find a headline incrementally; use ↑/↓ to cycle matches
o Edit the node body in $VISUAL/$EDITOR; for derived nodes, open the real source at its sentinel
y Toggle syntax highlighting
? Show command help

Outline editing

Key Action
Ctrl-I or Tab Insert a new sibling and enter headline editing
Ctrl-H or Backspace Edit the selected headline
Ctrl-↑, Ctrl-↓ Move among siblings
Ctrl-←, Ctrl-→ Promote or demote the selected node
Ctrl-R Reload from disk; press twice to discard unsaved changes
Ctrl-S Save outline changes
q or Esc Quit; press twice to discard unsaved changes

Headline editing

Key Action
Printable characters Append to the headline
Backspace Delete the previous character
Enter Accept the headline
Esc Cancel editing; a newly inserted node is removed

Use --no-derived to display only the hierarchy physically present in the .leo XML file.

For source navigation, cub recognizes common position arguments for Vim, Neovim, Nano, Emacs, VS Code, Microsoft Edit, Helix, and Kakoune. Other editors receive the file path without a line argument.

Headless commands

cub inspect outline.leo
cub inspect outline.leo src/main.rs
cub inspect outline.leo --gnx ekr.20260811210000.1
cub inspect outline.leo --position 0/2/1
cub inspect outline.leo --search 'render_(compact|json)'
cub inspect outline.leo --search TODO --search FIXME
cub inspect outline.leo src/main.rs --format json
cub validate outline.leo
cub import outline.leo src --recursive --mode auto --paths
cub import outline.leo README.md --mode edit --no-paths
cub sync outline.leo
cub sync outline.leo src/main.rs --dry-run
cub sync outline.leo --gnx ekr.20260811210000.1
cub diff before.leo after.leo
cub inspect-derived path/to/derived.py --summary
cub apply outline.leo operations.json --dry-run

import creates Leo external-file nodes in auto, edit, or clean mode. Markdown, Python, Rust, C#, Go, JavaScript/JSX, and TypeScript/TSX @auto files are expanded transiently with Tree-sitter when they are loaded by inspect or the TUI; the generated tree is not stored in the .leo file. Unsupported source types remain available as a plain root node. Markdown also supports Leo's @auto-md and @auto-markdown headlines and leo-noheader markers. Directory imports are recursive only with --recursive and preserve their layout with @path nodes by default. Use --no-paths to put all imported files directly below the destination, --parent GNX to choose that destination, and --dry-run to validate without saving.

inspect uses a compact text format containing position paths, GNXs, headlines, and bodies. Repeated clone content is shown as =GNX. Use --format json for structured output in scripts. --search accepts a Rust regular expression and searches headlines and body lines. Search results include line-numbered excerpts with two surrounding lines instead of printing entire matching bodies. Repeat --search to match any of several expressions. Thin external files are scanned first and reconstructed only when they may contain a search or GNX match.

An operation batch is a JSON object:

{
  "operations": [
    {
      "op": "set-body",
      "node": "ekr.20260811210000.1",
      "expected": "old body",
      "body": "new body"
    }
  ]
}

Operations are applied to a copy and committed only if the complete batch is valid. expected provides optimistic conflict detection for headline and body edits.

Status and safety

This project is early and the file format support is incomplete. In particular, it does not yet write thin derived files, dynamically interpret every @comment/@delims change, or fully reconstruct all doc-part forms. Keep backups and use --dry-run when testing write operations on important outlines.

The TUI overlays derived files without modifying either the outline or external source files. Derived descendants are read-only in the outline editor; use o to edit their full external source. Unsaved outline changes require a second q before they are discarded.

License

MIT

Project links

Data verified by PyPI on Aug 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for vivainio from gravatar.com vivainio

Credits

Author: Ville Vainio

GitHub Statistics

Data verified by PyPI on Aug 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License, MIT License (MIT OR Apache-2.0)

Requires

Python >=3.10

Tags

leo-editor outline cli tui automation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

leo_cub-0.2.1-py3-none-win_amd64.whl (3.3 MB view details)

Uploaded Python 3Windows x86-64

leo_cub-0.2.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

leo_cub-0.2.1-py3-none-macosx_11_0_arm64.whl (3.5 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

leo_cub-0.2.1-py3-none-macosx_10_12_x86_64.whl (3.5 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file leo_cub-0.2.1-py3-none-win_amd64.whl.

File metadata

  • Download URL: leo_cub-0.2.1-py3-none-win_amd64.whl
  • Upload date:
  • Size: 3.3 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for leo_cub-0.2.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 ada125132e77e747563a346922bb86eb8f63088ce51d7e0f32c85f92da60b763
MD5 4a09fb3231b43d1d9fc338a8b37ef64a
BLAKE2b-256 9cbe55c9372475df603a73162e227cee43082ee75be0e6a1d79761f52ca67ed5

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.2.1-py3-none-win_amd64.whl:

Publisher: release.yml on vivainio/leo-cub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file leo_cub-0.2.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for leo_cub-0.2.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2c52339cc563f7f94de0389ef66adfc52639e3d83d6f2c0c6ce059f15db28e6e
MD5 9f0038bbba802df4302fafb1fc108cd4
BLAKE2b-256 3e04ee77d8f58c5bd9221db7b3da771f776b52e5211bb14c895c80009ec716f4

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.2.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on vivainio/leo-cub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file leo_cub-0.2.1-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for leo_cub-0.2.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6a831d4b01603e5adf93693f3f20800cca4c66fb219fdbbb58e7e080c5b668e8
MD5 77ee117acfd53845f453f9aa02294b6a
BLAKE2b-256 b002699945a34874500a6757c35dd3d30babe7bb418515cf9be02f341e5e05df

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.2.1-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on vivainio/leo-cub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file leo_cub-0.2.1-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for leo_cub-0.2.1-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6d36257c749353cac87bcb84ca337b0af0be69ec56026b7530db154f9d5b6d1d
MD5 8d84b9274857601c82b5dc69ce23ba94
BLAKE2b-256 838b4086c20f5adfbbafe896c59ddc316a1dce8daee280dac89806b7fa86fcea

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.2.1-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on vivainio/leo-cub

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.0

5 files

0.2.2

5 files

This release

0.2.1 This release

4 files

0.1.1

4 files

0.1.0

4 files

0.0.2

4 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page