Start in Obsidian

This guide walks through installing the Knowlery plugin, initializing a vault, and understanding what changes after setup. (Starting with an agent instead? See Getting Started.)

Requirements

Knowlery targets Obsidian desktop and requires community plugins to be enabled.

You also need Claude Code or OpenCode if you want to run agent workflows against the vault. Node.js and npm are required for optional tool preparation and the external skill browser.

Desktop behavior

Knowlery uses local command-line tools and Electron desktop APIs for agent-oriented features. The current plugin manifest marks it as desktop-only.

Install from Community plugins

Install Knowlery from Obsidian's community plugin directory for normal use.

1. Open Settings -> Community plugins in Obsidian.
2. Select Browse.
3. Search for Knowlery.
4. Install and enable the plugin.

Install beta builds with BRAT

BRAT is the Beta Reviewers Auto-update Tool for Obsidian. Use it only when you want to test preview builds before they are published to the community plugin directory.

1. Install BRAT in Obsidian.
2. Open BRAT settings.
3. Add this beta plugin repository: https://github.com/JayJiangCT/knowlery.
4. Enable Knowlery from Settings -> Community plugins.

Manual Install

1. Download main.js, manifest.json, and styles.css from the latest GitHub release.
2. Create .obsidian/plugins/knowlery/ inside your vault if it does not already exist.
3. Place the three files in that folder.
4. Reload Obsidian.
5. Enable Knowlery from Settings -> Community plugins.

First Run

After enabling the plugin, open Knowlery from the ribbon icon or command palette.

If the vault is not initialized, Knowlery shows setup entry points in the dashboard and settings tab.

The setup wizard asks you to choose a platform:

Platform	Generated config
Claude Code	Detects the claude CLI; labels say Claude Code
OpenCode	Detects the opencode CLI; labels say OpenCode

The agent configuration itself is the same for both: a vault-root AGENTS.md for Codex, OpenCode, and Cursor, and a .claude/CLAUDE.md for Claude Code. Both carry Knowlery's operating rules and are built from the same two sources — your KNOWLEDGE.md and the rules in .agents/rules/: AGENTS.md copies them in (those harnesses have no import syntax), CLAUDE.md @-imports them. KNOWLEDGE.md stays the one file you edit.

If you are upgrading from an older release, v0.5.0 adds knowledge bundle sharing and installing: a Bundles section on the dashboard, the Share knowledge bundle and Install knowledge bundle commands, the Library/ folder for installed bundles, and a bundle-aware /ask skill. v0.4.0 kept the dashboard focused on one action-first home and moved diagnostics, rules, schema shortcuts, and the Skills library into the Knowlery settings tab. Bundled skills still auto-sync on version changes, and SCHEMA.md is migrated in place when missing anchor sections are found. Custom and forked skills are preserved.

What Setup Creates

Knowlery creates the knowledge workspace and agent configuration in your vault:

Path	Purpose
KNOWLEDGE.md	Your description of the knowledge base (what it covers, how it is laid out) — yours to edit
SCHEMA.md	Knowledge taxonomy and page conventions
INDEX.base	Obsidian Bases index for compiled knowledge pages
entities/	Named things such as people, tools, organizations, and projects
concepts/	Ideas, frameworks, theories, and mental models
comparisons/	Side-by-side analyses
queries/	Saved questions and research threads
.knowlery/manifest.json	Knowlery setup metadata
.agents/skills/	Canonical installed skill files
.agents/rules/	Rules, for every platform (inlined into AGENTS.md, imported by .claude/CLAUDE.md)
.claude/skills/	Mirrored built-in skill files for Claude Code
AGENTS.md	Entry file for Codex, OpenCode, and others: KNOWLEDGE.md, Knowlery's operating rules, and your rules copied into a managed block (regenerated on sync)
.claude/CLAUDE.md	Entry file for Claude Code: @../KNOWLEDGE.md, Knowlery's operating rules, and one @ import per rule (managed block); Claude-specific notes outside the block are kept
skills-lock.json	Skill source, version, and disabled-state metadata

Normal use can also create private activity receipts, weekly summary reports, and daily review request/result files under .knowlery/.

Optional Tool Preparation

The setup wizard can detect Claude Code, OpenCode, Node.js, Claudian, and skills tooling.

Missing optional tools are shown as selectable install or preparation steps. Already-installed tools are shown as read-only status rows. These actions are opt-in and run on your computer with your user permissions.

Open the Dashboard

After setup, open the Knowlery dashboard. It is a single scrolling review surface:

Section	Use it for
Today's move	Start from the current activity context and choose the next small move
Suggested moves	Use reusable review prompts such as Process new material or Challenge an idea
Knowledge health	See stale pages and never-compiled notes; copy a re-cook prompt
This note	Review the active Markdown note and prepare a focused prompt
Recent activity	Scan private activity receipts and open the full activity list
This week	Generate a weekly summary, open the last report, or send it for review
Bundles	Share a reviewed knowledge bundle or install one shared with you

Open Settings -> Knowlery for diagnostics, rules and schema shortcuts, the Skills library, platform switching, activity logging, and maintenance actions. A Language setting controls the dashboard and settings display language — Follow Obsidian (default), English, or 中文.

Recommended First Session

1. Initialize a clean test vault first.
2. Read the generated KNOWLEDGE.md and SCHEMA.md.
3. Open the dashboard and read Today's move, Suggested moves, and This note.
4. Add one or two real notes to the vault.
5. Generate a weekly summary, then open Settings -> Knowlery and run diagnostics.