Koru

Koru is a desktop-first, local document workspace.

It is built for documents you want to keep under your own control: contracts, invoices, certificates, scans, notes, PDFs, and other personal records. Import files, search names/text/OCR output, arrange documents on a visual board, tag them, restore them from Trash, and export the verified original bytes when you need them.

The desktop app is the primary product. The CLI is included for automation, maintenance, and recovery.

Download the latest release

What Koru does

• Native desktop workspace with a dark, desktop-first interface.
• Local library backed by SQLite and content-addressed blob storage.
• Search over filenames, tags, text-like files, PDF text layers, and OCR output.
• Visual document board, table view, inspector, status, settings, and Trash.
• Drag-and-drop and file-picker import.
• Open/export actions with source and stored SHA-256 verification.
• Backup, restore, doctor checks, OCR workers, and CLI workflows.

Koru has no account system, telemetry, hosted backend, cloud sync, sharing, collaboration, or mobile app. Your library stays on your machine.

Downloads

Use the repository Releases page:

https://github.com/Tunahanyrd/koru/releases/latest

Published desktop packages are:

• koru-vX.Y.Z-windows-amd64.zip
• koru-vX.Y.Z-macos-arm64.zip
• koru-vX.Y.Z-macos-amd64.zip
• koru-vX.Y.Z-linux-amd64.tar.gz

Each archive is published with a .sha256 checksum.

Windows

Download the Windows zip, extract it, and run:

• koru.exe for the desktop app.
• koru-cli.exe for terminal commands.

koru.exe is built as a Windows GUI application, so it should not flash a Command Prompt window when launched normally.

Windows packages are currently unsigned. Windows may show an unknown-publisher or SmartScreen warning on first launch. This does not mean the archive contents changed; verify the published .sha256 checksum before running the app. Removing that warning properly requires a paid public code-signing certificate, so Koru does not claim signed Windows distribution yet.

macOS

Download the archive for your CPU:

• Apple Silicon: macos-arm64
• Intel: macos-amd64

Extract it and run koru. Current macOS packages are portable command bundles, not a notarized .app installer.

Linux

Download the Linux archive, extract it, and run the included installer:

tar -xzf koru-vX.Y.Z-linux-amd64.tar.gz
cd koru-vX.Y.Z-linux-amd64
./install.sh

The installer places the binary in ${XDG_BIN_HOME:-$HOME/.local/bin}, registers a desktop entry, and installs the scalable icon. It does not remove or modify an existing Koru library.

The Linux package targets glibc-based amd64 desktop distributions with glibc 2.34 or newer, an X11 or Wayland session, and working OpenGL/EGL or Vulkan desktop libraries.

Quick start

Open the desktop app and drop files into the window. Koru stores the originals locally, indexes searchable content, and queues OCR work for PDFs/images when available.

By default, Koru uses a .koru directory relative to the process working directory. For a stable library location, pass --data-dir:

koru desktop --data-dir "$HOME/Documents/Koru Library"
koru import --data-dir "$HOME/Documents/Koru Library" ./contract.pdf
koru search --data-dir "$HOME/Documents/Koru Library" contract
koru export --data-dir "$HOME/Documents/Koru Library" 1 ./exports

Typical library layout:

.koru/
  koru.db
  blobs/
  derived/
  tmp/

Koru stores library data, metadata, search rows, OCR text, and backups in local plaintext. Treat the library directory like the original documents.

OCR

Koru can use Tesseract for image OCR. Install the language packs you need:

# Ubuntu / Debian
sudo apt install tesseract-ocr tesseract-ocr-eng tesseract-ocr-tur

# Fedora
sudo dnf install tesseract tesseract-langpack-eng tesseract-langpack-tur

The desktop app starts background workers automatically. For a headless library:

koru work --data-dir "$HOME/Documents/Koru Library"

CLI

Common commands:

koru version
koru desktop [flags]
koru import [flags] <path>
koru list [flags]
koru search [flags] <query>
koru export [flags] <document-id> [out-dir]
koru delete [flags] <document-id>
koru restore [flags] <document-id>
koru tag add [flags] <document-id> <tag>
koru tag remove [flags] <document-id> <tag>
koru tag list [flags] <document-id>
koru graph [flags]
koru ocr [flags] <pdf>
koru work [flags]
koru doctor [flags]
koru backup create [flags] <path>
koru backup restore [flags] <backup-path> <target-data-dir>

On Windows, use koru-cli.exe for CLI commands so koru.exe can remain the desktop launcher.

Build from source

Install the Go version declared in go.mod.

Linux desktop builds need Gio/X11/Wayland/EGL/Vulkan/WebP development packages:

sudo apt update
sudo apt install \
  gcc pkg-config \
  libegl1-mesa-dev libgles2-mesa-dev libvulkan-dev \
  libwayland-dev libx11-dev libx11-xcb-dev libxcursor-dev \
  libxfixes-dev libxi-dev libxinerama-dev libxkbcommon-dev \
  libxkbcommon-x11-dev libxrandr-dev libxxf86vm-dev libwebp-dev

Build and run:

go build -trimpath -o ./bin/koru ./cmd/koru
./bin/koru version
./bin/koru desktop --foreground

Build the Windows desktop launcher from Linux:

GOOS=windows GOARCH=amd64 CGO_ENABLED=0 \
  go build -trimpath -ldflags "-H=windowsgui" -o ./dist/koru.exe ./cmd/koru-desktop

Release packaging

Release archives are produced by .github/workflows/release.yml from an existing semver tag.

Windows signing is optional. If these repository secrets are present, the package script signs koru.exe and koru-cli.exe before creating the zip:

• WINDOWS_SIGNING_CERT_BASE64: base64-encoded .pfx/PKCS#12 code-signing certificate.
• WINDOWS_SIGNING_CERT_PASSWORD: certificate password.

Optional repository variable:

• WINDOWS_SIGN_TIMESTAMP_URL: timestamp server URL. If omitted, the package script defaults to DigiCert's timestamp endpoint.

Without a real public code-signing certificate, Windows packages remain unsigned and may show an unknown-publisher warning. A self-signed certificate is not a distribution-quality fix.

Tests

gofmt -w ./cmd ./internal
go vet ./...
go test ./... -count=1
go test -race ./... -count=1
bash integration/run_all.sh
(cd third_party/gio && go test ./... -count=1)
bash scripts/test-collect-licenses.sh
bash scripts/verify-pdfium-release-inputs.sh

CI runs formatting, vet, builds, unit/repository tests, race tests, integration tests, and local Gio fork tests. The release workflow also verifies the PDFium distribution inputs before publishing packages.

Reliability boundary

Koru separates original byte streams from user-facing document records. Equal imports can share one physical blob while keeping separate names, tags, and board positions.

Each blob records:

source_sha256 = sha256(original bytes)
stored_sha256 = sha256(stored blob bytes)

Export verifies the stored representation and the restored original. Overwrite export stages and verifies replacements before publishing them. Normal search excludes soft-deleted documents. Backup creation refuses targets that overlap protected live database, blob, or derived-data paths. Stored zstd extraction uses bounded decoder limits.

koru doctor provides quick/full checks and repair modes. Backup and restore are local recovery tools; they are not encrypted.

License and brand assets

Koru source code is licensed under GNU GPL version 3 only; see LICENSE.

The Koru logo, app icon, and brand artwork are not GPL-licensed. They are separate all-rights-reserved assets by @btdrws. You may install, run, back up, and redistribute an unmodified official Koru distribution with the original terms and attribution intact. You may not extract, modify, rebrand, or embed the artwork in another project without prior written permission.

Distributed forks must remove the protected brand assets and embedded vector coordinates and use their own identity. See assets/brand/REDISTRIBUTION.md.