Codex Obsidian Loop

A task-driven Codex + Obsidian workflow for agent memory, source boundaries, and durable result writeback.

This repository packages a small agent skill plus a starter vault template. It is inspired by the LLM+wiki pattern: let the agent do task work, but keep durable project knowledge in a wiki-like system that can be queried, corrected, and reused.

The core loop is simple:

query -> work -> checkpoint/closeout writeback -> lint

Codex drives the task. Obsidian stores the project wiki. The loop connects them: read the minimum relevant context, do the work, write back only reusable conclusions, then lint the vault so it does not accumulate stale facts, broken links, or noisy process logs.

What This Is For

Use this workflow when you repeatedly collaborate with Codex or another AI agent on work where context loss is expensive:

• product design and planning
• UX or research synthesis
• strategy and positioning
• technical architecture notes
• release-gate tracking
• decision records
• source-backed internal knowledge bases
• long-running projects that need continuity across threads

It is intentionally domain-neutral. Bring your own product, team, project, or research context.

Repository Contents

.
├── skills/codex-obsidian-loop/SKILL.md          # Agent skill entrypoint
├── vault-template/                        # Copy this to start a vault
│   ├── AGENTS.md
│   ├── raw/
│   ├── wiki/
│   ├── workbench/
│   ├── decisions/
│   └── system/
├── examples/product-design/README.md      # Example adaptation notes
├── docs/sanitizing-private-vaults.md      # How to make a private workflow public-safe
├── evals/evals.json                       # Starter test prompts
├── .claude-plugin/                        # Marketplace metadata compatible with skill/plugin installers
└── .codex-plugin/                         # Codex plugin metadata

Install

Marketplace-Style Install

Use the GitHub repository as a plugin source:

/plugin marketplace add zhouxifox6249-byte/codex-obsidian-loop
/plugin install codex-obsidian-loop@codex-obsidian-loop

Depending on your client, the equivalent CLI form may be:

codex plugin marketplace add zhouxifox6249-byte/codex-obsidian-loop
codex plugin add codex-obsidian-loop@codex-obsidian-loop

Manual Skill Install

Copy the skill directory into your local skills folder:

cp -R skills/codex-obsidian-loop ~/.codex/skills/codex-obsidian-loop

Then copy vault-template/ somewhere stable and customize it for your project.

Quick Start

1. Copy vault-template/ to a project-specific folder.
2. Fill in:
   • wiki/source-of-truth.md
   • wiki/current-direction.md
   • system/source-map.md
3. Install or expose skills/codex-obsidian-loop/SKILL.md to your agent.
4. Start a task with:

Use $codex-obsidian-loop with my project vault.

Goal:
Background:
Existing material:
Constraints:
Done means:

Before answering, give me a short query plan: task type, context to read, sources that are stale or exploratory, and likely writeback target.

5. At a natural checkpoint, ask:

Save this stage as a checkpoint. Do not log the chat; only record the current conclusion, sources, decision candidates, open questions, and next action.

6. At closeout, ask:

Close out this task using the vault rules. Update the relevant workbench note, promote only stable source-backed facts to wiki, append important decisions, update open questions, and run lint.

Vault Model

The template uses five stable layers:

Design Principles

• Do not invent facts to fill gaps.
• Separate source-backed facts, user preferences, hypotheses, decisions, and open questions.
• Read narrowly before working.
• Treat old notes, prototypes, and external summaries as lower-priority unless promoted.
• Write back only reusable conclusions, not process logs.
• Promote to wiki/ only when facts are stable and source-backed or user-confirmed.
• Keep decisions/decision-log.md append-only.
• Run lint after writeback.

Optional Obsidian Helpers

This workflow pairs well with Obsidian-specific skills such as:

• obsidian-markdown for frontmatter, wikilinks, callouts, embeds, and properties
• obsidian-bases for .base views
• json-canvas for .canvas diagrams
• obsidian-cli when you need to interact with a running Obsidian app

Those helpers handle file formats. codex-obsidian-loop handles project memory, source boundaries, and writeback decisions.

Public-Safety Notes

Before publishing your adapted vault or examples:

• Remove private company, customer, employee, and repository names.
• Remove local absolute paths.
• Remove credentials, tokens, internal URLs, and raw exports.
• Replace business-specific facts with placeholders or fictional examples.
• Keep only the reusable workflow and templates.

See docs/sanitizing-private-vaults.md.

License

MIT. Replace the copyright holder in LICENSE before publishing.