Kimün (Mapudungun): Knowledge, learning, or wisdom.

Kimün is a lightweight, fast, terminal-based notes application focused on simplicity and powerful search. Local-first; you own the notes.

It doesn't try to be a bloated, all-in-one life-management tool or a second brain (some of us struggle with a single brain already!). Instead, it serves as a minimalist local-first vault that seamlessly weaves into your existing developer terminal environment. Because your notes are stored as plain Markdown files, it plays beautifully alongside tools like Obsidian, Logseq, or QOwnNotes giving you a fast TUI/CLI alternative right in your shell.

USERS BEWARE: Kimün is in heavy development; configuration and custom themes may break with newer updates. If the app fails to start after an update, remove your configuration file so a new one is generated.

🚀 Quick Start

Two commands and you're taking notes:

# 1. Install (macOS & Linux)
curl -fsSL https://kimun.2co.dev/install.sh | sh

# 2. Run
kimun

First launch greets you with a little setup screen — point it at a folder for your notes and you're in. Hit Ctrl+K to search, Ctrl+W to jot something down. That's it, really.

Want the fancy extras — searching notes by meaning and asking questions that get answered from your own notes? That's the optional server. One more command:

# 3. (Optional) Semantic search & Ask — installs the server and runs it on login
curl -fsSL https://kimun.2co.dev/install-server.sh | sh -s -- --service

Then tell Kimün where to find it: Preferences (Ctrl+,) → Server → http://localhost:7573. Kimün works exactly the same without it — just a little less magic. Heads up: the server downloads its embedding model on first start (a few hundred MB), so give it a minute.

Prefer Homebrew, Cargo, or Docker? All the options are in Installation below.

📖 Documentation

Do you want to know more? ⭐️🚀 Check out our official documentation site for complete user guides, advanced setup steps, and integration tips:

👉 Read the Full Documentation Here

Key Features

  • Blazing Fast Search: Local Markdown files are automatically indexed into a local SQLite database for (almost) instantaneous full-text, structured, and fuzzy search.
  • Semantic Search & Ask (optional): Run the companion Kimün server to search notes by meaning and ask natural-language questions answered from your own notes (RAG) — local embeddings, local or cloud LLM, your choice.
  • Zettelkasten-Ready Linkages: Seamlessly navigate your knowledge base using [[wikilinks]] and standard Markdown links with intuitive keyboard shortcuts. Includes backlink support with interactive previews!
  • AI & MCP Native: Equipped with a dedicated Model Context Protocol (MCP) Server and LLM tools. Let your local or cloud AI models (like Claude Code) scan your notes, run daily reviews, update journals, or synthesize concepts directly.
  • Two Interfaces:
    • TUI (Terminal User Interface): An elegant, interactive pane for capturing thoughts, browsing workspaces, and previewing files.
    • CLI (Command Line Interface): Fully scriptable. Pipe outputs, log entries via cron jobs, and manipulate entries using jq and shell tools.
  • Workspaces in Context: Effortlessly separate your notes into distinct contexts (e.g., Personal vs Work) using multiple independent vaults.
  • Vim ready: Power users rejoice! You can navigate with HJKL and more with either:
    • Vim emulation: fully baked in in the app, you have Vim motions, vim Visual mode, even replace mode, and more! While having the rich editor capabilities.
    • Embedded Neovim Mode: In case you want to use your own config from Neovim, you can use Neovim in embedded mode too.

How the TUI looks

Installation

Install script (macOS & Linux)

curl -fsSL https://kimun.2co.dev/install.sh | sh

Installs the latest release into ~/.local/bin (override with KIMUN_INSTALL_DIR) and enables in-app self-update. The script verifies the download's SHA-256 before installing. Prefer to inspect first:

curl -fsSLO https://kimun.2co.dev/install.sh && less install.sh && sh install.sh

Homebrew (macOS & Linux)

brew tap nico2sh/kimun
brew install kimun

Cargo (Rust Ecosystem)

cargo install kimun-notes

Try It Out

Explore Kimün immediately using the pre-configured environments located inside the example/ directory. It comes loaded with interconnected personal and work notes, journals, and incoming inboxes:

# Launch Kimün in the sample workspace
kimun --config ./example/config.toml

⌨️ TUI Keyboard Shortcuts

Shortcut Action
Ctrl + K Global fuzzy search (Telescope-like)
Ctrl + N Follow [[wikilink]] under cursor
Ctrl + G Leader gateway (e.g. Ctrl + G then l b opens Backlinks)
Ctrl + E Open the file browser drawer
Ctrl + T Toggle the sidebar drawer
Ctrl + W Quick Note — immediately capture thoughts to your inbox
F4 Switch Workspaces (e.g., Toggle Personal / Work)

🤖 Automating with CLI & AI (MCP)

The Power of the CLI

Because Kimün is fundamentally a CLI tool, you can easily pipeline your notes into automation workflows:

# Quick log to your daily journal from a shell workflow
echo "Finished deploy script successfully" | kimun journal append

# Search your notes structurally
kimun search "refactoring" --json | jq '.[].path'

Model Context Protocol (MCP) & LLMs

Kimün bridges local notes with next-generation AI assistants. Using its native MCP Server, AI agents (such as Claude Code) can natively view, update, query, and synthesize your thoughts.

  • Scan & Synthesize: Ask an LLM to read a week's worth of journal logs and pull out action items.
  • Brainstorm: Ground an agent's reasoning inside your existing knowledge vault to avoid hallucinations.
  • Auto-organize: Let AI tools suggest unlinked but highly relevant notes.

Check the docs to learn how to set up the MCP server, here is an example for Claude Code integration:

# Claude Code (one-time setup)
claude mcp add kimun -- kimun mcp

If instead, you are skills person (or both!), just copy the skills into your preferred agent harness tool:

# Copy the skill to your Claude skills directory
cp -r skills/kimun-cli ~/.claude/skills

(Want to check out or share prompts? See the available definitions in the /skills directory!)

Semantic Search & Ask (RAG Server)

The optional Kimün server adds semantic search (find notes by meaning) and Ask — questions answered from your notes with sources cited — to the TUI. It is push-only (never reads your disk), hosts many vaults at once, and can run fully local: embedded SQLite + local embeddings, with an optional LLM (Claude, OpenAI, Gemini, Mistral, or a local OpenAI-compatible endpoint) for question-answering.

# Install script (Linux, macOS Apple Silicon) — re-run to update
curl -fsSL https://kimun.2co.dev/install-server.sh | sh

# Run with working local defaults (SQLite + local embedder)
kimun-server --default-config

Also available as a Docker image (ghcr.io/nico2sh/kimun-server) and via cargo install — see the server README for those.

Then point Kimün at it: Preferences → Server, or kimun_server_url = "http://localhost:7573" in the [global] section of your config. Full details in the server README and the documentation site.

Contributing

Who doesn't love open-source contributions! Whether you want to submit a bug fix, optimize the SQLite indexing, polish the text layout engine, or share an LLM Prompt template/Skill, you are welcome here.

  1. Fork the repository.
  2. Create your feature branch (git checkout -b feature/amazing-idea).
  3. Commit your changes (git commit -m 'feat: Add amazing feature').
  4. Push to the branch (git push origin feature/amazing-idea).
  5. Open a Pull Request.

Credits

Kimün stands on the shoulders of giants in the terminal and note-taking ecosystem: