KiloCode

---

The Problem

KiloCode is powerful. But like every AI coding agent, it has a fundamental flaw:

It forgets everything between sessions.

Every conversation reset means:

• Lost architecture context — you re-explain the same decisions
• Forgotten coding standards — the agent repeats the same mistakes
• Inconsistent workflows — no two sessions produce the same result
• Repeated prompting — you type the same instructions again and again

This plugin is the fix: your Obsidian vault becomes KiloCode's long-term memory.

---

What This Plugin Does

KiloCode for Obsidian is a bidirectional bridge between your knowledge base (Obsidian vault) and the KiloCode CLI. The vault doesn't just store notes — it stores memory for your coding agent.

┌──────────────────────────────────────────────────────────────┐
│                     Obsidian Vault                            │
│               (Persistent Memory Layer)                       │
│                                                               │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────────┐   │
│  │ 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 a memory system, not just a chat panel?

• Persistent project memory: Architecture decisions, coding standards, and project knowledge live in your vault as markdown. KiloCode reads them as context — every session, every message. No context is ever lost.
• Skills stored in your vault: AI skill definitions live at .kilo/skills/ as .md files. Edit a skill, and KiloCode's behavior changes instantly. No config toggling, no CLI restarts.
• Session history in your vault: Every conversation persists to .kilocode/sessions/ — version-controlled, backed up with your notes, searchable across sessions.
• Reference anything with @: Type @ to search and reference vault files, folders, MCP servers, or subagents. Content flows from your memory 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

KiloCode forgets everything when the conversation ends:

• Architecture decisions are lost
• Workflows reset every session
• Coding standards must be re-explained
• Reusable patterns never accumulate

After

Your Obsidian vault becomes KiloCode's persistent memory:

• Architecture is always loaded as context
• Skills are always available (markdown files in vault)
• Previous sessions are searchable and reusable
• Project knowledge accumulates over time

---

Documentation

---

Features

---

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

Permission Modes

---

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:

{
  "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

---