Codex Obsidian

<p align="center"> <a href="README.md">English</a> · <a href="docs/README.zh-CN.md">简体中文</a> · <a href="docs/README.ja.md">日本語</a> </p>

<p align="center"> <img src="assets/codex-obsidian-cover.svg" alt="Codex Obsidian: a Codex-native Obsidian wiki companion" width="100%" /> </p>

<p align="center"> <a href="https://github.com/aidehua08/codex-obsdian"><img alt="Codex native" src="https://img.shields.io/badge/Codex-native-111827?style=flat-square"></a> <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-2563eb?style=flat-square"></a> <a href="https://obsidian.md"><img alt="Obsidian" src="https://img.shields.io/badge/Obsidian-ready-7c3aed?style=flat-square"></a> <a href="plugins/codex-obsdian/skills"><img alt="Skills" src="https://img.shields.io/badge/Skills-15-0f766e?style=flat-square"></a> <a href="tests/test_codex_obsidian.py"><img alt="Tests" src="https://img.shields.io/badge/Tests-unittest-f97316?style=flat-square"></a> </p>

Codex Obsidian turns Codex into an Obsidian-native knowledge companion: a local, plain-Markdown wiki that remembers sources, links concepts, retrieves prior context, saves sessions, lints itself, and compounds over time.

It is a Codex-native full core port of claude-obsidian: the upstream skills, scripts, installers, agents, hooks, tests, Obsidian config, templates, seed vault, and wiki assets are preserved, with Codex marketplace metadata, installable plugin manifest, Codex subagents, and macOS-compatible lock fixes added on top.

Why This Exists

Most AI memory systems hide your knowledge in an app, an index, or a chat history you cannot really inspect. Codex Obsidian keeps the substrate boring on purpose:

• You own the files: Markdown, JSON, and Obsidian Canvas in your repo or vault.
• Codex owns the workflow: skills decide when to set up, ingest, retrieve, save, fold, lint, or draw.
• Sources stay intact: .raw/ is append-only evidence; wiki/ is the synthesized knowledge layer.
• Context compounds: wiki/hot.md, wiki/log.md, source notes, concept pages, entities, and questions keep future work warm.

Quick Start

Install from a local checkout:

git clone https://github.com/aidehua08/codex-obsdian.git
cd codex-obsdian
codex plugin marketplace add "$(pwd)"
codex plugin add codex-obsdian@aidehua08-codex-obsdian

Start a new Codex thread after installing so the skills are loaded.

Then try:

Set up an Obsidian wiki vault here.
Ingest this file into my wiki.
Query the wiki for our recent decisions.
Save this session to Obsidian.
Lint the wiki.
Create a canvas for this topic.

What Gets Created

your-project/
├── .raw/                    # immutable source captures
│   └── .manifest.json       # source tracking and hashes
├── .vault-meta/             # locks, modes, local metadata
└── wiki/
    ├── hot.md               # active context Codex reads first
    ├── index.md             # navigation hub
    ├── log.md               # chronological work log
    ├── sources/             # source notes
    ├── concepts/            # durable ideas
    ├── entities/            # people, orgs, projects, products
    ├── questions/           # evergreen questions and answers
    ├── folds/               # compacted summaries
    └── canvases/            # Obsidian Canvas JSON

Capabilities

Codex-Native Structure

This repository is an installable Codex marketplace, not a folder of loose prompts:

codex-obsdian/
├── .agents/plugins/marketplace.json
├── .codex/agents/                 # Codex subagents
├── .obsidian/                     # Seed Obsidian config
├── .raw/                          # Seed raw source area
├── .vault-meta/                   # Locks, counters, retrieval state
├── agents/                        # Upstream Claude agent source
├── bin/                           # Setup scripts
├── commands/                      # Upstream slash-command source
├── hooks/                         # Upstream hook config
├── scripts/                       # Retrieval, locks, DragonScale, mode tooling
├── skills/                        # Root skill mirror
├── tests/                         # Upstream tests plus Codex smoke test
├── wiki/                          # Seed wiki vault
├── plugins/codex-obsdian/
│   ├── .codex-plugin/plugin.json
│   ├── skills/                    # Full installed skill set
│   ├── scripts/                   # Full installed helper set + codex_obsidian.py
│   ├── bin/ _templates/ hooks/
│   ├── .obsidian/ .raw/ .vault-meta/
│   └── wiki/
└── docs/

Architecture

flowchart LR
    A["User asks Codex"] --> B["Codex skill router"]
    B --> C["Wiki setup"]
    B --> D["Ingest"]
    B --> E["Retrieve"]
    B --> F["Save / Fold / Lint"]
    C --> G["wiki/ + .raw/"]
    D --> H[".raw/.manifest.json"]
    D --> I["wiki/sources"]
    E --> J["wiki/hot.md + wiki pages"]
    F --> K["wiki/log.md + wiki/folds"]
    G --> L["Obsidian"]
    H --> L
    I --> L
    J --> L
    K --> L

The bundled helpers handle repeatable file operations:

python3 plugins/codex-obsdian/scripts/codex_obsidian.py --root . init
python3 plugins/codex-obsdian/scripts/codex_obsidian.py --root . ingest-file ./source.md
python3 plugins/codex-obsdian/scripts/codex_obsidian.py --root . query "search terms"
python3 plugins/codex-obsdian/scripts/codex_obsidian.py --root . lint
python3 plugins/codex-obsdian/scripts/codex_obsidian.py --root . save --title "session" --text "summary"
bash plugins/codex-obsdian/bin/setup-retrieve.sh
python3 plugins/codex-obsdian/scripts/retrieve.py "query"
bash plugins/codex-obsdian/scripts/wiki-lock.sh acquire wiki/concepts/Foo.md

Codex still does the high-value work: synthesis, linking, judgment, source-grounded explanation, and deciding what belongs in long-term memory.

Skills

Methodology Modes

Codex Obsidian supports four organization modes:

• Generic: sources, concepts, entities, questions.
• LYT: maps of content and link-first navigation.
• PARA: projects, areas, resources, archives.
• Zettelkasten: atomic notes and evergreen links.

Ask Codex to switch modes naturally:

Switch this vault to PARA mode.
Use Zettelkasten-style atomic notes for this research.
Create an LYT map of content for this topic.

Compared With Claude Obsidian

The goal is not to hide the lineage. The goal is to make the same idea feel native in Codex.

Verification

python3 /Users/edward/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/codex-obsdian
for d in plugins/codex-obsdian/skills/*; do \
  python3 /Users/edward/.codex/skills/.system/skill-creator/scripts/quick_validate.py "$d"; \
done
python3 -m unittest discover -s tests -v
make test

FAQ

Is this an Obsidian plugin?<br> No. It is a Codex plugin that writes an Obsidian-compatible vault.

Does it require Obsidian to run?<br> No. Codex can create and maintain the Markdown files without Obsidian. Obsidian is the best visual/editor layer.

Does it upload my notes?<br> No. The vault is local plain text unless you choose to sync it.

Can I use an existing vault?<br> Yes. Run Codex from inside the vault or point the CLI at the vault root.

Why keep `.raw/` separate from `wiki/`?<br> Because source evidence and synthesis should not be mixed. Raw files are preserved; wiki pages can evolve.

Attribution

Codex Obsidian ports the workflow ideas from AgriciDaniel/claude-obsidian into a Codex-native plugin package. See ATTRIBUTION.md and docs/source-breakdown.md.

License

MIT. See LICENSE.