English | 中文

KiloCode for Obsidian

My Obsidian knowledge base, managed with KiloCode.

I have a knowledge base (Obsidian), I have an AI tool (KiloCode).
This plugin bridges them.

---

The Problem

Managing an Obsidian knowledge base is hard. As notes pile up:

• Notes become disconnected — knowledge silos grow
• Tags drift — the same concept ends up under different labels
• Weekly review becomes a chore — journals pile up without curation
• Knowledge accrual is manual — writing takes effort, organizing takes even more

I already use KiloCode CLI for coding. Now the same tool can help me manage my knowledge in Obsidian.

This plugin bridges my knowledge base with my AI tool.

---

What This Plugin Does

KiloCode for Obsidian is a bidirectional bridge between your knowledge base (Obsidian vault) and the KiloCode CLI. KiloCode is your AI tool — it helps you code in the terminal, and now it helps you manage knowledge in Obsidian. Zero config: same tool, two scenarios.

┌──────────────────────────────────────────────────────────────┐
│                     Obsidian Vault                            │
│                  (My Knowledge Base)                          │
│                                                               │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────────┐   │
│  │ Notes    │  │ .kilo/skills/ │  │ .kilocode/sessions/   │   │
│  │ (.md)    │  │ (AI skills   │  │ (conversation history) │   │
│  │          │  │  live in the │  │                        │   │
│  │          │  │  vault!)     │  │                        │   │
│  └──────────┘  └──────────────┘  └───────────────────────┘   │
│         ▲              ▲                      ▲               │
│         │              │                      │               │
│         └──────────────┼──────────────────────┘               │
│                        │                                      │
│            ┌───────────┴───────────┐                          │
│            │   KiloCode Plugin     │                          │
│            │   (this plugin)       │                          │
│            │                       │                          │
│            │  @mention vault files │                          │
│            │  Inject skills        │                          │
│            │  Attach notes as ctx  │                          │
│            │  Route conversation   │                          │
│            └───────────┬───────────┘                          │
│                        │ HTTP (127.0.0.1)                     │
└────────────────────────┼──────────────────────────────────────┘
                         │
            ┌────────────▼────────────┐
            │    KiloCode CLI         │
            │    (kilo serve)         │
            │                         │
            │  AI model               │
            │  Tool execution         │
            │  Code generation        │
            └─────────────────────────┘

What makes it interesting?

• Knowledge in the vault, shared tooling: Notes, skill definitions, and conversation history all live in your vault — version-controlled, backed up. KiloCode reads them as context — every session, every message. Same KiloCode config for coding and knowledge management, zero extra setup.
• Skills are knowledge workflows: AI skill definitions live at .kilo/skills/ as .md files. Write a weekly review workflow in markdown → run it every week with one /skill weekly-review command. Edit a skill, and the behavior changes instantly. No config toggling, no CLI restarts.
• Reference anything with @: Type @ to search and reference vault files, folders, MCP servers, or subagents. Content flows from your notes into the conversation seamlessly.
• One-click note context: Toggle "Include current note" and the active note's full content is sent to the AI as context — no copy-paste.
• File attachments: Drag, paste, or click to attach files. Text files are read inline and sent to the AI.
• MCP servers configured in the vault: .kilocode/mcp.json defines tools the AI can use. Edit this file to give KiloCode new capabilities.
• Zero-install CLI: The KiloCode CLI auto-downloads on first use. The plugin manages its entire lifecycle — start, keep-alive, idle timeout, and graceful shutdown.
• Your existing CLI config, respected: If you already use KiloCode CLI, the plugin reads ~/.config/kilo/kilo.jsonc directly — API keys, model selections, agent settings. Configure once in your terminal, use everywhere in Obsidian.

---

What Changes

Before

Managing the knowledge base is entirely manual:

• Notes are written and rarely revisited
• Tagging conventions drift over time
• Weekly reviews require manual effort and separate notes
• Knowledge silos go unnoticed

After

KiloCode becomes your knowledge management assistant:

• Workflows for knowledge processing live in the vault as reusable skills
• Previous sessions are searchable and replayable
• Weekly review runs with one command
• Knowledge accumulates and gets organized over time

---

KiloCode's Toolbox × My Knowledge Management

KiloCode is a versatile toolkit. Here's how each tool helps manage your knowledge base:

KiloCode Tool	I use it to...	Example
Skill System	Write reusable knowledge workflows	Write a weekly-review.md skill: auto-scan this week's journals → extract key decisions → generate a weekly summary. Write once, run /skill weekly-review every Friday
Bash / Scripting	Batch-operate on notes	"Find all untagged notes in my vault and auto-tag them based on content" — one instruction, done
File Read/Write	Generate knowledge indexes and maps	"Scan all ML-related notes in the vault, generate a knowledge map page with backlinks"
MCP Tools	Import knowledge from external sources	Connect Brave Search → "Search for latest AI Agent developments this week, write into literature notes"
Plan Mode	Safely analyze the full vault	"Analyze my vault structure, find knowledge silos and tagging inconsistencies" — read-only, confirm before execution
Permission Control	Trust but verify	Plan mode for analysis, Normal mode for execution. Never Yolo — data safety first
Multi-Tab Chat	Handle parallel knowledge tasks	Tab 1 researching connections, Tab 2 writing weekly report, Tab 3 organizing tags
Fork/Rewind	Roll back unsatisfactory changes	"Not happy with the tag organization → Rewind → adjust → re-run"
Session Persistence	Never lose knowledge work progress	Every organization session auto-saves — open next week and see exactly where you left off
Zero Config	Open and use	Already using KiloCode in the terminal? Same config, zero extra setup in Obsidian

---

Features

Feature	Capability
AI Chat Sidebar	Chat with KiloCode AI in Obsidian's sidebar. Each message carries your vault path, active note, and installed skills as context — the AI knows your vault.
@mention Vault Files	Type @ to search and reference any vault file or folder. The content flows from your notes into the conversation — no copy-paste.
Custom Instructions	Click # to open an instruction editor — write custom system prompts that get injected into the current conversation. Auto-saved, applied per session.
File Attachments	Attach any file from your system via the toolbar button. Text files are read inline and sent to the AI conversation.
Current Note Context	One-click toggle to include the active note as AI context. The plugin reads the note via Obsidian's Vault API and passes it to the CLI.
Vault-Backed Skill System	Knowledge processing skills are .md files in .kilo/skills/ inside your vault. The plugin loads them automatically and injects them as system context for every message. Edit a skill → behavior changes. No CLI restart needed.
Slash Commands	/skill to activate skills from the catalog, /model to switch AI models on the fly, /mode to toggle code/plan/ask, /compact to summarize conversation history, /clear to start fresh.
MCP Tool Framework	Tools are defined in .kilocode/mcp.json inside your vault. The plugin lists available MCP servers in the @mention dropdown so you can reference them in chat.
Plan Mode	Three modes: code (full read/write), plan (read-only analysis), ask (Q&A only). The mode prefix is injected into every message sent to the CLI.
Multi-Tab Chat	Multiple independent chat sessions. Each tab has its own conversation history stored in .kilocode/sessions/ — backed up with your vault.
Streaming Responses	Real-time AI responses with cancel support. The plugin consumes the CLI's async generator and updates the UI incrementally.
Conversation Fork/Rewind	Fork a new conversation from any message, rewind to previous states. All managed through the ConversationController layer.
Permission System	Yolo (auto-approve) / Normal (per-tool approval dialogs) / Plan (read-only). The ApprovalManager intercepts tool calls before they reach the CLI.
i18n	English and Chinese UI, auto-switches by browser language.
CLI Auto-Download	No manual CLI install. The BinaryManager auto-detects, downloads, and caches the platform-appropriate KiloCode binary from npm on first use. Background warmup pre-starts the CLI process so your first message is fast.
CLI Config Aware	Already using KiloCode CLI in your terminal? The plugin reads ~/.config/kilo/kilo.jsonc directly — your API keys, model selections, and agent settings carry over automatically. The /model command lists models from your CLI config. Configure once, use everywhere.
Idle Timeout	After 10 minutes of inactivity, the CLI process auto-stops to save resources. Next message restarts it transparently. HTTP keep-alive is used to reduce connection overhead.

---

Documentation

Document	Audience	Contents
ARCHITECTURE.md	Contributors	Directory structure, data flow, key components, design decisions, security model
DEVELOPMENT.md	Developers	Setup, build/test/lint scripts, i18n guide, CI/CD pipeline
ROADMAP.md	Everyone	Current progress and planned features
CHANGELOG.md	Everyone	Version history and release notes

---

Quick Start

Prerequisites: Obsidian v1.7.2+ (Desktop only)

Zero config. No CLI installation required — the plugin auto-downloads the KiloCode binary on first use. If you already have kilo installed globally or have config at ~/.config/kilo/kilo.jsonc, the plugin detects and uses them automatically. Your API keys, model preferences, and agent settings carry over with zero extra setup.

Installation

From Obsidian Community Plugins (Recommended)

1. Open Obsidian → Settings → Community plugins → Browse
2. Search for "KiloCode" and click Install
3. Enable the plugin

From GitHub Release

Download main.js, manifest.json, and styles.css from the latest release and place in <vault>/.obsidian/plugins/kilocode/.

From Source

cd /path/to/vault/.obsidian/plugins
git clone https://github.com/realhenrylan/obsidian-with-kilocode.git
cd obsidian-kilocode
npm install
npm run build

---

Usage

Basic Chat

Click the KiloCode icon in the ribbon (or Command Palette → KiloCode: Open chat view), type your message, and press Enter. Responses stream in real-time — press Cancel to interrupt. Shift+Enter for new line.

Quick Reference

Action	How
@mention Vault Files	Type @ or click toolbar @ → search and reference files, folders, MCP servers
Slash Commands	Type / or click toolbar / for /skill, /model, /mode, /compact, /clear
Custom Instructions	Click toolbar # to write and apply custom system prompts for the current session
File Attachment	Click toolbar 📎 to attach any file from your system
Current Note Context	Toggle toolbar 📝 to include active note as AI context
Switch Mode	Click mode toggle or Shift+Tab to cycle Code/Plan/Ask
Fork/Rewind	Hover a message for ⏪ Rewind, 🍴 Fork, or 📋 Copy
Inline Edit	Select text → Ctrl/Cmd+Shift+E → enter instruction (AI call pending)

Permission Modes

Mode	Behavior
Normal (default)	Read tools auto-approved, write tools require your approval
Yolo	All tools automatically approved — no prompts
Plan	Read tools allowed, write tools denied — read-only guarantee

---

Configuration

Open Settings → KiloCode:

Section	Key Settings
General	CLI Path (auto-detect), Download Mirror URL, Auto Start
API	API Key, Base URL (leave empty to use CLI's stored credentials)
Chat	Max Tabs (default: 3), Auto Save, Compact Keep Recent (default: 5)
Model	Default Model (default: claude-sonnet-4-20250514), Temperature (default: 0.7)
Appearance	Theme (auto/light/dark), Font Size (default: 14px)
Security	Permission Mode (Normal / Yolo / Plan)

Environment variables: Configured in Settings → Environment (Shared and KiloCode-specific). When API Key / Base URL are set, they pass KILO_API_KEY and KILO_BASE_URL to the kilo serve process.

MCP servers: Configure in vault/.kilocode/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "web-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"]
    }
  }
}

---

Architecture

See ARCHITECTURE.md for directory structure, data flow diagram, key component descriptions, design decisions, and security model details.

---

Development

See DEVELOPMENT.md for setup, build/test/lint commands, i18n guide, and CI/CD pipeline.

---

Roadmap

See ROADMAP.md for current progress and planned features.

---

Troubleshooting

KiloCode CLI not found

The plugin auto-downloads the CLI on first use. If it fails:

1. Check your internet connection
2. Set a mirror URL in Settings → General → Download Mirror URL
3. Install manually: npm install -g @kilocode/cli
4. Verify: kilo --version

CLI Path Issues

Leave empty for auto-detection. If needed, find the path with which kilo (macOS/Linux) or where.exe kilo (Windows) and set in Settings → General → CLI Path.

JSON-RPC Errors

Ensure @kilocode/cli is up to date (npm update -g @kilocode/cli) and verify your API key.

Network Errors

Check internet connection, API key, and firewall settings (CLI needs outbound HTTPS).

Conversation Persistence Issues

Conversations are stored in .kilocode/sessions/. Check the folder is writable and Auto Save is enabled.

---

License

MIT — see LICENSE.

---

Support

• GitHub Issues — Bug reports and feature requests
• Discussions — Questions and community chat
• Discord — Real-time support

---

Made with ❤️ for the Obsidian and KiloCode communities