<div align="center">
<img src="assets/logo.png" alt="Kimün Logo" width="80" height="80" />
<h1>Kimün</h1>
<p><strong>Simple note-taking. Powerful search. AI-ready.</strong></p>
<p>
<a href="https://nico2sh.github.io/kimun/"><img src="https://img.shields.io/badge/docs-github%20pages-brightgreen?style=flat-square" alt="Documentation"></a>
<a href="https://github.com/nico2sh/kimun/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
<a href="https://crates.io/crates/kimun-notes"><img src="https://img.shields.io/crates/v/kimun-notes?style=flat-square&color=orange" alt="Crates.io"></a>
<a href="https://github.com/nico2sh/kimun/stargazers"><img src="https://img.shields.io/github/stars/nico2sh/kimun?style=flat-square&label=stars" alt="Stars"></a>
<a href="https://ratatui.rs/"><img src="https://img.shields.io/badge/Built_With_Ratatui-000?logo=ratatui&logoColor=fff", alt="Built With Ratatui"></a>
</p>
<em><strong>Kimün</strong> (Mapudungun): Knowledge, learning, or wisdom.</em>
</div>
---
**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.
---
## 📖 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](https://nico2sh.github.io/kimun/)**
---
## ✨ 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.
* 🗺️ **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.
* 🟢 **Embedded Neovim Mode:** Power users rejoice! Utilize standard `HJKL` navigation, native motions, and search-and-replace routines without breaking context.
---
### 📸 How the TUI looks
<div align="center">
<img src="assets/screenshot.png" alt="Kimün Notes Preview and Search Panel Screenshot" width="100%" />
</div>
---
## 🚀 Quick Start
### Installation
#### Homebrew (macOS & Linux)
```bash
brew tap nico2sh/kimun
brew install kimun
```
#### Cargo (Rust Ecosystem)
```bash
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:
```bash
# Launch Kimün in the sample workspace
kimun --vault ./example
```
---
## ⌨️ TUI Keyboard Shortcuts
| 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:
```bash
# Quick log to your daily journal from a shell workflow
# Search your notes structurally
```
### 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 logs to learn how to set up the MCP server, here is an example for Claude Code integration:
```bash
# 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:
```bash
# 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!)*
---
## 🤝 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 'Add amazing feature'`).
4. Push to the branch (`git push origin feature/amazing-idea`).
5. Open a Pull Request.
---
## 🏆 Credits & Inspirations
Kimün stands on the shoulders of giants in the terminal and note-taking ecosystem:
* **UI/UX Foundations:** Built with [Ratatui](https://github.com/ratatui/ratatui) & `ratatui-textarea`.
* **Search Mechanics:** Powered by [Nucleo](https://www.google.com/search?q=https://github.com/0x0ac/nucleo) for ultra-fast fuzzy matching, and `ignore` for rapid directory walking.
* **Editor Integration:** Leverages `nvim-rs` for Neovim synchronization workflows.
* **Inspiration:** Heavily inspired by Obsidian, Logseq, and QOwnNotes.
---