VibeDNA Journal

Journals DNA

Your AI cannot skip your journal.

Journals DNA gives every project one markdown journal ( _JOURNAL.md) that your AI reads before it acts and writes to while it works. The next session, or another AI, picks up exactly where the last one stopped, and you can share your work with anyone by sending the journal.

It runs on your machine. Your journals stay where they are, in plain markdown.

What it does, in plain words

• Journals your AI must read. In Claude Code, the journals mod stops the first edit of a piece of your project until the AI has really read that piece's journal. A plain retry does not get through; reading the journal does.
• A map before every change. Before your AI edits a file, runs a command or briefs an agent, it sees a short map of that thing: which journal talks about it, who is working on it now, what was already decided, what already exists, the latest entries and what is still pending.
• It warns when your AI repeats itself. When the AI is about to build its own way of doing a job a tool you already have does, it is shown that tool and stopped once. When a reply proposes something your journals already have a verdict on, or lists as pending something a journal says shipped, the AI is told so in its next turn.
• It warns about stale status. Lines that state something that changes (an account is active, a service is live, a balance) are marked "check live before repeating it" in the map. When the AI writes an entry that states such a status without saying how it was checked, the entry is still saved and the AI gets a warning.
• Your rules, in your words. Write your rules as dated lines in a rules journal (RULES_JOURNAL.md or any *_RULES_JOURNAL.md). When an action shares the words of a rule, the rule is shown and the action stops once.
• Finds what you meant, in any language (optional). A small model on your own processor gives every entry a meaning, so a question in other words or another language finds the entry that says the same thing. Your journals never leave your computer.
• Old decisions never pass as current. When a later entry replaced a decision, or states a different price or number for it, the decision is shown with that newer line first and your AI checks the live source and updates it.
• It stops rebuilding what already exists. Before your AI writes a new script or briefs an agent to build something a shipped entry already did, it is shown that entry and stopped once.
• Your decisions guard the reply (optional). Each project gets an owner brief: your rules, what you already tried and lost, and the thread you approved. With the reply check on, a reply that proposes again what you rejected, or describes one of your tools against its own sheet, is sent back for a rewrite before you read it.
• Old rules carry their newer word. A rule or decision older than a week is shown with the newer entry that changed it, so your AI never follows an outdated rule as current.
• A calm status line. Under your prompt: Journals DNA · active, and one plain sentence only when something real happens.
• Opens in Obsidian. One command builds a map of all your journals for Obsidian: a START HERE page, a table view of every journal, and a canvas by folder. New journals are born with Obsidian properties.

What is inside

New in 1.4.0

• A calm status line: Journals DNA · active, one plain sentence per real event, never internal wording.
• Newer word on old rules: an old rule or decision is shown with the newer entry that changes it.
• The reply check against your own decisions (opt in: JOURNAL_REPLY_GATE=on with the judge on): a reply that breaks your rules or proposes again what you already lost is sent back before you read it, with the words quoted.
• Judged manual hints: a lesson is pointed at one of your manuals only when the judge agrees it belongs there.
• Your own tools in tools.json: a message that names one carries what it does today.
• The judge is optional and off by default; without it the checks fall back to the rules of 1.3.0. See INSTALL.md.

Install

Full steps, written so you can hand the file to your AI: INSTALL.md. Short version, from this folder:

python3 -m venv .venv

.venv/bin/pip install -r requirements.txt # Windows: .venv\Scripts\pip install -r requirements.txt .venv/bin/python install_mod.py --dry-run # Windows: .venv\Scripts\python install_mod.py --dry-run .venv/bin/python install_mod.py # Windows: .venv\Scripts\python install_mod.py

Then open a new Claude Code session and ask: journal_quick(" ").

Other MCP clients (Cursor and others) can run server.py as a normal MCP server; the mod and its stops are a Claude Code feature.

The tools

Open your journals in Obsidian

.venv/bin/python obsidian.py vault --root "<your projects folder>"            # dry run: lists what it would write

.venv/bin/python obsidian.py vault --root " " --apply # writes it

It writes _obsidian/START HERE.md, _obsidian/Journals.base, _obsidian/Journals map.canvas and a minimal .obsidian/ config in that folder, then you open the folder as a vault in Obsidian. Details in INSTALL.md.

Your data

Everything is local: the journals are your files, the index lives in ~/.journal. The quick map and the mod make no network calls. The store tools (journal_market, journal_get, ...) and check_for_update talk to vibedna.ai only when you call them. See SECURITY.md.

Vibedna, vibedna.ai