The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Obelisk listing page.
Inline comments and GitHub-style suggested edits for Obsidian.
Select a passage, leave a comment on it, and optionally propose a replacement that can be applied with one click. Comments are stored in the note's own frontmatter, so they travel with the file through sync, git, export and rename.
An obelus (†) was the mark ancient editors drew in the margin of a manuscript to say: this passage is disputed.
Early. Anchoring, decoration, the sidebar, suggested edits and the agent
integration are implemented. The plugin is in the Obsidian community plugin
directory, and the CLI and the MCP server are on npm as obelisk-mcp. None of
it has been exercised against a large vault.
Search for Obelisk in Settings → Community plugins → Browse, install it, and enable it. Updates come from the same panel.
The plugin can also be added via the Add to Obsidian button in its directory listing.
```suggestion block inside
the comment, the way GitHub does it. It renders as a diff against the quoted
passage with an Apply button, so one comment can explain itself and propose a
change, and a reply can offer a counter-proposal. Applying is refused if the
underlying text has changed since. It also resolves the comment, and Reopen
is there if the comment asked something the edit did not answer.obelisk key. Readable,
diffable, portable.[[ autocompletion and live
preview work in a comment exactly as they do in a note.A comment is one piece of markdown. A proposed edit is a ```suggestion
fenced block inside it, whose content replaces exactly the anchored range when
applied, so one comment can hold prose, a link and a proposal at once.
The quote is what a comment is anchored by. The line/column range records
where the passage was when the comment was written. It orders the sidebar and
breaks ties when a quote appears twice, and is never rewritten. Lines are
counted from the first line after the frontmatter block, so adding a comment
never invalidates the others.
A comment written by a model carries one more key, origin, holding the model
and an id shared by every comment in that review pass. Its absence means a
person wrote it, so nothing already in a vault needs migrating.
The same comments, from outside Obsidian. A model reviews a note and its remarks appear in the sidebar of the note you already have open. Or you leave comments asking for things and a model reads them, makes the edits, and resolves them.
For an agent that speaks MCP, register the server with it:
One registration covers every vault: the tools work on whichever vault the
agent is running in, and an absolute path reaches a note in one it is not. The
server is listed in the official MCP registry as io.github.zachhannum/obelisk
for a client that installs from there.
The agent starts it. It speaks MCP over stdio: the agent spawns a process
when a session opens and kills it when the session ends, so there is no port
and no daemon. One process per session is also what makes a session's comments
share one run chip in the sidebar. A session keeps the process it spawned, so a
new version of the package arrives at the next one. To take it sooner,
reconnect from /mcp.
To check the registration, claude mcp list, or /mcp inside a session. To
check the server itself with no agent in the way:
That prints the handshake and then the four tools. A server that fails this fails the same way for an agent.
For an agent that does not speak MCP, paste
docs/agents-fragment.md into the vault's
AGENTS.md or CLAUDE.md.
The one rule worth knowing: the quote is the anchor. A line number is never
one. A model asked for a line produces a plausible wrong number, which attaches
a comment to the wrong paragraph without looking like an error, so
--near-line only picks between identical quotes and takes a number copied out
of obelisk list. --quote has to appear in the note character for character,
and if it does not, or appears twice, nothing is written and the reason is
printed. obelisk list prints the body numbered so the exact text is there to
copy.
Writes are frontmatter-only and leave the body byte-identical, so they are safe while the note is open in Obsidian. A write also re-reads the file first and refuses if it changed underneath.
src/core/ is the half that does not import Obsidian: the model, the anchor
arithmetic, the YAML and the four verbs. The plugin, the CLI and the MCP server
are three front ends over it.
site/ is the documentation site, an Astro project of its own with its own
npm install. It is not part of npm run build.
Symlink the repo into a test vault to try it:
MIT