ppatlabs/obsidian-tools repository overview

⁠obsidian-tools

Code for BRAIN: a git-backed Obsidian vault used as a shared brain — the store of the owner's knowledge and ideas, written mostly by AI agents, read by the same agents and a human. The design of record lives beside this file: USE_CASES.md⁠ (the outcomes), DESIGN.md⁠ (the pillars, invariants and glossary), and ROADMAP.md⁠ (the work and its state), with the decision records under docs/adr/⁠.

⁠Status

Two components are shipped and running (v0.4.0 released; later fixes are merged and ride the next release — see ROADMAP.md⁠ for the delivery gap and everything below):

• The git committer (obsidian-tools commit) — runs in-cluster on a schedule, turning the vault volume into git history pushed to two remotes. It never authors content.
• local-replicator (obsidian-tools replicate + obsidian-tools drain) — runs on the operator's Mac under launchd, keeping the device-facing iCloud vault current from git, one-way and non-destructively: device-side drift is captured to a durable local spool before anything is overwritten. The drainer's destination is a deliberate stub (discard) until the work queue exists.

Still to build, each specified in the design and tracked on the roadmap: the work queue and its three processors (batch-processor, promotion-processor, drift-processor), the admission validator, and the lint pass.

⁠Documentation

⁠Related repositories

• ppat/obsidian-vault⁠ — the vault content itself (private).
• ppat/homelab-ops-kubernetes-apps⁠ — the deployment manifests (module apps-ai) for the in-cluster workloads built here.
• ppat/homelab-ops-kubernetes-clusters⁠ — composes those modules onto the real clusters at pinned release tags.

⁠Development

Requires mise⁠ (pins exact tool versions — see mise.toml⁠) and uv⁠ for Python dependency management.

mise install
mise exec -- uv sync --all-extras
mise exec -- pre-commit install --install-hooks

Run the checks locally:

mise exec -- uv run ruff check .
mise exec -- uv run ruff format --check .
mise exec -- uv run pyright
mise exec -- uv run pytest
pre-commit run --all-files

CI runs the same checks plus an offline link-and-anchor check — see .github/workflows/lint.yaml⁠ and .github/workflows/test.yaml⁠.

⁠Releases

Versioned via release-please⁠ — merging a release PR cuts a tagged release and updates CHANGELOG.md automatically. Don't hand-edit CHANGELOG.md.

⁠Conventions

Runtime code is Python, managed with uv; shell is for CI/ops only, never runtime. The full working conventions for this repository — an agent's orientation included — are in CLAUDE.md⁠.