Vulcan

Pre-alpha: Vulcan is moving fast and still contains a large amount of LLM-written code. Treat it as experimental, keep backups, and use git or another versioning system before pointing it at important vaults.

Vulcan is a local-first Rust information hub for Obsidian-style vaults and plain Markdown directories. It indexes canonical Markdown into a rebuildable local SQLite cache, then exposes search, graph queries, Dataview/Bases-style metadata, TaskNotes workflows, publishing, scripting, MCP tools, and safe note mutations without requiring Obsidian to be running.

The current implementation includes the local CLI and MCP server plus a multi-vault synchronization daemon built on the shared vulcan-core and vulcan-app workflows. Outline already has first-class named subtree routes and exact local-note/remote-document bindings. Later connector layers extend the same inspectable hub model to SilverBullet, Git wikis, and HedgeDoc without making their databases or Vulcan's cache authoritative.

What It Can Do

• Index and query Markdown vaults: incremental scanning, frontmatter, tags, wikilinks, embeds, aliases, block refs, attachments, and diagnostics.
• Search and explore: SQLite FTS5, Obsidian-like search operators, graph traversal, backlinks/outgoing links, communities, suggestions, and optional vector search via sqlite-vec.
• Use structured knowledge models: Dataview DQL, inline fields, inline expressions, .base views, task queries, TaskNotes, recurring tasks, dependencies, Kanban boards, periodic notes, and an emerging pinned mdbase v0.3 compatibility layer.
• Edit safely: note get/create/append/patch/set/delete/rename, task create/complete/reschedule/archive, property updates, refactors, dry-run reports, link rewriting, and permission profiles.
• Publish, import, and route: Markdown, JSON, CSV, Graph, EPUB, ZIP, SQLite, static search indexes, frontend bundles, full static sites, Outline-compatible ZIPs, conflict-aware Outline publication/pull, exact document bindings, and named subtree mirror routes.
• Automate locally: JSON output on commands, saved reports, automation runs, checkpoints, shell completions, JavaScript scripting with sandbox tiers, custom skills, skill commands, and plugins.
• Synchronize devices: finite Git-backed vault synchronization, deterministic conflict preservation and reviewed resolution, multi-wiki daemon scheduling, plus detached Git directories for Obsidian-visible Android/Termux storage.
• Integrate with agents: vulcan describe, OpenAI tool schemas, MCP stdio/HTTP, ChatGPT-compatible OAuth/IndieAuth, tool packs, resources, prompts, and Agent Skills-compatible vault guidance.

Quick Start

Versioned release archives for Linux, macOS, and Windows include the binary, generated shell completions, a man page, install notes, checksums, and license files. Releases also provide native amd64/arm64 Debian packages. The checksum-verifying installers require an explicit version and do not enable the daemon:

curl -fsSL https://raw.githubusercontent.com/tionis/vulcan/v0.1.0/scripts/install.sh | \
  sh -s -- --version 0.1.0 --dry-run

On Windows, download scripts/install.ps1 from the matching tag and run ./install.ps1 -Version 0.1.0 -DryRun. Review the installation guide before removing --dry-run; Git remains a separate runtime dependency for synchronization.

Manual portable installs can check the stable stream with vulcan self-update check. A bounded rolling build from eligible main commits is available through --channel main; update descriptors are currently unsigned, so either stream requires the explicit --allow-unsigned checksum-only opt-in until project signing keys are configured. Package-managed installations should update only through their package manager. See the update-channel specification.

Vulcan requires Rust 1.88 or newer. With rustup, the checked-in rust-toolchain.toml installs and selects the supported toolchain automatically. Build the CLI:

cargo build --release -p vulcan-cli --bin vulcan

Initialize and scan a vault:

./target/release/vulcan --vault ~/notes index init
./target/release/vulcan --vault ~/notes index scan

Try common workflows:

vulcan --vault ~/notes browse
vulcan --vault ~/notes search 'meeting notes'
vulcan --vault ~/notes query 'FROM "Projects" WHERE status = "active"'
vulcan --vault ~/notes note get "Projects/Alpha.md" --output json
vulcan --vault ~/notes daily today
vulcan --vault ~/notes tasks list --output json
vulcan --vault ~/notes export markdown 'tag:publish' --path public.md
vulcan --vault ~/notes export outline-zip --collection-title Wiki --path wiki.zip
vulcan --vault ~/notes export outline-zip --profile wiki --path wiki.zip
vulcan --vault ~/notes outline collections list wiki
vulcan --vault ~/notes publish outline wiki --create-collection
vulcan --vault ~/notes integration validate players
vulcan --vault ~/notes integration plan players
vulcan --vault ~/notes site build
vulcan --vault ~/notes doctor

For external agent runtimes and MCP clients:

vulcan --vault ~/notes agent install
vulcan --vault ~/notes describe --format mcp
vulcan --vault ~/notes mcp --transport stdio --tool-pack notes-read,search,status

Configuration

Vulcan stores vault-local state under .vulcan/:

• .vulcan/config.toml: shared vault configuration, usually committed with the vault
• .vulcan/config.local.toml: device-local overrides, ignored by default
• .vulcan/cache.db: rebuildable SQLite cache
• .vulcan/publish/: durable publisher mappings such as Outline source-to-document identity, stored outside the rebuildable cache
• .vulcan/integrations/: durable pull identities, content snapshots, conflict journals, and named-route run state, stored outside the rebuildable cache

Use vulcan config ... and vulcan help config for the editable config surface. Vulcan can import settings from supported Obsidian plugins with vulcan index init --import or vulcan config import --all.

Automation And Agent Surfaces

Vulcan has several automation layers with different jobs:

Surface	Use It For
CLI JSON	Shell scripts, CI, direct command automation
vulcan run	One-off JavaScript scripts against the vault API
Skills	Agent-readable workflow instructions and references in .agents/skills/
Skill commands	Typed callable tools inside skills, exposed to CLI, MCP, describe, and JS
Plugins	Event-driven lifecycle hooks such as note-write or pre-commit checks
MCP	ChatGPT/Claude/Codex-style tool clients with permission profiles and tool packs

For a private ChatGPT connector, see docs/guide/chatgpt-mcp.md. The recommended setup uses HTTPS, Vulcan's embedded OAuth issuer, IndieAuth for human login, Dynamic Client Registration when useful, and a narrow permission profile.

Documentation

• Getting started: first commands and conventions
• CLI guide: command catalogue and examples
• Filters and query DSL: selection syntax
• Scripting, sandboxing, and automation surfaces
• Skill commands and custom tools
• ChatGPT MCP setup
• Static sites
• Outline publishing
• Git-backed device synchronization: direct Linux/Windows operation and detached Android/Termux setup
• Installation and daemon services: release archives, upgrades, native user services, and state-preserving removal
• Obsidian companion: authenticated status, sync triggers, and dry-run-first conflict review
• Local information hub and external wikis: current integration baseline and planned binding/route/connector architecture
• Design document: architecture and crate boundaries
• Roadmap: implementation status and planned phases
• Hardening: verification matrix and boundary checks

The integrated help system mirrors much of this documentation:

vulcan help
vulcan help filters
vulcan help assistant-integration
vulcan help custom-tools

Workspace Layout

Crate	Purpose
vulcan-core	Synchronous vault semantics: parser, indexer, cache, config model, query/search/graph/task logic, permissions, optional JS/web/OAuth/vector features
vulcan-app	Reusable synchronous workflows over vulcan-core: note/task/template/export/site/config/plugin/tool orchestration without terminal UI
vulcan-embed	Embedding provider trait and vector store implementations
vulcan-cli	The vulcan binary: clap surface, terminal output, TUI/editor integration, MCP stdio/HTTP server, completions
vulcan-daemon	Async HTTP/WebSocket transport, multi-vault registry state, background scheduling, and native service lifecycle

Development Checks

Run these before committing:

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo check --workspace --no-default-features

Feature and boundary expectations are documented in docs/hardening.md. The repository also has boundary tests to keep CLI, app, core, MCP, JS, web, OAuth, and vector responsibilities from drifting back together.