Johannes Kaindl Uplink Deutsch

Koda

Most "AI in Obsidian" plugins are a chat window that happens to sit next to your notes. Koda is the other kind: an assistant that can actually do things in the vault — search it, read from it, write to it — while the model runs on your own machine. The name is Lakota for friend, and it sets the register deliberately. This is not an oracle you consult; it is something that lives in the vault with you and works on the same material.

Why this one

The design question that shaped everything was not "how do we give a model tools" — that part is well-trodden. It was where the line sits between convenience and consent.

An agent that must ask before every action is exhausting, and people click through the prompts without reading them, which is worse than not asking. An agent that writes freely is unusable in a vault that holds years of your own thinking. The resolution was to make the boundary spatial rather than procedural: Koda has its own folder, where it may write on its own. Everywhere else, a write goes through a confirmation showing the actual diff. Not a summary of the change — the change. One rule, visible in the file tree, that you can reason about without reading a settings page.

The second decision was to make the learning legible. Koda remembers things across sessions, and that memory is a plain Markdown note in your vault. You can read it, correct it, or delete a line you disagree with. Nothing about what the assistant "knows" lives in a database you cannot open. It is the same instinct as the write rule: whatever the thing does to your vault should be something you can see in the vault.

And one thing it will never do: run commands. No terminal, no shell, no full system access — not as a setting, not behind a warning. An assistant with a shell is a different product with a different risk profile, and the boundary is worth more than the capability.

Under the hood

A pure core with no Obsidian imports — the agent loop, the tool definitions, the write policy, memory and session storage — testable in Node without a DOM and enforced by a build gate. Four tools, deliberately few: search notes, read a note, write a note, save a memory. Sessions are append-only JSONL, so a conversation is a file rather than a blob. Bilingual (English / Deutsch), following Obsidian's own language setting. Local-first: LM Studio, MLX or Ollama; the model list is read live from the endpoint and no model name is hard-coded.

The parts that were hard were not the agent loop. They were the things only real use surfaces. A response timeout measured from the start of the request will cut a healthy answer off mid-sentence when a large vault makes the model think for two minutes — so it measures silence instead of duration. And when a model aborts a tool call halfway, it leaves an empty argument string in the transcript, after which the endpoint rejects every subsequent request in that session. That one was isolated at the endpoint, character by character, and repaired at the transport edge, which means a conversation that already went wrong heals itself. Neither failure was reachable by a test suite; both were measured, not guessed.

Online repository

github.com/johannes-kaindl/koda-agent: source, releases and the technical detail.


See also: zettelkasten · Setup help: run your own local LLM