Darjeeling

by arrakis-surfer

Run Claude Code and other AI agents on your own Linux server and pick up the same sessions on desktop or phone.

↓ 50 downloadsUpdated 16d agoMIT

Project Darjeeling

Run Claude Code and other AI agents on your own Linux server and pick up the same sessions on desktop or phone.
Includes chat, phase-gated plans saved as notes, a remote terminal, and direct chat with AI providers.

What is Darjeeling?

Project Darjeeling is an Obsidian plugin and companion server daemon designed to integrate AI coding agents and large language models seamlessly into your personal knowledge base.

Persistent Sessions: Start an agent turn on your laptop, close the lid, and pick up the stream or interrupt it from your phone.
Architectural Plans as Notes: Decompose complex tasks into phase-gated plans, track task checkboxes, and export directly to Markdown notes and 2D visual Obsidian Canvases (.canvas).
Mobile-First Ergonomics: Touch-calibrated 44px hit targets, virtual terminal accessory keys, and responsive layouts that fit mobile sidebars.
Privacy & Ownership: Your notes stay in your vault. Server connections run over encrypted private overlay networks (Tailscale, Meshnet, WireGuard) with zero third-party telemetry.

Who It Is For (and Not For)

Who It Is For

Developers & Technical Writers: You work inside an Obsidian vault alongside git repositories and want agents like Claude Code to inspect files, run tests, and refactor code without leaving your notes.
Self-Hosters & Homelabbers: You run a dedicated Linux machine, VPS, or tethered workstation and want to offload heavy agent compilation and turn processing.
Multi-Device Thinkers: You plan initiatives on desktop and review or follow up on progress from your phone or tablet on the go.

Who It Is NOT For

If you only want to converse with Claude on your phone and do not use Obsidian or have a repository to inspect, you do not need Darjeeling. Use the official Claude iOS/Android app or Anthropic's Remote Control feature.

How It Works

Darjeeling provides three distinct runtime modes:

┌─────────────────────────────────────────────────────────────────────────┐
│                        Obsidian Client (Any Device)                     │
│               Chat Surface  •  Plan Engine  •  Terminal                 │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
      ┌──────────────────────────────┼──────────────────────────────┐
      ▼                              ▼                              ▼
┌──────────────┐              ┌──────────────┐              ┌──────────────┐
│  Direct API  │              │  Local Mode  │              │ Remote Server│
│(Zero Server) │              │(Desktop Only)│              │ (Companion)  │
└──────┬───────┘              └──────┬───────┘              └──────┬───────┘
       │                             │                             │
       ▼                             ▼                             ▼
Google Gemini / Anthropic     Local CLI (`claude`)          Headless Linux
Claude / DeepSeek / Ollama    & PTY in Vault Root           Daemon (Port 8765)

Remote Companion Server: A headless Python daemon (darjeeling-server) running on your Linux host. Runs Claude Code and tmux terminal sessions, streaming bidirectional Protocol v2 WebSocket events to your desktop or mobile Obsidian app over private overlay networks.
Desktop Local Mode: Spawns local CLI agents (claude, agy) and an embedded Python PTY terminal directly on macOS or Linux desktop within your vault working directory.
Direct Provider API: Connects Obsidian directly to Google Gemini, Anthropic Claude, DeepSeek, Ollama, or OpenAI-compatible endpoints with zero server requirements.

Runtime Compatibility Matrix

Runtime Mode	Supported Platforms	Shell & Tools	Session Resumption	Notes & Canvas Export	Status
Remote Companion Server	Linux Host (Client: macOS, Linux, Windows, iOS, iPadOS, Android)	Yes (Full bash & tmux)	Yes (Protocol v2 async turn recovery)	Yes	Stable (v1.0)
Desktop Local Mode	macOS, Linux Desktop	Yes (Local PTY)	Process lifetime	Yes	Stable (v1.0)
Direct Provider API	macOS, Linux, Windows, iOS, iPadOS, Android	No (Completion only)	No	Yes	Stable (v1.0)

[!NOTE] Agent Support: Claude Code (claude, tested versions 0.2.29–0.2.32) is the primary supported agent CLI. Support for Google Antigravity (agy) and DeepSeek CLI is Experimental. Platforms: Tested on macOS and Linux. Windows, iOS, Android and iPadOS are supported.

Quick Starts

Option 1: Remote Companion Server (4 Steps)

Install Server Daemon on your Linux host (Debian 12/13 or Ubuntu 22.04/24.04). Download the installer, the server tarball and SHA256SUMS from the latest release, verify, then run:

VER=1.0.4
BASE=https://github.com/michaelperna/obsidian-darjeeling/releases/download/$VER
curl -fsSL -O "$BASE/install.sh" -O "$BASE/darjeeling-server-$VER.tar.gz" -O "$BASE/SHA256SUMS"
sha256sum --ignore-missing -c SHA256SUMS
sudo bash install.sh --yes --network auto

Authenticate Agent as the service user (the installer prints this command, with the full path to claude if it is not on the service user's PATH):

sudo runuser -u darjeeling -- claude login

Pair Device: Run sudo darjeeling pair on the server (the installer also prints a code), then enter the 8-digit code in Obsidian under Settings > Darjeeling > Connections. A paired desktop can generate codes for your other devices.
Synchronize Vault: Configure Syncthing, git, or Obsidian Headless Sync between your devices and /var/lib/darjeeling/vault (remembering to exclude .obsidian/ in both directions).

Full installation details: Server Installation Guide.

Option 2: Direct API Mode (No Server Required)

Install and enable the Darjeeling plugin in Obsidian.
Navigate to Settings > Darjeeling > Providers.
Select your provider (Google Gemini, Anthropic Claude, DeepSeek, or Ollama) and enter your API key.
Open the Darjeeling leaf from the ribbon or command palette and start chatting immediately.

Full details: Direct API Guide.

Security, Privacy & Network Egress

Darjeeling is designed specifically for sensitive personal and professional knowledge vaults:

Strict Permission Sandboxing: By default, agents operate in plan mode (read-only analysis). Modifying workspace files requires acceptEdits, and autonomous commands require bypassPermissions (subject to the host server's permission ceiling).
Protected Bearer Tokens: Tokens are stored exclusively in device-local storage (SecretStorage). Revoking a device terminates active WebSockets immediately.
No Third-Party Telemetry: Hardware metrics stay on your host machine. Telemetry polling only runs when the Host tab is open and active.

Network use and data

Every outbound network call site is audited and accounted for. Outbound network traffic is strictly restricted to configured endpoints, direct LLM providers, or user-clicked hyperlinks:

ID	Destination	Protocol	Purpose	Data Sent
`host-ws`	Configured Darjeeling host	WebSocket	Agent event streaming & interactive turns	Prompts, permission responses, session inputs
`host-http`	Configured Darjeeling host	HTTP/HTTPS	Health checks, agent listing, async turn management	Authentication token in header, turn options
`host-pairing`	Configured Darjeeling host	HTTP/HTTPS	Device token exchange & pairing verification	8-digit pairing code, device metadata
`host-sync`	Configured Darjeeling host	HTTP/HTTPS	Vault note sync to remote host workspace	Selected markdown note content & relative path
`host-terminal`	Configured Darjeeling host	WebSocket	Remote interactive PTY terminal session	Keystrokes, terminal dimensions, auth token in protocol header
`provider-anthropic`	Anthropic API (`api.anthropic.com`)	HTTPS	Direct LLM completions & model listing	User prompts, optional system prompt, api key in header
`provider-gemini`	Google Gemini API (`generativelanguage.googleapis.com`)	HTTPS	Direct LLM completions & model listing	User prompts, optional system prompt, api key in header
`provider-deepseek`	DeepSeek API (`api.deepseek.com`)	HTTPS	Direct LLM completions & model listing	User prompts, optional system prompt, api key in header
`provider-ollama`	Local or configured Ollama instance	HTTP/HTTPS	Direct LLM completions & model listing	User prompts, optional system prompt
`provider-openai`	OpenAI-compatible endpoint	HTTP/HTTPS	Direct LLM completions & model listing	User prompts, optional system prompt, api key in header
`browser-open`	External browser target	OS URL Handler	Opening terminal hyperlinks in external browser	Destination URL clicked by user

Accounts, Pricing & Billing

100% Free & Open Source: Project Darjeeling is free software released under the MIT License. There are no subscriptions, hidden fees, seat charges, or token markups.
Bring Your Own Keys / Accounts: All API usage is billed directly to your own account with each respective model provider (Google Cloud, Anthropic, DeepSeek, OpenRouter, etc.).
Self-Hosted Infrastructure: You provide your own server or compute instance (e.g., local home computer, spare laptop, Raspberry Pi 5, or private cloud VM).

Processes & Filesystem Access

Local Mode: Runs child processes directly under your personal user account. Subprocesses have access to your vault directory according to the selected permission mode.
Companion Server Mode: Runs as an unprivileged dedicated service user (darjeeling) with systemd hardening (NoNewPrivileges=yes, ProtectSystem=full).
Vault Code Path Isolation: Sync engines must exclude .obsidian/ in both directions so that server-side file edits can never write untrusted plugins or snippets to connected client devices.

Documentation

Credits & Acknowledgements

Project Darjeeling is built on open standards and open-source software:

Obsidian by Dynalist Inc.
xterm.js by SourceLair and Christopher Jeffrey (MIT)
Model APIs provided by Anthropic, Google, DeepSeek, and Ollama.

Similar Plugins

AI Agent Panel

approvedunreviewed61% similar

by Yoav Aharoni

Chat with an AI coding agent inside your vault. Unofficial; works with Anthropic's Claude Code CLI, which you install and log in to yourself.

↓ 9917d agoMIT

Lodestone

approvedunreviewed61% similar

by whiskeyjack96

Enables an AI Agent (Lode) that uses Agent Client Protocol (ACP), to communicate directly with your notes.

★ 15↓ 1,76610mo agoMIT

Companion for Claude

approvedunreviewed61% similar

by Sasan Sotoodehfar

Chat with Claude inside your vault, generate gallery-grade interactive planning artifacts, and sync everything Claude produces back into your notes.

★ 4↓ 4,13314d agoMIT

Vault Companion for Claude

approvedunreviewed61% similar

by Sander Robijns

Chat with Claude on desktop and mobile. Claude reads, searches, creates, and updates notes in your vaultl — via your own Anthropic API key or your Claude subscription through a self-hosted relay.

↓ 1,6522mo agoMIT

Agent MCP

approvedunreviewed60% similar

by Robert Spaans

Run coding agents (Claude Code, Codex, Ollama) inside Obsidian. Ships a built-in terminal and exposes the active selection and open editors over MCP.

★ 2↓ 1,2161mo agoMIT

Agentic Copilot

unlisted60% similar

by Spencer Marx

Integrate agentic CLI tools (Claude Code, Opencode, Gemini CLI) as a workspace copilot with streaming chat, vault-aware context, and edit diffs.

★ 485mo agoMIT

Agent Client

approvedunreviewed60% similar

by rait-09

Chat with Claude Code, Codex, Gemini CLI, and more via the Agent Client Protocol — right from your vault.

★ 2,441↓ 295,89227d agoApache-2.0

LingXi1949

approvedunreviewed60% similar

by cyber-bike01

Bridge your notes to AI agents — rich markdown and linked context replace the single prompt box, with local and remote terminal sessions.

↓ 23917d agoGPL-3.0

Vault Claude

unlisted60% similar

by Victor Dasari

Agentic AI assistant — chat with Claude to read, write, search, and transform your notes using natural language.

6mo agoMIT

Claude Code Integration

unlisted60% similar

by David Alcalá

Integrate Claude Code AI assistant for intelligent note editing.

★ 889mo agoMIT

For plugin developers

Search results and similarity scores are powered by semantic analysis of your plugin's README. If your plugin isn't appearing for searches you'd expect, try updating your README to clearly describe your plugin's purpose, features, and use cases.