KiloCode
Henry Lan107 downloadsGive KiloCode persistent project memory from your vault. Architecture decisions, skills, workflows, and sessions — all stored in markdown.
- Overview
- Scorecard
- Updates7
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.mdfiles. Write a weekly review workflow in markdown → run it every week with one/skill weekly-reviewcommand. 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.jsondefines 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.jsoncdirectly — 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
kiloinstalled 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)
- Open Obsidian → Settings → Community plugins → Browse
- Search for "KiloCode" and click Install
- 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:
- Check your internet connection
- Set a mirror URL in Settings → General → Download Mirror URL
- Install manually:
npm install -g @kilocode/cli - 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