Crate vagus_plugin 

SDK for building vagus plugins — standalone vagus-<name> binaries that vagus core dispatches to (the git/kubectl/gh-extension pattern). See docs/plugin-contract.md.

Using this crate is optional: a plugin in any language can speak the protocol directly. In Rust it saves you from re-implementing the wire format, the env contract, and the vault-write guard.

Minimal plugin

use vagus_plugin::{Emitter, describe, is_describe};

fn main() -> std::io::Result<()> {
    let args: Vec<String> = std::env::args().skip(1).collect();
    if is_describe(&args) {
        describe("vagus-hello — example plugin");
        return Ok(());
    }
    let mut out = Emitter::from_env();
    out.progress(1, Some(1), "working");
    out.write_note("30-Resources/hello/note.md", "# hi\n\nfrom a plugin\n")?;
    out.result_ok(serde_json::json!({ "notes": 1 }));
    Ok(())
}

Re-exports

pub use vagus_plugin_protocol as protocol;

Structs

Emitter

Emits Events to core (NDJSON mode) or renders them for a human (standalone mode).

Constants

DESCRIBE_SUBCOMMAND

Reserved discovery subcommand: vagus-<name> __describe prints a one-line summary on stdout for vagus plugins. Used by both core (caller) and the SDK (callee).

Functions

config_dir

This plugin’s own config dir: ~/.config/vagus-<name>/ (XDG, even on macOS — to sit alongside vagus core, which deliberately uses XDG paths). Core never reads it. Respects $XDG_CONFIG_HOME.

data_dir

This plugin’s own state/cache dir: ~/.local/share/vagus-<name>/ (XDG) — outside iCloud (G1). Respects $XDG_DATA_HOME.

describe

Print a one-line description for vagus plugins discovery.

is_describe

True when the first arg is the DESCRIBE_SUBCOMMAND.

protocol_mode

True when core launched us in NDJSON protocol mode (vs. a direct standalone run).

vagus_bin

Path to the vagus binary for callbacks (e.g. indexing standalone). Falls back to vagus on PATH.

vault

Resolved vault root. Prefers $VAGUS_VAULT (set by core); falls back to the documented ~/brain symlink for standalone runs. Returns None only if neither is resolvable.