paivot-graph

paivot-graph

A Claude Code plugin that turns an Obsidian vault into a living runtime for AI agents. Agents read their instructions from the vault, capture knowledge as they work, and refine their own prompts based on experience. The vault evolves with every session.

Prerequisites

1. vlt (required)

You must install vlt before using this plugin. vlt is the fast, standalone CLI that all hooks, commands, and agents use to interact with your Obsidian vault.

# From source (requires Go 1.24+)
git clone https://github.com/paivot-ai/vlt.git
cd vlt
make install

# Verify
vlt version   # should print vlt 0.9.0+

Pre-built binaries are available at vlt releases if you don't have Go installed.

Without vlt, the plugin falls back to direct filesystem operations (grep, cat) which are slower, lack vault-aware features (alias resolution, wikilink repair, backlink tracking), and miss the inert zone masking that prevents false positives.

2. nd (recommended for execution)

nd is the issue tracker Paivot uses for execution. The on-disk format is git-native markdown, but for multi-branch execution the live backlog should be branch-independent rather than copied into each story branch checkout. See docs/LIVE_SOR.md.

# From source (requires Go 1.22+)
git clone https://github.com/paivot-ai/nd.git
cd nd
make build
make install    # Installs to ~/.local/bin/nd

# Verify
nd --help

Pre-built binaries are available at nd releases.

Without nd, the vault-knowledge and vault-lifecycle features still work (hooks, commands, skills), but the execution agents (developer, PM, Sr PM, anchor, retro) cannot manage work items.

3. pvg (required)

pvg is the shared control plane Paivot uses for guardrails, live nd routing, loop recovery, and story helpers. paivot-graph shells out to the installed pvg binary; make install checks that it is already on your PATH.

# Pre-built binaries
gh release download -R paivot-ai/pvg -p '*darwin*arm64*' -D /tmp
tar xzf /tmp/pvg_*.tar.gz -C ~/go/bin

# Or from source (requires Go 1.24+)
git clone https://github.com/paivot-ai/pvg.git
cd pvg
make install

# Verify
pvg version

4. Codebase indexing MCP server (strongly recommended)

A codebase indexing MCP server dramatically improves story quality. When available, Paivot agents use it for API signature verification, cross-cutting concern discovery, and module count validation instead of grep. This prevents the most common class of Anchor rejections: hallucinated API signatures.

Any MCP server that provides search_graph, get_code_snippet, and trace_call_path works. Two tested options:

• codebase-memory-mcp -- Graph-based indexing with Cypher queries, call path tracing, and architecture summaries
• Augment Code (cx) -- Commercial codebase intelligence with similar capabilities

Install via .mcp.json in your project or ~/.claude/settings.json. After indexing, agents automatically prefer MCP tools over grep for codebase queries.

Without a codebase indexing server, agents fall back to grep/ripgrep. This works but is slower, less precise on call graph analysis, and cannot verify module counts as reliably.

5. Obsidian vault

You need an Obsidian vault that vlt can discover. The plugin expects a vault named "Claude" by default. If you don't have one:

1. Open Obsidian and create a new vault named "Claude"
2. Verify vlt can see it: vlt vaults

6. Claude Code

This is a Claude Code plugin. You need Claude Code installed.

Installation

git clone https://github.com/paivot-ai/paivot-graph.git
cd paivot-graph
make install

This does four things:

1. Checks that vlt and Claude Code are installed
2. Verifies that pvg is on PATH
3. Fetches the vlt skill from GitHub and installs it to ~/.claude/skills/vlt-skill (teaches Claude how to use vlt effectively)
4. Registers the plugin with Claude Code's marketplace and installs it

Restart any open Claude Code sessions for hooks to take effect.

If something goes wrong

If a session gets into a bad state, use the smallest escape hatch that solves the problem: