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 or source extensions.
  • 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.

TUI keybindings

Browsing and display

Key Action
j, ↓ / k, ↑ Select next/previous node
l, →, Enter Expand selected node
h, ← Collapse selected node
Home / End Select the first/last visible node
PageUp / PageDown Scroll the selected node's body by one page
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-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 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

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 12, 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 12, 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.1.1-py3-none-win_amd64.whl (2.0 MB view details)

Uploaded Python 3Windows x86-64

leo_cub-0.1.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.4 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

leo_cub-0.1.1-py3-none-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

leo_cub-0.1.1-py3-none-macosx_10_12_x86_64.whl (2.2 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: leo_cub-0.1.1-py3-none-win_amd64.whl
  • Upload date:
  • Size: 2.0 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.1.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 1a6bd3e515e46a17e7cb3d1e67f9df9a83a4eb75e15262490398f38942c4997d
MD5 6a8f779dc48c6452256ec44a4f197a4f
BLAKE2b-256 9cef21518fa9ce9c30dcd69bcefa62ef013a1120977f788f0ad0bf304e7da2d4

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.1.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.1.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for leo_cub-0.1.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a1184c2c2e3ad1e70b4a545ea455093cdd6d8dc3fc59957e1e3262b7ef832b8d
MD5 71a57738dd5caec6d4b6caf88e2f01af
BLAKE2b-256 bd1d01a076d5217c8fbfc1f35cec7c3b087fe75c27a71d5678bd73eff1c23f18

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.1.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.1.1-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for leo_cub-0.1.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2e7acc957e5e92cdc836e118551012292a34faa312a1bdbec425751715a3679f
MD5 705f37fa676754c7e1974c555e5d1b57
BLAKE2b-256 762a65ac9f8dce0fd81d6419010b19f2d28d8065667d28749aae37655d1c8e72

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.1.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.1.1-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for leo_cub-0.1.1-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f01796af68666a8acf092be4326687a2ca48d030bf5b41856ab74c91cbbab1d1
MD5 7e60367f491ae9e4a545fbc285c2c7ea
BLAKE2b-256 7d923204c77b0b42f27f88aa8218f3307ad4160682434c931bdeb0bb1c4d234d

See more details on using hashes here.

Provenance

The following attestation bundles were made for leo_cub-0.1.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

0.2.1

4 files

This release

0.1.1 This release

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