Skip to content

zzhzkx/codex-obsidian

v2.2.0MIT

Local-first Agent Skills package and Codex plugin for source-cited Obsidian knowledge bases. Ported from claude-obsidian with Codex manifests, Codex lifecycle hooks, and a native-Windows write path.

codex-obsidian is a local-first knowledge system for Codex and compatible Agent Skills hosts. It turns source material into linked, source-cited Obsidian pages; answers from the evidence already in the vault; and provides explicit workflows for research, retrieval, maintenance, and visual mapping.

It is a minimal port of AgriciDaniel/claude-obsidian: the skills, vault model, and transaction core are unchanged. The host adapter now targets Codex manifests and Codex lifecycle hooks, and vault writes run natively on Windows without WSL.

Your vault remains a normal directory of Markdown, JSON, and source files. It is not hidden in a plugin cache, locked in a cloud database, or silently uploaded to a model.

From source to living knowledge

Most AI note workflows stop after saving text. codex-obsidian is organized around a repeatable loop: retain the source, ground the claims, connect the knowledge, then put it back to work.

The codex-obsidian compounding knowledge loop

  • Capture with context. Bring local sources through a visible inbox and preserve immutable, content-addressed copies before synthesis.
  • Ground every important claim. Source and claim ledgers retain authority, freshness, support, contradiction, confidence, and review state.
  • Connect what you learn. Build linked pages, indexes, Maps of Content, methodology-aware structures, and Obsidian Canvas views.
  • Use the vault again. Query, research, retrieve, lint, and fold what is already known instead of starting every conversation from zero.

See the vault

The output is meant to remain useful with or without an agent: plain Markdown for portability, Obsidian for navigation and visual exploration.

Why it feels different

  • Local by default. The vault is user-owned and works as ordinary files. Network egress is a separate, explicit decision.
  • Sources survive the summary. Notes point back to durable source evidence; unsupported and contradictory claims remain visible.
  • Knowledge compounds deliberately. Ingestion, querying, linting, retrieval, research, and rollups share one provenance-aware model.
  • Parallel agents cannot race the vault. Workers return drafts. One orchestrator inspects and applies one recoverable transaction.
  • Capabilities are stated honestly. Optional tools are detected, maturity is declared, and missing adapters degrade clearly instead of being simulated.

This is not an automatic transcript recorder, a cloud sync service, a factual oracle, or a substitute for backups and source control.

Quick start

The safest first run uses a source checkout and a separate user vault. Every mutating setup command previews its exact operation before it can apply.

1. Get the product

git clone https://github.com/zzhzkx/codex-obsidian.git
cd codex-obsidian

The checkout contains the product. It is not your knowledge vault.

2. Register the plugin in Codex

codex plugin marketplace add zzhzkx/codex-obsidian

Then open /plugins in Codex, install Codex Obsidian, and start a new session. For local development, register the checkout instead:

codex plugin marketplace add .

Codex loads the plugin from .codex-plugin/plugin.json; .claude-plugin/ is kept only for upstream compatibility. Do not point a marketplace at a vault.

3. Initialize a separate vault

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"

python scripts/codex-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"

Review the JSON plan and copy its approved_plan_sha256, then apply that exact operation:

python scripts/codex-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<sha256-from-the-plan>" --apply

For an existing Obsidian vault, use the non-destructive adopt workflow described in the installation guide.

4. Start from the vault

Open the new directory in Obsidian, then run Codex from that directory:

cd "$HOME/Documents/MyKnowledgeVault"
codex

Start with:

$wiki

Then place a source in inbox/ and invoke $wiki-ingest. Save an answer explicitly with $save; ask the vault with $wiki-query.

Without the plugin, other hosts can link the portable skills directly:

python scripts/setup-multi-agent.py --host codex
python scripts/setup-multi-agent.py --host codex --apply

Cursor and Windsurf use workspace-local skill discovery. Marketplace setup, every supported host, vault adoption, upgrades, and uninstall steps are covered in the full installation guide.

python3 is the equivalent command on macOS and Linux. On Windows use python. The plugin hooks already select the right interpreter per platform.

15 skills, one system

The skills are small enough to invoke directly and coordinated enough to share the same evidence, vault-selection, and mutation rules.

Build and use the wiki

SkillWhat it does
wikiInitializes or adopts a vault, diagnoses readiness, and routes work
saveSaves one scoped answer or insight—never an automatic transcript
wiki-ingestTurns captured sources into linked pages and provenance records
wiki-queryAnswers read-only from relevant vault evidence
wiki-lintReports dead links, orphans, metadata gaps, stale indexes, and empty sections

Extend the workflow

SkillWhat it adds
autoresearchBounded web research with explicit egress and a separate canonical merge
canvasWiki-scoped Obsidian Canvas creation and maintenance
defuddleClean, readable web content before ingestion
wiki-foldExtractive, traceable rollups of the operation log
wiki-modeGeneric, LYT, PARA, or Zettelkasten filing conventions
wiki-retrieveContextual prefixes, BM25, and optional cosine reranking
wiki-cliObsidian CLI reads and search with transaction-safe writes

Reference skills

SkillWhat it provides
obsidian-markdownCorrect Obsidian Flavored Markdown, links, embeds, and callouts
obsidian-basesNative .base tables, cards, filters, formulas, and summaries
thinkA structured observe, listen, connect, create, and grow review loop

Codex invokes skills as $wiki-lint (or by their description); other hosts use their native Agent Skills invocation. Trigger phrases and exact contracts live in each skills/<name>/SKILL.md.

Trust is part of the architecture

The codex-obsidian product and vault trust boundary

The product never treats a source checkout, plugin cache, or contributor state as the default vault. A vault is selected explicitly, through CODEX_OBSIDIAN_VAULT (or the legacy CLAUDE_OBSIDIAN_VAULT), by the nearest .codex-obsidian.json or .claude-obsidian.json, or by one unambiguous initialized ancestor. If selection is uncertain, the command exits without writing.

One logical knowledge operation is one recoverable transaction:

  1. Read every target and record its expected SHA-256.
  2. Let parallel workers return drafts and evidence only.
  3. Merge the complete change into one operation bundle.
  4. Inspect the bundle, then apply it once.
  5. Report the operation ID and exact changed paths.

The core holds one process-lifetime vault lock, journals backups, uses atomic replacement, and restores the prior state if an apply cannot finish. A changed target is a conflict, never a silent overwrite. Git checkpoints, destructive repairs, network egress, and canonical research merges remain explicit operations.

Read the transaction contract, provenance contract, and Compound Vault architecture for the machine-facing detail.

Honest capability boundaries

Input or capabilityCurrent support
Local filesystem sourcesImplemented bounded, content-addressed byte capture
ImagesMetadata, hash, size, and bounded dimensions when available
PDF and EPUBMetadata, hash, and size; no built-in semantic extraction
URL and YouTubeValidated consent plans; a configured external runner is required
OCRLocal-file consent plan; a configured external runner is required
BM25 retrievalLocal and deterministic
Contextual prefixes or remote modelsOptional and gated by explicit egress consent
Obsidian CLIOptional for reads/search; filesystem transport remains available

High-risk accepted claims require two independent sources. Unsupported or contradictory evidence stays visible, and a grounded refusal is preferred over an invented citation. Model-based retrieval falls back to deterministic BM25 when the embedding or reranking stage cannot be trusted.

Shape the vault to the way you think

wiki-mode can route new notes using four methodologies without bulk-moving existing knowledge:

ModeFiling principle
GenericSources, concepts, entities, and sessions
LYTMaps of Content and linked atomic notes
PARAProjects, Areas, Resources, and Archives
ZettelkastenStable identifiers, atomic notes, and dense links

Generic is the default when no mode is configured. Switching modes changes how new notes are routed; it does not silently reorganize old ones. See the methodology modes guide.

Operator reference

Portable CLI

The wrapper is python scripts/codex-obsidian.py (python3 on macOS/Linux).

CommandEffect
doctor --vault PATHShow vault selection and readiness
init PATH [--approved-plan-sha256 HASH --apply]Plan or create a separate vault
adopt PATH [--approved-plan-sha256 HASH --apply]Plan or adopt an existing Obsidian vault
migrate --vault PATH [--approved-plan-sha256 HASH --apply]Add v1 ledgers and configuration without rewriting legacy data
transaction inspect BUNDLE --vault PATHValidate a write bundle without mutation
transaction apply BUNDLE --vault PATH --approved-plan-sha256 HASHApply one inspected, recoverable operation
transaction recover --vault PATH [--force-stale-lock]Restore an interrupted operation
lint --vault PATH [--as-of YYYY-MM-DD] [--exclude GLOB]...Emit findings deterministic for the declared UTC date
contracts --verify --vault PATHExecute capability readiness contracts
capture plan --vault PATH [SOURCE ...]Run a local capture preflight without writes
capture apply --vault PATH [SOURCE ...]Plan or create immutable content-addressed copies
checkpoint OPERATION_ID --vault PATHExplicitly commit one completed operation
package validateCheck skills, hooks, manifests, and documentation coherence
release build --output FILE.zipBuild and self-audit a deterministic public artifact
release audit FILE.zipAudit an artifact without extracting or publishing it

High-level mutating planners emit approved_plan_sha256. Pin --generated-at and --operation-id, review the JSON operation, and pass that exact hash with --apply. Filesystem or generated-bundle drift fails before a vault write.

Repository and vault layout

product repository/                user vault/
├── claude_obsidian/               ├── .gitignore
├── skills/                        ├── .codex-obsidian.json
├── hooks/                         ├── inbox/
├── scripts/                       ├── .raw/
├── templates/vault/               ├── wiki/
├── config/                        ├── .obsidian/
├── assets/                        └── .vault-meta/   # ignored runtime state
└── tests/

Public artifacts contain product code, deterministic templates, and reviewed README assets. They reject contributor hot/log state, root raw sources, runtime metadata, private paths, recognizable personal email addresses, secrets, symlinks, unsafe archive entries, and unreviewed binaries.

The private development checkout deliberately has no marketplace catalog. The release builder injects the reviewed catalog only into the distribution-clean artifact. A public default branch must be populated from that audited tree, never by pushing contributor-vault state.

Upgrade, rollback, and uninstall

Upgrade the product independently from the vault. For an older vault, first preview the additive, idempotent migration:

python scripts/codex-obsidian.py migrate --vault /path/to/vault \
  --generated-at "$GENERATED_AT" --operation-id migrate-reviewed

Review its hash and rerun with --approved-plan-sha256 HASH --apply. Migration preserves the legacy raw manifest byte-for-byte and does not infer claims from prose.

After an interrupted operation, run:

python scripts/codex-obsidian.py transaction recover --vault /path/to/vault

Removing the plugin or host links never removes the vault. Delete only the integration you installed; user notes, sources, ledgers, and Obsidian settings remain yours.

Requirements

  • Python 3.11 or newer for the portable core
  • Obsidian for the visual vault experience; plain Markdown remains usable without it
  • Bash only for the legacy .sh wrappers and shell test suites; the canonical .py entry points need no shell
  • Git only for development, releases, or an explicit knowledge checkpoint
  • A Codex release that supports plugins and lifecycle hooks. Install the plugin through codex plugin marketplace add and /plugins; hooks are optional and reviewed separately under Settings > Hooks.

Windows, WSL, Linux, and macOS are all supported. Native Windows now performs vault writes; it uses a path-based mutation lock and bounded runtime-directory checks instead of POSIX directory descriptors. The reduced guarantee is documented in the Windows guide. Approval hashes bind to the environment that produced them, so review and apply in the same environment. Optional tools such as Obsidian CLI, Ollama, and defuddle are capability-detected and affect only their dependent workflow.

Development and release

python tests/run_tests.py

The runner executes every tests/test_*.py file in its own process. On native Windows it skips the upstream adversarial tests that need POSIX symlink privileges or bash wrappers, and fails on everything else. make test additionally runs the shell suites and package contracts on macOS/Linux.

Build and audit locally without publishing:

python scripts/codex-obsidian.py release build --output dist/codex-obsidian.zip
python scripts/codex-obsidian.py release audit dist/codex-obsidian.zip

No command pushes, tags, publishes, opens issues, or creates releases automatically. See CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md.

Lineage, license, and attribution

The design follows Andrej Karpathy's LLM Wiki pattern and uses kepano/obsidian-skills as the reference substrate for Obsidian Markdown, Bases, and JSON Canvas syntax.

codex-obsidian is a derivative of AgriciDaniel/claude-obsidian (MIT). The vault model, skill contracts, and transaction design come from that project; this repository changes the host adapter and the Windows write path.

MIT licensed. See ATTRIBUTION.md and CITATION.cff.