Skip to content

getting-started.md

Latest commit

 

History

History
155 lines (105 loc) · 4.37 KB

getting-started.md

File metadata and controls

155 lines (105 loc) · 4.37 KB
Raw

Getting Started

Prerequisites

  • Kakoune v2026.04.12 or later (AUR package installs this automatically)

Installation

Arch Linux (AUR)

yay -S kasane-bin    # or: paru -S kasane-bin

Installs a prebuilt binary. Kakoune is pulled in automatically as a dependency.

macOS (Homebrew)

brew install Yus314/kasane/kasane

Installs a prebuilt binary. Kakoune is pulled in automatically as a dependency.

Binary Release

Download a prebuilt binary from GitHub Releases:

# x86_64 Linux (glibc) — replace the URL with your target from the releases page
curl -LO "$(curl -s https://api.github.com/repos/Yus314/kasane/releases/latest \
  | grep -oP 'https://[^"]*x86_64-linux-gnu\.tar\.gz')"
tar xzf kasane-*-x86_64-linux-gnu.tar.gz
install -Dm755 kasane ~/.local/bin/kasane

Other targets: aarch64-linux-gnu, x86_64-linux-musl, x86_64-macos, aarch64-macos. See the releases page for all available archives.

macOS and Linux x86_64 (glibc) builds include the GPU backend. Use kasane --ui gui to launch the GUI, or set backend "gui" in the ui section of kasane.kdl. Other targets (musl, aarch64-linux) are TUI-only.

From Source

git clone https://github.com/Yus314/kasane.git
cd kasane

# Default: TUI + WASM plugin support (cursor-line and color-preview bundled)
cargo install --path kasane

# Include the GPU backend
cargo install --path kasane --features gui

# Add tree-sitter syntax highlighting
cargo install --path kasane --features syntax

# Combine
cargo install --path kasane --features "gui syntax"

Requires Rust stable toolchain.

Slim-Build Matrix

The kasane binary composes from four optional feature flags:

Flag Default Adds
wasm-plugins on WASM plugin runtime (kasane-wasm) + bundled cursor_line / color_preview + the lock-file resolver + plugin reload watcher (notify). Disable with --no-default-features for a TUI-only build with native plugins only.
gui off GPU backend (kasane-gui: winit + wgpu + Parley + swash). Significantly larger binary.
syntax off Tree-sitter syntax highlighting (kasane-syntax). Pre-render hook attached automatically.
tui-image off (in kasane-core) TUI image protocol support (kitty / sixel). Off by default to keep kasane-core slim.

Common build invocations:

# Slimmest: TUI only, no WASM, no GUI, no syntax
cargo build --no-default-features

# TUI + WASM (the default)
cargo build

# TUI + WASM + syntax
cargo build --features syntax

# TUI + WASM + GUI + syntax (the maximum surface)
cargo build --features "gui syntax"

--no-default-features retires the entire kasane-wasm dependency (lock resolver, bundled plugins, hot-reload watcher) — useful for embedded targets or environments where the WASM runtime is not desired. Custom native plugins built via kasane::run() continue to work in this mode.

Nix

nix run github:Yus314/kasane

First Run

kasane file.txt

You should see your file in Kakoune — same keybindings, same behavior. Kasane connects to Kakoune via the -ui json protocol and renders the UI independently.

Making It Your Default

Add to your .bashrc or .zshrc:

alias kak=kasane

All Kakoune arguments work unchanged:

kak file.txt              # Edit a file
kak -c project            # Connect to existing session
kak -s myses file.txt     # Named session
kak -l                    # List sessions (delegates to kak)

Configuration

Kasane reads configuration and widget definitions from a single file:

~/.config/kasane/kasane.kdl

No config file is needed — all defaults match Kakoune's standard behavior. Create a config file only when you want to change something.

Example:

ui {
    shadow #false
    border_style "double"
}

scroll {
    smooth #true
}

See config.md for the full configuration reference.

Next Steps