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.

Status legend: Features marked Planned are documented for upcoming releases but not yet wired to the CLI (see Roadmap). Implemented (partial) means the feature is functional in the UI but its end-to-end path is not yet verified.

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:

Features

Documentation

Quick Start

No CLI installation required. The plugin automatically downloads the platform-appropriate KiloCode CLI binary from npm on first use. If you already have kilo installed globally, it will be detected and used.

Note: the CLI version is currently pinned to 7.3.1 (PINNED_CLI_VERSION), matching @kilocode/sdk ^7.3.1. Custom CLI versions are not yet supported; decoupling the pinned version is planned.

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

Permission Modes

Inline Edit

Status: Implemented — select text, press Ctrl/Cmd + Shift + E, enter an instruction, and the plugin asks the CLI for a suggestion (read-only prompt), shows a diff preview, then writes the change to the note on Accept.

1. Select text in a note
2. Press Ctrl/Cmd + Shift + E
3. Enter your editing instruction in the modal
4. Review the diff preview (added lines in green, removed in red)
5. Click Accept (writes the change to the note) or Reject

Slash Commands

Status: Implemented — type / to open the command palette and run /compact /clear /model /mode.

Type / in the input to see available commands. A command palette with keyboard navigation (Arrow/Enter/Escape) will appear:

@mention

Status: Planned — the @ dropdown is not yet implemented and currently shows a "coming soon" notice.

Type @ to trigger the mention dropdown, which searches across:

Results are grouped by type with up to 20 matches returned.

Plan Mode

Click the mode toggle button in the chat header or press Shift+Tab to cycle through modes:

The mode prefix is injected into each message, and the active mode is visually indicated in the UI.

Conversation Management

Messages display action buttons on hover:

• ⏪ Rewind — Discard all messages after the selected message (with confirmation)
• 🍴 Fork — Create a new conversation starting from the selected message
• 📋 Copy — Copy message content to clipboard

Compaction

When conversations grow long, use /compact to replace old messages with a system summary, keeping the N most recent messages intact (configurable in settings, default: 5).

Image Attachments

You can attach images to your messages in three ways:

1. File picker — Click the image button in the toolbar
2. Clipboard paste — Copy an image and paste (Ctrl/Cmd+V) into the input area
3. Drag & drop — Drag an image file into the input area

Images are previewed in a grid above the input box with individual remove buttons. Size limit: 5MB per image.

Current Note Context

Toggle the current note context button in the toolbar to include your active note's content as context for the AI. The toggle state is visually indicated and persists within the session.

Permission System

Status: Implemented (partial) — ApprovalManager and the ApprovalModal are fully implemented, but the approval round-trip to the runtime (sendApproval) is not yet covered by end-to-end tests.

Tool calls by the AI are governed by the selected permission mode:

Configuration

Open Settings → KiloCode:

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:

API Configuration

Note: kilo serve manages its own credentials independently (via CLI keychain or config files). You only need to fill in API Key / Base URL here to override the CLI's defaults. If left empty, the plugin uses the CLI's existing credentials automatically.

Chat

Model

Appearance

Security

Environment Variables

Configure environment variables in Settings → Environment:

• Shared — Applied to all providers
• KiloCode — Applied to KiloCode provider only. Passes KILO_API_KEY and KILO_BASE_URL from settings to the kilo serve process when configured; otherwise the CLI uses its own stored credentials. Working directory is set to vault path.

MCP Servers

Status: Implemented (pass-through) — MCP servers are configured in vault/.kilocode/mcp.json and passed to the kilo serve CLI at startup (KILO_CONFIG_CONTENT). The CLI owns the connection lifecycle; the plugin queries real status via the SDK (client.mcp.status()). Connection state is no longer simulated.

Configure MCP servers in vault/.kilocode/mcp.json (SDK Config.mcp format):

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "web-search": {
      "type": "local",
      "command": ["npx", "-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.

🛠️ Development

Setup

# Clone the repository
git clone https://github.com/realhenrylan/obsidian-with-kilocode.git
cd obsidian-kilocode

# Install dependencies
npm install

# Start development mode (watch mode with esbuild)
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Run linter
npm run lint

Scripts

Testing

The test suite covers:

• Unit tests: ProviderRegistry, StreamController, InputController, TabManager, ConversationService, MessageRenderer, CommandRegistry, PlanModeController, MCPManager, KiloCodeChatRuntime, i18n, ApprovalManager, ImageContext, CurrentNoteContext, InputToolbar
• Integration tests: Chat workflow (TabManager + StreamController + InputController + PlanModeController), conversation management (fork/rewind/compact/resume), streaming pipeline

# Run all tests
npm test

# Run with coverage
npm run test:coverage

i18n

Adding a new language:

1. Create src/i18n/locales/{lang}.json following the structure of en.json
2. The i18n system auto-detects the locale and falls back to en for missing keys
3. Translation keys use dot notation (e.g., settings.cliPathDesc) with {{param}} substitution

CI/CD

• CI (.github/workflows/ci.yml): Runs on push/PR to main — typecheck → lint → build → test
• Release (.github/workflows/release.yml): On tag v* — build → create GitHub Release with main.js, manifest.json, styles.css

📋 Roadmap

• Basic chat functionality
• Streaming responses with interruption
• Multi-tab support with state persistence
• Conversation management (CRUD, fork, rewind, compact, resume)
• Inline edit with diff preview (plan-mode CLI call + preview + accept-to-vault)
• Slash commands with command palette
• @mention (files, folders, MCP servers, subagents) (UI pending)
• Plan mode (code/plan/ask)
• MCP server support (pass-through to kilo serve, real status query)
• Permission system (yolo/normal/plan) with approval dialogs (end-to-end approval not yet verified)
• Image attachments (paste, drag-drop, file picker)
• Current note context toggle
• Input toolbar
• i18n (English, Chinese, Japanese, Korean)
• Virtual scrolling for large conversations
• Error handling with severity levels
• CLI binary auto-download (zero-config setup)
• Streaming performance optimization (rAF scroll throttle, debounced writes, SSE chunk merge)
• Additional language support
• Custom theme support
• Plugin API for third-party extensions

🐛 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