Your private workspace for thinking, writing and AI.

Koru is a private, local-first AI workspace

Koru is an open-source, local-first workspace for thinking, writing and working
with AI. Documents, files and terminal sessions, including your shells and AI
coding agents, open as tabs in one native window. Your work stays on your own
devices, works offline, and syncs directly between them, with no cloud server
holding your data.

What can you do with Koru?

• Write and organize: documents with headings, tables, checklists, code,
  images and attachments, nested in a tree, with full-text search, #tags and
  named versions you can compare.
• Work with AI on your terms: open Claude Code, Codex, Gemini and other
  coding agents as tabs beside your documents, and let any MCP client, including
  a local model, read and edit your workspace through Koru's built-in MCP server.
• Bring your notes with you: import from Evernote (.enex), Notion,
  OneNote, Google Docs, Markdown and TextBundle, and export to Markdown or
  TextBundle at any time.
• Speak instead of type: Koru Voice dictates on your own device; your audio
  never leaves it.
• Keep it yours: free, no account required, and open source under the
  MPL-2.0.

What is Koru an alternative to?

Koru is a private, local-first alternative to cloud note-taking and document
apps. Your documents, files and AI agents stay on your own devices, work
offline, and sync directly between them, with nothing stored on someone else's
server.

• Evernote alternative: your
  notes live on your own devices instead of Evernote's cloud, and they're fully
  available offline.
• OneNote alternative: you don't
  need a Microsoft account or OneDrive, because devices sync peer-to-peer.
• Notion alternative: it's built
  to work offline first, and it syncs device to device instead of through a
  cloud server.
• Google Docs alternative: your writing stays private on your devices, with
  no Google account and no cloud storage.

Does Koru work offline?

Yes. Koru stores every workspace on your own devices, so you can read and write
without an internet connection (an AI agent still needs whatever connection its
own model needs). When your devices reconnect, they sync directly with each
other, peer-to-peer. No cloud server stores your data, and sync traffic is
end-to-end encrypted, including when a relay has to forward it between networks.

How does Koru sync without a server?

Koru stores each workspace as a Loro snapshot. Loro is a
CRDT (conflict-free replicated data type), so two devices editing the same
workspace always end up in the same state without a server to coordinate them.
If you only use one device, Koru never exchanges an operation, so the sync
option costs you nothing.

How is a Koru workspace structured?

A Koru workspace is a tree of typed nodes: documents, tasks, contacts and
images. Their attributes are stored as structured data rather than plain text,
and each view, such as a list, a table or a document, is a projection over that
one model.

What is Koru built with?

The Koru desktop app is written in Rust. It uses
parley for text layout,
vello for GPU rendering, winit for
windowing, and iroh for device-to-device sync. The iOS
and Android apps are native Swift and Kotlin, built on the same contracts.

Status

Pre-1.0 and moving quickly. The first public release shows documents, files,
and terminal sessions for your shells and AI coding agents. More is built than
is shown: tasks, the Koru AI chat, the Agents and Artifacts views, canvases,
reminders and Koru Cloud sign-in sit behind product flags that are off unless a
build turns them on
(product feature flags). The
user guide describes the available behavior and
experimental features.

Build and run from a fresh clone

You need:

• Rust, from rustup. The checked-in
  rust-toolchain.toml selects Rust 1.99.0 for development and release builds;
  rustup installs it automatically. The minimum supported version is 1.92,
  declared in Cargo.toml and tested in CI. Windows also needs the MSVC build
  tools.
• sccache, which is not optional: .cargo/config.toml sets it as the
  compiler wrapper. winget install Mozilla.sccache, or cargo install sccache.
• A GPU with DX12, Vulkan or Metal. vello renders with compute shaders and
  has no software fallback.
• Python 3, for the repository's checks under scripts/checks/.

Then, on Windows:

git clone https://github.com/koruworks/mono.git koru
cd koru
koru.bat setup   REM sets up whatever is not set up yet, and lists what it could not
koru.bat run

./koru.sh setup and ./koru.sh run are the same on macOS.

setup installs sccache; sets its cache directory, cache size and the cargo job
count for this machine (user environment variables on Windows, a marked block in
your shell profile elsewhere); and fetches fonts and third-party code. What is
already set up it leaves alone, and whatever it cannot do it lists with the
command that does it. Run it again at any time: it does only what is still
missing, and retries what failed. setup --check reports without changing
anything, including when combined with the optional flags below.

Two setup options are available separately:

• koru.bat setup --defender-exclusions: recommended for faster builds
  in a trusted local checkout after reviewing the trade-off. Windows asks for
  elevation. It disables Defender scanning for the repository, worktrees,
  Cargo dependency sources, and compiler cache. Leave it off when reviewing
  untrusted contributions. scripts/setup/defender-exclusions.ps1 -Remove
  reverses the exclusions.
• koru.bat setup --agent-skills (or ./koru.sh setup --agent-skills):
  install coding-agent skills and the Git hook that installs them in new
  worktrees. This requires Node.js and runs the skills CLI. Its anonymous
  install telemetry can be disabled with DISABLE_TELEMETRY=1.

Ordinary build, test, and run commands do not install agent tooling or change
Git hooks. Both optional flags can be combined on Windows.

run downloads the bundled fonts on first use (koru.bat fonts does just that
step; the faces are pinned by hash in scripts/setup/fonts.manifest), compiles, and
launches. The first compile takes several minutes and everything after it is
incremental. Fetch the fonts before running the tests on a fresh clone, or
the typography tests fail.

Every launcher verb also fetches three crates Koru builds from patched source
(onenote_parser, sherpa-onnx, sherpa-onnx-sys) from crates.io and applies
Koru's patches, which are all of them this repository holds
(third-party/). To run cargo directly on a fresh
clone, run scripts\setup\fetch-third-party.ps1 (or bash scripts/setup/fetch-third-party.sh) once first. Without them cargo stops with
patch location ... third-party/crates/sherpa-onnx does not contain packages matching.

Coding agents get Koru's skills from
koruworks/skills (the document-driven
workflow: draft, review, plan, execute, hand off), installed with npx skills add into .agents/skills/, which .claude/skills links to; none of it is
committed. setup --agent-skills installs them and sets the Git hook that
installs them in every git worktree add after it. It needs Node.js for npx,
and nothing else needs the skills: without Node the build is unaffected. To take
a newer set, run sh scripts/setup/setup-skills.sh --update.

Koru Cloud is off in a build from source, and that is expected. With no
.env.production at the repository root, run starts with Koru Cloud not
configured and says so in one line; the app works in full on its own device and
syncs directly between your devices. To point a build at a Koru Cloud of your
own, see CONTRIBUTING.md.

Usage telemetry is opt-in

A build from source has the same telemetry destination as an official one,
Koru's metrics service at https://m.koru.do, and the same rule: nothing is
sent until you agree. Koru asks once on each device. What it sends is which
features are used, how well the app runs, and basic facts about the device such
as its operating system and screen size; never your documents, their names or
anything you type. The Share usage data switch in Settings changes the answer
at any time. KORU_TELEMETRY_ENABLED=0 removes the destination altogether, and
KORU_TELEMETRY_BASE_URL points it at a service of your own
(reference/ENV.md).

Voice and agents need CMake and libclang

koru.bat run launches the app alone. Koru Voice, the agent host,
koru.bat run-all and packaging also link sherpa-onnx
for speech recognition, and whisper.cpp, which is compiled from source:

winget install Kitware.CMake LLVM.LLVM     REM CMake, and libclang for the bindings
koru.bat run-all

The launcher downloads sherpa-onnx's prebuilt archive the first time (about
117 MB) into third-party\sherpa-onnx\, and refuses it unless it matches the
hash Koru pins; a new worktree copies it from the main checkout instead. It is
upstream's build without text-to-speech: the ordinary one links eSpeak NG,
which is GPL-3.0, and Koru does not use it. Why, and what ships:
licensing/.

Tests, packages and phones

koru.bat test                  REM cargo test --workspace, the whole suite
koru.bat dist-local beta       REM an unsigned local package under dist\ (needs the voice archive)

Android needs JDK 17 and Android SDK 36. The Gradle wrapper is fetched, not
committed, so on a fresh clone run scripts\setup\fetch-third-party.ps1 (or
bash scripts/setup/fetch-third-party.sh) once, then cd apps/android and
./gradlew testDebugUnitTest assembleDebug. See the
contributor guides for testing and implementation
guidance, and the Android README for platform setup.

The launchers are thin: what they run lives under scripts/, in four folders.
setup/ fetches and builds what a fresh clone lacks (fonts, dictionaries, the
third-party code, the voice runtime, the skills) and checks the machine;
dev/ starts, stops, captures and probes the app while you work on it;
checks/ holds the repository's own checks (links, the publication scan, SPDX
headers, sign-off), which CI runs too; and icons/ regenerates the app and
mobile icons from the logo.

Where to go next

The user and contributor guides live in guide/, alongside
the source, and are available in every clone. Internal plans, ADRs, company
notes, and hosted-service operations remain in the private docs/ submodule.

Koru Cloud is not in this repository

Koru Cloud is the hosted service official builds can sign in to: accounts and
sync through the cloud. It is run by Koru
Works, Inc., and its server code, infrastructure and credentials are not part
of this repository. Everything the apps link is here, including the client side
of Cloud and the wire contracts it speaks (contracts/), so a build from this
source can talk to any server that implements them — or to none.

Official builds are this source at a tag, built with configuration only we
hold: the Cloud origin, the update-signing key and the Google Docs importer's
registration. A build without them turns those features off and says so.

Share with the community

If Koru is useful to you, a post about it really helps a small, independent
project get found. Follow the build on X: @liechti_dev.

License

Koru is free software under the Mozilla Public License 2.0. Change a
Koru file and distribute it, and that file stays open; add your own files beside
ours under whatever license you like. Every commit is signed off under the
Developer Certificate of Origin; CONTRIBUTING.md says
how. Third-party components and what they require are listed in
licensing/.

The Koru name, logo and icons are trademarks of Koru Works, Inc. and are not
covered by the license; see TRADEMARKS.md.