Install and shortcuts

Everything from the README needed to get Kokuban v0.4 running and to learn its keys. The README remains the source of truth.

Install a release

Download the archive (or, on a Mac, the disk image) for your computer from the v0.4 release, along with its matching .sha256 file. Neither Rust nor Python is needed to run it.

Ubuntu 24.04 is the tested Linux distribution; build from source for other architectures or older distributions. macOS binaries target macOS 11. Disk images are ad-hoc signed, not notarized.

Linux (Ubuntu 24.04)

Install the runtime libraries and a monospace font:

1sudo apt update
2sudo apt install --yes libfontconfig1 libfreetype6 fonts-dejavu-core \
3  libx11-6 libxcursor1 libx11-xcb1 libxi6 libxkbcommon-x11-0

In the directory with the archive and checksum:

1sha256sum --check kokuban-v0.4-x86_64-unknown-linux-gnu.tar.gz.sha256
2tar -xzf kokuban-v0.4-x86_64-unknown-linux-gnu.tar.gz
3cd kokuban-v0.4-x86_64-unknown-linux-gnu
4./kokuban

macOS

Archive, Apple Silicon:

1shasum -a 256 --check kokuban-v0.4-aarch64-apple-darwin.tar.gz.sha256
2tar -xzf kokuban-v0.4-aarch64-apple-darwin.tar.gz
3cd kokuban-v0.4-aarch64-apple-darwin
4./kokuban

App: check the disk image, open it and drag Kokuban to Applications.

1shasum -a 256 --check kokuban-v0.4-aarch64-apple-darwin.dmg.sha256
2open kokuban-v0.4-aarch64-apple-darwin.dmg

On Intel Macs, replace aarch64-apple-darwin with x86_64-apple-darwin. The first launch may need Open from the Finder context menu or approval in Privacy & Security.

Updating

From v0.4, Kokuban checks the latest GitHub release in the background when it opens. Nothing downloads until you ask:

1kokuban --check-update   # report whether a newer release exists
2kokuban --update         # download, verify and install it

The update refuses the download unless the checksum matches. Turn the check off with check_on_startup = false under [update] in kokuban.toml, or set KOKUBAN_NO_UPDATE_CHECK=1.

Build from source

Install Git and Rust through rustup. The verified toolchain is Rust 1.94.1.

1sudo apt install --yes build-essential pkg-config libfontconfig1-dev libfreetype6-dev

1xcode-select --install

1git clone --branch v0.4 --depth 1 https://github.com/guicybercode/kokuban.rs.git
2cd kokuban.rs
3rustup toolchain install 1.94.1 --profile minimal
4rustup run 1.94.1 cargo build --release --locked
5./target/release/kokuban

Pick a shell with KOKUBAN_SHELL=/bin/bash. A minimal kokuban.toml:

1[font]
2# family = "DejaVu Sans Mono" # Optional explicit font.
3size = 14.0
4
5[images.kitty]
6allow_file_transfer = false

Omarchy and commands

1kokuban --working-directory="$HOME" -e nvim
2kokuban --app-id=org.omarchy.btop -e btop
3kokuban --help

Arguments after -e are passed unchanged; use sh -c for pipelines. See Omarchy installation and bindings.

Troubleshooting

• No Linux display. Start it inside an X11 or Wayland session; headless SSH cannot open a window.
• Missing library. Install the runtime packages above.
• Missing font. Install fonts-dejavu-core; fonts-noto-color-emoji adds emoji fallback.
• Shell fails to start. Set KOKUBAN_SHELL to an absolute executable path without arguments.
• Config ignored. A local kokuban.toml wins over the user config. Invalid config falls back to defaults with a warning.

Linux shortcuts

Plain Ctrl+C and Ctrl+V stay application input. Omarchy maps Super+C and Super+V to the Insert shortcuts.

macOS shortcuts

Pane, resize, zoom and prompt bindings are configurable. Cmd+C copies a selection or sends Ctrl+C when there is none; Cmd+V pastes. Linux does not implement the pane table yet.

Back to home Download v0.4