{
  "markdown": "# DeepOrbit\n\n![DeepOrbit](deeporbit.png)\n\n> A local-first Obsidian knowledge system that works across Kimi Code, OpenClaw, Gemini/Antigravity, Codex, and other Agent Skills runtimes.\n\n[中文](README_CN.md) · [Documentation](https://dull-bird.github.io/DeepOrbit/) · [Architecture](docs/architecture.md)\n\nDeepOrbit 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.\n\n## Why DeepOrbit\n\n- **Portable:** the same `skills/` work across Agent Skills runtimes.\n- **Local-first:** Markdown is authoritative; no DeepOrbit cloud account is required.\n- **Sync-neutral:** use Git, Obsidian Sync, or any filesystem sync. Search indexes rebuild locally.\n- **Obsidian-native:** Properties, Bases, Graph, Backlinks, Daily Notes, Callouts, and Canvas remain useful outside an agent.\n- **Graceful fallback:** ChromaDB, MCP, Obsidian CLI, Tasks, Dataview, and Calendar are optional.\n- **Checkpointed:** long work resumes from Markdown checklists instead of an external self-invoking loop.\n\n## Three-minute tutorial\n\n### 1. Install with one prompt\n\nPaste this prompt to your agent (Claude Code, Kimi Code, OpenClaw, Codex, …) and it will perform the whole install:\n\n```text\nInstall DeepOrbit on this machine:\n\n1. Clone the repository: `git clone https://github.com/dull-bird/DeepOrbit.git ~/src/DeepOrbit`\n   (if ~/src/DeepOrbit already exists, run `git -C ~/src/DeepOrbit pull --ff-only` instead).\n2. Install the deterministic CLI: `python3 -m pip install -e ~/src/DeepOrbit`.\n3. Verify the CLI: run `deeporbit __schema` and confirm it prints the machine-readable\n   command surface. If the executable is not on PATH, fall back to\n   `PYTHONPATH=~/src/DeepOrbit/src python -m deeporbit __schema`.\n4. Install the global connector skill:\n   `npx skills add dull-bird/DeepOrbit --skill do.link --global --agent '*' --yes`.\n5. Report what was installed and any errors you encountered.\n```\n\nThe result is **one global connector skill** plus the deterministic CLI. `deeporbit __schema` prints the full machine-readable CLI surface for agents.\n\n### 2. Initialize or take over a vault\n\n```bash\ndeeporbit --vault ~/Documents/MyVault init --source ~/src/DeepOrbit\ndeeporbit --vault ~/Documents/MyVault doctor\ndeeporbit link add main ~/Documents/MyVault --description \"Personal research and writing\"\n```\n\nInitialization is idempotent. Existing notes and customized prompt files are\npreserved. Legacy localized folders are merged only when safe; conflicts are\nreported without overwriting either file. The initializer materializes:\n\n- workflow skills into `99_System/DeepOrbit/skills/` plus `skills-index.json`;\n- system templates, Bases, prompts, and methodology guides under `99_System/`;\n- a curated portable repository bundle under `99_System/DeepOrbit/repo/`.\n\nThe bundle is not a Git checkout. It copies the runtime surface needed to use or\nhand off the vault (skills, commands, prompts, hooks, CLI source, MCP, docs, and\nmanifests) while excluding `.git`, virtualenvs, caches, build outputs,\n`node_modules`, and generated agent install artifacts.\n\n### 3. Use it\n\n```bash\ndeeporbit --vault ~/Documents/MyVault todo add \"Dinner with Lily tomorrow at 7pm\"   # NL time parsing: text, date, and time split out automatically\ndeeporbit --vault ~/Documents/MyVault agenda\ndeeporbit --vault ~/Documents/MyVault rag \"index tracking\"\ndeeporbit --vault ~/Documents/MyVault calendar export\ndeeporbit --vault ~/Documents/MyVault open 10_Diary/2026-07-15.md\ndeeporbit --vault ~/Documents/MyVault about             # show vault directory semantics\ndeeporbit --vault ~/Documents/MyVault about inbox       # details for one directory\n```\n\nYou can also ask your agent naturally: “research index tracking”, “add this to today”, “what is overdue?”, or “find my previous notes about RAG”.\n\n## Link vaults from any workspace\n\nYou 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:\n\n```bash\ndeeporbit link add main ~/Documents/MyVault --description \"Personal research and writing\"\ndeeporbit link add work ~/Documents/WorkVault --description \"Work projects and client material\"\ndeeporbit link list\ndeeporbit link route \"prepare the client review\"\ndeeporbit --vault @work todo add \"Prepare the review\" --today\ndeeporbit --vault @main rag \"index tracking\"\n```\n\n`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.\n\nThe CLI also experimentally supports [CLI Schema v1](https://github.com/cli-schema/cli-schema): `deeporbit __schema` prints a machine-readable description of the whole command tree for agent tooling.\n\n## Work lifecycle, profile, and authorship\n\nEvery 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:\n\n```bash\ndeeporbit --vault ~/Documents/MyVault status                              # active / paused / done / archived, vault-wide\ndeeporbit --vault ~/Documents/MyVault pause 30_Research/Old-Thread.md     # dormant but visible\ndeeporbit --vault ~/Documents/MyVault resume 30_Research/Old-Thread.md\ndeeporbit --vault ~/Documents/MyVault done 15_Writings/essay.md\ndeeporbit --vault ~/Documents/MyVault archive 20_Projects/BigProj         # folder + assets, never overwrites\ndeeporbit --vault ~/Documents/MyVault trash 00_Inbox/stale.md             # reversible, into .trash/\n```\n\nInside `20_Projects` and `30_Research` the shelving mirrors that state: active work stays at the section root, `pause` files items into `Paused/`, and `archive` into `Archived/` — frontmatter `status` remains the source of truth. Every directory name is customizable in `deeporbit.json` (`directories`), and `init` adopts existing default folders by renaming them to match (see [docs/vault-layout.md](docs/vault-layout.md)).\n\n`99_System/Bases/Work Status.base` is the standing board for active / paused / done / archived work. `99_System/Profile.md` is the vault's picture of the user: stable facts through `profile set`, durable learnings through `profile observe` (timestamped, source-tagged, user-authored facts never silently overwritten).\n\nFolders managed by an external sync (e.g. `60_Notes/微信读书` exported by [weread-vault](https://github.com/dull-bird/weread-vault)) are **read-only zones**: `deeporbit init` detects them via sync frontmatter and records them in `deeporbit.json` (`readonly.directories`). The lifecycle CLI refuses to mutate them, `status` marks them, and suggestions skip them — link to these notes, derive analysis elsewhere.\n\nAuthorship is one invisible frontmatter field, never a visible badge: agents **must** write `author: ai` on every note they create and `author: mixed` when substantially rewriting a human note. Unmarked notes are human — the user never tags anything. Reading view stays clean, and Bases can filter AI output from human writing.\n\n## Guidance, rhythm, and extensibility\n\n- `deeporbit --vault ~/Documents/MyVault suggest` — prioritized issues derived from vault state (done-not-archived, dormant projects, stale index, empty profile…).\n- `/do:mentor` — a coach, not an assistant: diagnoses from `status` + `suggest` + profile, teaches one method slice at a time (GTD for commitments, PARA for filing, Zettelkasten for knowledge, Atomic Habits for rhythm — boundaries researched in [docs/methodology.md](docs/methodology.md), materialized into each vault), and leaves you with one next action.\n- `/do:dream` — the vault's offline consolidation: promotes repeated themes to Wiki, finds hidden connections, nudges lifecycle decisions, records profile observations. It proposes; you approve.\n- `deeporbit cron add dream \"Run the do.dream consolidation workflow\" --every daily` — device-local schedules; `cron run-due --agent` reports what's due and wraps each job in the configured agent CLI's handoff command.\n- `/do:heartbeat` — the batched proactive check-in: `deeporbit heartbeat` assembles a context package (suggest issues, status overview, reminders due, delta vs. yesterday's snapshot), the agent evaluates the WHEN rules in `99_System/Rules/` against it, and you get one briefing only when something hits — silence by default, every action propose-approve. Schedule it with `deeporbit cron add heartbeat ... --every daily`.\n- `/do:agent` — detect agent CLIs installed on this machine (omp/claude/gemini/codex), pick one via an ask form, and hand execution to it (ACP/RPC/print). See [docs/agent-cli.md](docs/agent-cli.md).\n- `/do:teach-me` — export vault knowledge into [teach-me](https://github.com/dull-bird/teach-me-skill) with an `origin` provenance block, so imported notes never mix with teach-me's natively accumulated knowledge. See [docs/teach-me-bridge.md](docs/teach-me-bridge.md).\n- `deeporbit --vault . sync` — git sync for the current vault (pull, commit, push when needed). Use it directly or via `deeporbit cron`.\n\n- **Recipes** (`99_System/Recipes/*.md`) are the extension point: declarative `cli:` / `skill:` / `note:` steps composing DeepOrbit with any other skill. `deeporbit --vault . recipe run \"Weekly Review\"` resolves one into an execution plan. Prefer a recipe over new infrastructure.\n\nThe tooling research behind these choices (PDF/Markdown/HTML processors, the Obsidian plugin ecosystem, community AI-note projects like kepano's obsidian-skills) is in [docs/tooling-landscape.md](docs/tooling-landscape.md); a wider survey of skill ecosystems and open-source NotebookLM alternatives is in [docs/skill-ecosystem-research.md](docs/skill-ecosystem-research.md). A runnable example vault lives in [examples/example-vault](examples/example-vault) and is mirrored at [dull-bird/deeporbit-example-vault](https://github.com/dull-bird/deeporbit-example-vault).\n\n## Obsidian plugin\n\n`plugin/` ships a thin, LLM-free Obsidian companion: a work-status sidebar (active / paused / done / archived with one-click transitions and AI/human markers) plus pause / resume / done / archive commands with the same no-overwrite semantics as the CLI. See [plugin/README.md](plugin/README.md).\n\n## Web dashboard\n\n```bash\ndeeporbit --vault ~/Documents/MyVault serve --open        # http://127.0.0.1:8765\n```\n\nA local, zero-dependency dashboard (binds 127.0.0.1 only): status cards and dormant counts, a 14-week activity heatmap, prioritized suggestions, the full work-item table with one-click pause/resume/done/archive, status/authorship/directory statistics, vault-wide search, recipes and cron overviews — plus an **Agent panel that chats through ACP** (`omp acp`, `claude --acp`, `gemini --acp` auto-detected, `--agent` to pick one). Agent file reads are sandboxed to the vault; write requests are denied. The UI follows Apple's fluid-interface principles (translucent materials, instant pointer feedback, reduced-motion fallbacks).\n\n## Runtime compatibility\n\n| Runtime | Portable Skills | Native package | Commands | MCP | Optional hooks | Prompt/context loading | Long-work enhancement |\n|---|---:|---|---:|---:|---:|---|---|\n| Kimi Code | Yes | `kimi.plugin.json` | Yes | Yes | Yes | Runtime hook + prompt file | Experimental Goal + checkpoints |\n| OpenClaw | Yes | Workspace `.agents/skills` | Natural language | Yes | Yes | Runtime-dependent | Native Goal + checkpoints |\n| Gemini / Antigravity | Yes | `gemini-extension.json` | Yes | Yes | Yes | `contextFileName` + hook | Plan/Tracker + checkpoints |\n| Claude Code | Yes | `.claude-plugin/plugin.json` | Yes | Yes | Yes | `CLAUDE.md` imports `DeepOrbitPrompt.md` | Markdown checkpoints |\n| Codex | Yes | `.codex-plugin/plugin.json` | Skills/natural language | Yes | Yes | Trusted `.codex/hooks` or plugin hook | Markdown checkpoints |\n| OMP | Yes | — | Runtime-dependent | Optional | Yes | Native `.omp/hooks/pre/deeporbit.ts` | Markdown checkpoints |\n| Other Agent Skills runtimes | Yes | — | Runtime-dependent | Optional | — | Runtime-dependent | Markdown checkpoints |\n\nThe runtime feature is never the only place progress is stored. Long workflows write a plan with checked and unchecked items under `90_Plans/` and can resume after interruption or on another agent.\n\n## Sync and local retrieval\n\nOnly notes, templates, Bases, and `deeporbit.json` belong in the vault. Machine-local indexes live under the operating system cache directory, keyed by the stable vault ID.\n\n```text\nGit / Obsidian Sync             Each computer\nMarkdown + deeporbit.json  -->  ~/.cache/deeporbit/<vault-id>/\n                                  search.sqlite\n                                  manifest.json\n                                  optional chromadb/\n```\n\nEvery retrieval checks for added, changed, renamed, and deleted files before querying. The default SQLite FTS index has no third-party dependencies. Optional semantic retrieval is available with:\n\n```bash\npython3 -m pip install -e '.[rag]'\ndeeporbit --vault ~/Documents/MyVault index ensure --semantic\ndeeporbit --vault ~/Documents/MyVault rag \"a conceptual query\" --semantic\n```\n\nDo not commit or synchronize vector databases. See [Sync and RAG](docs/sync-and-rag.md).\n\n## Obsidian integration\n\nDeepOrbit ships native Bases for projects, research, task-containing notes, and knowledge health under `99_System/Bases/`.\n\nCore Obsidian features:\n\n- Properties provide a shared schema (`type`, `status`, `area`, `created`, `updated`, `tags`).\n- Bases provide editable file-level dashboards.\n- Graph and Backlinks expose conceptual relationships and orphans.\n- Daily Notes connect agenda, recap, and current work.\n- Canvas is available for spatial research maps when it improves understanding.\n\nOptional community plugins:\n\n| Plugin | Enhancement | Required? |\n|---|---|---:|\n| Tasks | Rich task queries and completion UI | No |\n| Dataview | Advanced read-only dashboards | No |\n| Calendar | Daily Note navigation | No |\n\nObsidian CLI is preferred for opening generated notes. DeepOrbit falls back to `obsidian://` URIs and then to printing the absolute path.\n\n## Tasks, agenda, and calendar\n\nTasks remain portable Markdown:\n\n```markdown\n- [ ] Review DeepOrbit architecture 🔼 ⏳ 2026-07-13 📅 2026-07-15 ⏰ 14:00 ^do-20260713120000-a1b2c3\n- [ ] Weekly report 🔁 every week on Friday 📅 2026-07-31 ^do-20260724100000-d4e5f6\n```\n\n`todo add` parses Chinese and English natural-language times (\"明晚七点\", \"every Friday\") out of the text; tasks support priority, `⏰` exact times, recurrence, subtasks with derived `[n/m]` progress, dependencies, and attachments. `deeporbit remind install` delivers local macOS notifications for timed tasks. `99_System/Todo Dashboard.md` renders the same lines through Tasks-plugin query blocks (optional). The stable block ID supports exact completion and stable iCalendar UIDs. ICS export is a local snapshot — timed tasks become one-hour events, date-only tasks all-day events; it does not claim two-way Google or Apple Calendar synchronization. See [Tasks and calendar](docs/todo-calendar.md).\n\n## Skill catalog\n\nDeepOrbit 2.0 ships **33 `do.*` skills**. `skills/` is the single source of truth; every skill has paired Claude-style Markdown and Gemini TOML commands.\n\n| Skill | Purpose |\n|---|---|\n| `do.init` | Safely initialize or upgrade a vault |\n| `do.link` | Link external vaults and route requests to their workflows |\n| `do.mentor` | Coach on methods, tools, and recipes; diagnose vault health |\n| `do.dream` | Offline consolidation: promotions, connections, lifecycle nudges |\n| `do.teach-me` | Export vault knowledge into teach-me with provenance tagging |\n| `do.agent` | Detect and configure the local agent CLI (omp/claude/gemini/codex) |\n| `do.daily` | Daily planning, recap, news, and project context |\n| `do.todo` | Capture and manage Markdown tasks with natural-language time parsing |\n| `do.agenda` | Group overdue, today, upcoming, and unscheduled tasks |\n| `do.calendar` | Export dated tasks to portable ICS |\n| `do.remind` | Install local notifications for timed tasks (launchd + alerter/osascript) |\n| `do.heartbeat` | Batched proactive check-in — silence by default, propose-approve |\n| `do.kickoff` | Turn an idea into a structured project |\n| `do.write` | Polish raw thoughts into personal writing |\n| `do.research` | Checkpointed evidence-based deep research |\n| `do.ask` | Lightweight vault-aware Q&A |\n| `do.brainstorm` | Interactive idea exploration |\n| `do.rag` | Self-refreshing local retrieval |\n| `do.rag-index` | Inspect and refresh lexical or semantic indexes |\n| `do.search` | Fast lexical and phrase search |\n| `do.note-summary` | Full-source summaries and captures |\n| `do.parse-knowledge` | Convert unstructured material into durable notes |\n| `do.recap` | Summarize recent vault changes |\n| `do.arxiv-translator` | Translate and compile arXiv LaTeX sources |\n| `do.pdf-to-markdown` | Checkpointed high-fidelity PDF conversion |\n| `do.translate-markdown` | Complete, glossary-consistent Markdown translation |\n| `do.translate` | Route document translation to the right workflow |\n| `do.mermaid` | Select and create suitable Mermaid diagrams |\n| `do.fix-links` | Find and resolve ghost wikilinks |\n| `do.organize` | Analyze and safely reorganize a vault |\n| `do.archive` | Archive completed projects and processed items |\n| `do.refresh-prompt` | Merge upstream prompt changes without losing customizations |\n| `do.obsidian-open` | Open notes through CLI, URI, or path fallback |\n\n## MCP tools\n\nThe optional server exposes:\n\n- `deeporbit_status`\n- `rag_search`\n- `rag_query`\n- `task_agenda`\n\nInstall with `python3 -m pip install -e '.[mcp]'`. Lexical retrieval works without ChromaDB. See [MCP reference](mcp/README.md).\n\n## Development\n\n```bash\npython3 -m pip install -e '.[dev]'\npython3 -m unittest discover -s tests -v\npython3 scripts/validate_repo.py\nnpm --prefix site install\nnpm --prefix site run build\n```\n\n`tests/fixture_vault.py` builds a messy example vault (active/paused/done projects, legacy localized folders, AI- and human-authored notes, a LaTeX fixture). The integration suite drives it end to end: initialization and migration, lifecycle transitions, archiving, trash protection, the todo → agenda → calendar chain, index synchronization on add/modify/delete, link routing, user profile maintenance, and the LaTeX splitter.\n\nCI validates Python behavior, skills and commands, JSON manifests, shell syntax, runtime profiles, and the GitHub Pages build. When changing a skill or command, update both README files as required by [AGENTS.md](AGENTS.md).\n\n## Documentation map\n\n- Tutorial: [Getting started](docs/getting-started.md)\n- How-to: [Sync and rebuild RAG](docs/sync-and-rag.md)\n- How-to: [Tasks and calendar](docs/todo-calendar.md)\n- Reference: [Runtime compatibility](docs/runtime-compatibility.md)\n- Explanation: [Architecture](docs/architecture.md)\n\n## Acknowledgments\n\nDeepOrbit was inspired by [OrbitOS](https://github.com/MarsWang42/OrbitOS) and uses ideas from the portable Agent Skills ecosystem. See [skills/ACKNOWLEDGMENTS.md](skills/ACKNOWLEDGMENTS.md).\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 19596,
  "sha": "5c0ed66376dabbd007759223e3053c5b1b22726a26adc7e2b1abe22e910cbdae",
  "repo_slug": "dull-bird/deeporbit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_dull_bird_deeporbit_61b4629c/readme"
}