deeporbit

DeepOrbit

A local-first Obsidian knowledge system that works across Kimi Code, OpenClaw, Gemini/Antigravity, Codex, and other Agent Skills runtimes.

中文 · Documentation · Architecture

DeepOrbit keeps research, projects, writing, tasks, and retrieval in ordinary local files. Agent Skills describe workflows; a small Python core handles deterministic operations such as safe initialization, incremental search, task IDs, and calendar export. Native goals, hooks, plugins, and MCP improve each runtime without becoming required for correctness.

Why DeepOrbit

• Portable: the same skills/ work across Agent Skills runtimes.
• Local-first: Markdown is authoritative; no DeepOrbit cloud account is required.
• Sync-neutral: use Git, Obsidian Sync, or any filesystem sync. Search indexes rebuild locally.
• Obsidian-native: Properties, Bases, Graph, Backlinks, Daily Notes, Callouts, and Canvas remain useful outside an agent.
• Graceful fallback: ChromaDB, MCP, Obsidian CLI, Tasks, Dataview, and Calendar are optional.
• Checkpointed: long work resumes from Markdown checklists instead of an external self-invoking loop.

Three-minute tutorial

1. Install only the connector globally

DeepOrbit's recommended cross-project install is one global connector skill:

npx skills add dull-bird/DeepOrbit --skill do.link --global --agent '*' --yes

Install the deterministic CLI once on the machine:

git clone https://github.com/dull-bird/DeepOrbit.git ~/src/DeepOrbit
python3 -m pip install -e ~/src/DeepOrbit
deeporbit __schema

deeporbit __schema prints the full machine-readable CLI surface for agents. If the executable is unavailable from a checkout, use:

PYTHONPATH=~/src/DeepOrbit/src python -m deeporbit __schema

2. Initialize or take over a vault

deeporbit --vault ~/Documents/MyVault init --source ~/src/DeepOrbit
deeporbit --vault ~/Documents/MyVault doctor
deeporbit link add main ~/Documents/MyVault --description "Personal research and writing"

Initialization is idempotent. Existing notes and customized prompt files are preserved. Legacy localized folders are merged only when safe; conflicts are reported without overwriting either file. The initializer materializes:

• workflow skills into 99_System/DeepOrbit/skills/ plus skills-index.json;
• system templates, Bases, prompts, and methodology guides under 99_System/;
• a curated portable repository bundle under 99_System/DeepOrbit/repo/.

The bundle is not a Git checkout. It copies the runtime surface needed to use or hand off the vault (skills, commands, prompts, hooks, CLI source, MCP, docs, and manifests) while excluding .git, virtualenvs, caches, build outputs, node_modules, and generated agent install artifacts.

3. Use it

deeporbit --vault ~/Documents/MyVault todo add "Review the paper" --today --due 2026-07-15
deeporbit --vault ~/Documents/MyVault agenda
deeporbit --vault ~/Documents/MyVault rag "index tracking"
deeporbit --vault ~/Documents/MyVault calendar export
deeporbit --vault ~/Documents/MyVault open 10_Diary/2026-07-15.md

You can also ask your agent naturally: “research index tracking”, “add this to today”, “what is overdue?”, or “find my previous notes about RAG”.

Link vaults from any workspace

You do not need to install every skill into every project. Install only do.link, register one or more vaults, and route natural-language requests to them:

deeporbit link add main ~/Documents/MyVault --description "Personal research and writing"
deeporbit link add work ~/Documents/WorkVault --description "Work projects and client material"
deeporbit link list
deeporbit link route "prepare the client review"
deeporbit --vault @work todo add "Prepare the review" --today
deeporbit --vault @main rag "index tracking"

link add validates the target: deeporbit reports whether the folder was initialized, obsidian_opened whether Obsidian ever opened it (.obsidian/app.json). Descriptions drive routing — with several vaults the agent picks the target by matching your request against each vault's description, and deeporbit link route is the machine-level helper for ambiguous requests. The registry is device-local at ~/.config/deeporbit/links.json and never syncs.

The CLI also experimentally supports CLI Schema v1: deeporbit __schema prints a machine-readable description of the whole command tree for agent tooling.

Work lifecycle, profile, and authorship

Every note with a status: field is a work item — not just 20_Projects. The CLI owns every transition, so nothing depends on an agent remembering to move files: