A local-first Codex Skill for safely auditing, querying, compiling, and organizing an Obsidian vault—with staged review before generated changes land.
Obsidian Knowledge Workbench turns Codex into a careful maintenance layer for a local Obsidian vault. It inventories and audits existing notes, answers with note-and-line citations, compiles source material into linked knowledge, and stages generated updates for human review. It does not require an Obsidian plugin, database, MCP server, network service, or Python dependency.
- Read first: inventory and audit before proposing organization changes.
- Local first: note contents stay on the machine unless the surrounding agent workflow explicitly sends them elsewhere.
- Human reviewed: compilation stages a diff by default; commit requires an unchanged baseline and explicit confirmation.
- Protects handwritten notes: only files marked with
generator: obsidian-knowledge-workbenchare replaced automatically. - Deterministic operations: one standard-library Python helper implements the file operations, JSON output contract, verification, and rollback.
- Works with existing structures: custom layouts support PARA, Johnny Decimal, and other established vault conventions.
| Area | Operations |
|---|---|
| Understand | inventory, audit, query, manifest-status, semantic-audit |
| Capture and compile | capture, compile |
| Review changes | stage-list, stage-review, stage-commit, stage-discard |
| Organize | graph, apply-inbox, daily-review, weekly-review |
| Initialize | init-vault |
Search and automatic taxonomy suggestions are lexical heuristics, not embedding search or semantic proof. The Skill instructs the agent to read relevant note context before making claims.
Clone the repository into your Codex Skills directory:
git clone https://github.com/Amossse/obsidian-knowledge-workbench.git \
~/.codex/skills/obsidian-knowledge-workbenchRestart Codex if the Skill does not appear immediately. Python 3.10 or newer is required. No package installation is needed.
Invoke the Skill and provide an explicit absolute Vault path:
Use $obsidian-knowledge-workbench to inventory and audit my vault at
/absolute/path/to/my-vault. Do not make changes yet.
The usual workflow is:
- Inventory and audit the confirmed Vault.
- Review the proposed, bounded plan.
- Dry-run any mutation.
- Review the staged diff.
- Explicitly authorize the commit.
- Read back and verify the resulting notes.
The deterministic helper can also be run directly:
python3 scripts/vault_ops.py --vault /absolute/path/to/vault inventory
python3 scripts/vault_ops.py --vault /absolute/path/to/vault audit
python3 scripts/vault_ops.py --vault /absolute/path/to/vault query "local-first knowledge"See SKILL.md for the agent workflow and references/output-contracts.md for the JSON and safety contracts.
- A Vault path is never inferred from the environment or current directory.
- Vault-relative paths are resolved and rejected if they escape the Vault.
- Broad audit results redact filenames by default and never return matched credential values.
- Sensitive-content audits scan complete notes by default. An optional scan limit is explicitly a partial audit.
- Generated writes are atomic. Staged commits recheck baselines, verify output hashes, and roll back touched targets after failure.
- Archive deletion requires explicit confirmation and occurs only after the destination is written and hash-verified.
Stage hashes protect against accidental drift and concurrent edits; they are not digital signatures. Treat the configured system directory and its staging bundles as trusted local control data, and always review diffs before committing. See SECURITY.md for the threat model and reporting process.
The CI matrix tests Python 3.10 and the latest supported Python on Linux, macOS, and Windows. Unix file-mode preservation is tested only on Unix-like systems.
python3 -m unittest discover -s scripts -p 'test_*.py' -v
python3 -m py_compile scripts/vault_ops.py scripts/test_vault_ops.pyThe implementation is intentionally dependency-free. Read docs/architecture.md before changing the transaction, manifest, or ownership invariants.
Contributions are welcome; start with CONTRIBUTING.md. Security issues should follow SECURITY.md, not a public issue.
Released under the MIT License. Historical attribution is recorded in NOTICE.md.