Onyxian

Onyxian scaffolds and operates a tailored Obsidian vault, composed from opt-in modules. Pick the domains you care about and Onyxian wires up the folders, typed frontmatter, Bases views, and templates for each. The same framework serves a researcher, a PhD student, a musician, and a product manager, with different module sets and different folder names.

Three things hold true everywhere:

• It works without any AI. Templates are plain copies, views are plain files. Optional Claude Code skills and agents amplify the vault, but nothing depends on them.
• It never clobbers your files. Every file Onyxian writes is tracked. A file you edited is yours: updates that would overwrite it arrive as a *.new sibling instead, never a silent overwrite. There is no flag that overrides this.
• It's tailored to you. Folder names, cadences, and structures are per-vault variables, not baked-in opinions.

Install

In Claude Code (nothing to set up)

/plugin marketplace add odysseia06/onyxian
/plugin install onyxian@onyxian
/vault-bootstrap

The plugin ships the interview wizard. On first run it installs the CLI for you and walks you from an empty folder, or an existing vault, to a working setup.

As a command-line tool

uv tool install onyxian      # or:  pipx install onyxian

Then create a vault:

onyxian init my-vault                                  # interactive interview
onyxian init my-vault --answers researcher-developer   # or start from a profile

Open the folder in Obsidian and you're done.

From source

git clone https://github.com/odysseia06/onyxian && cd onyxian
python -m venv .venv
# Windows: .venv\Scripts\activate     macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
pytest

Using it

Adopting an existing vault is the safe path. onyxian adopt <vault> --dry-run is read-only: it maps your existing folders onto module variables, proposes a purely additive plan, and parks anything ambiguous on a checklist instead of touching it. Nothing is moved, renamed, deleted, or overwritten. There is no --yes on adopt — in a terminal you review the plan and type adopt to confirm; non-interactively (scripts, agents), the review prints an acceptance token derived from the exact plan shown, and you apply with --accept <token>. (Commit your vault to git first; Onyxian will remind you.)

How it works

The engine is a small CLI built on a declarative reconciliation loop:

• .vault/config.yaml declares intent — which modules, with which variables. Yours to edit.
• .vault/lock.json records state — every file Onyxian has written, with its hash, write generation, and machine id. Machine-maintained.
• onyxian plan computes the difference; onyxian apply reconciles it.

Every file Onyxian writes is one of two kinds. Managed files (templates, views, skills) update themselves while you leave them alone, and turn into *.new deliveries the moment you customize them. Seeded files (your home note, a strategy note) are written once and yours from then on. Everything else in the vault is invisible to Onyxian, and it will never write there.

Modules

Enable any combination with onyxian add, or start from a profile (a named module set): minimal, creator, developer, fitness-focused, gamedev, musician, phd-student, product-manager, student, writer, or researcher-developer.

Modules are data, not code, so the roster isn't closed: scaffold your own with onyxian module new <id>, publish it as a git repository, and anyone can install it with onyxian add <url> (they'll see a trust warning first — a module can't execute anything, but a malicious template is still a social-engineering surface).

The agent layer (optional)

When you use Claude Code, each enabled module installs scoped skills and a per-domain agent into .claude/ — daily-planner, research-librarian, study-coach, fitness-coach, and so on, each with a documented read/write scope it operates within. A generated CLAUDE.md orients Claude the moment you open the vault, pointing at the agents and the operating rules so a plain request reaches the right one; other runtimes get a generated AGENTS.md.

These agents don't only suggest — they operate the live vault through Obsidian's official command-line interface: scaffold and triage the day, capture a task from a sentence ("add a task to fix this by Friday"), log a coding session or record a decision ("we decided X because Y"), file a typed paper summary, and so on — you reach the right agent just by saying what you want. Every write follows one contract (the vault-operations skill): additive by default, inside the agent's scope, escalating rather than guessing. These scopes are conventions the agents are instructed to honor, not a filesystem sandbox — the user guide says exactly what kind of guarantee that is. Opt-in vault checkpoints provide the recovery net: inspect with onyxian checkpoint diff, then restore one path or the whole vault with onyxian checkpoint restore <id> [path...]. Delete .claude/ entirely and the vault still works as plain files; the agent layer is power, never a dependency.

Documentation

• docs/user-guide.md — the user guide: install, quickstart, adopting an existing vault, everyday operations, *.new files, the agent layer, a full module reference, and troubleshooting. Start here.
• KICKSTART.md — the design charter: vision, architecture, the module system, and the write/lock/update contract. Internal, but the deep read on why the engine works the way it does.
• CONTRIBUTING.md — how to work on Onyxian and author modules.
• RELEASING.md — how releases are cut and published.

License

MIT.