---
Automates Flywheel MCP setup by detecting your platform, creating `.mcp.json` and `.flywheel.json` config files, validating the connection, and showing vault stats. Triggered when you say "setup flywheel" to configure the Obsidian vault integration.
/plugin marketplace add bencassie/flywheel/plugin install flywheel@flywheelThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Complete Flywheel setup in one command:
User: "setup flywheel"
│
▼
┌─────────────────────────────────────┐
│ Phase 1: Platform Detection │
│ Platform: win32 → cmd /c npx │
│ Platform: linux → npx (incl WSL) │
│ Platform: darwin → npx │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Phase 2: Generate .mcp.json │
│ - Detect vault path │
│ - Merge with existing servers │
│ - User confirms before write │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Phase 2.5: Generate .flywheel.json │
│ - Create client config if missing │
│ - Default: exclude_task_tags: [] │
│ - Explain customization options │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Phase 3: Validate Connection │
│ mcp__flywheel__health_check() │
│ - If fail → restart instructions │
│ - If pass → continue to Phase 4 │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Phase 4: Vault Onboarding │
│ mcp__flywheel__get_vault_stats() │
│ - Note count, link density │
│ - Folder structure │
│ - Suggested next steps │
└─────────────────────────────────────┘
| Gate | Status | Notes |
|---|---|---|
| 1. Read Before Write | ✅ | Reads existing .mcp.json before writing |
| 2. File Exists Check | ✅ | Creates new file if none exists |
| 3. Chain Validation | ✅ | Phases executed sequentially |
| 4. Mutation Confirm | ✅ | User confirms before writing .mcp.json |
| 5. MCP Health | ✅ | Validates MCP after setup |
| 6. Post Validation | ✅ | Shows vault stats to confirm working |
Claude Code uses layered configuration with precedence:
| Layer | File | Scope | Precedence |
|---|---|---|---|
| User | ~/.claude/settings.json | All projects globally | Highest |
| Project | .mcp.json | This project only | Lowest |
Key insight: User settings OVERRIDE project settings.
Check if user already has Flywheel in ~/.claude/settings.json:
~/.claude/settings.json (if exists)mcpServers.flywheel## Flywheel Already Configured (User Level)
Found existing Flywheel config in ~/.claude/settings.json
This config applies to ALL your projects automatically.
No action needed - proceeding to validation...
For Windows (Platform: win32), user-level config is recommended because:
cmd /c npx wrapper applies to all Flywheel projects.mcp.jsonIf suggesting user-level changes, ALWAYS warn about global scope:
⚠️ This will modify ~/.claude/settings.json
Changes apply to ALL projects, not just this one.
Confirm? (y/n)
Check the Platform: field in the environment info at the start of the session.
Platform: value | Runtime | Command | Path style |
|---|---|---|---|
linux | Linux or WSL | npx | /mnt/c/... (WSL) or /home/... |
win32 | Native Windows | cmd /c npx | C:/... |
darwin | macOS | npx | /Users/... |
CRITICAL: NEVER infer platform from filesystem path.
/mnt/c/Users/... means WSL accessing Windows files → use npx (NOT cmd /c)Platform: field is AUTHORITATIVEZero-config approach: If .mcp.json is placed in the vault root (the working directory), no PROJECT_PATH is needed—the server defaults to cwd().
Only ask for vault path if:
For WSL users with vaults on Windows filesystem:
C:\Users\name\vault → /mnt/c/Users/name/vaultZero-config (.mcp.json in vault root) - PREFERRED:
For Linux / macOS / WSL (Platform: linux or Platform: darwin):
{
"mcpServers": {
"flywheel": {
"command": "npx",
"args": ["-y", "@bencassie/flywheel-mcp"]
}
}
}
For Windows (Platform: win32):
{
"mcpServers": {
"flywheel": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@bencassie/flywheel-mcp"]
}
}
}
With explicit vault path (only if vault ≠ working directory):
For Linux / macOS / WSL:
{
"mcpServers": {
"flywheel": {
"command": "npx",
"args": ["-y", "@bencassie/flywheel-mcp"],
"env": {
"PROJECT_PATH": "/path/to/vault"
}
}
}
}
For Windows:
{
"mcpServers": {
"flywheel": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@bencassie/flywheel-mcp"],
"env": {
"PROJECT_PATH": "C:/path/to/vault"
}
}
}
}
.mcp.json exists in the project root.mcp.json fileAfter writing .mcp.json, create the client-side config file if it doesn't exist:
Check if .flywheel.json exists in the vault root:
Default .flywheel.json:
{
"exclude_task_tags": []
}
Show user the file and explain customization:
## Client Configuration
Created `.flywheel.json` in your vault root.
This file lets you customize Flywheel behavior:
- `exclude_task_tags`: Tags to exclude from task queries (e.g., `["habit", "recurring"]`)
Example: To hide habit tasks from task queries, edit `.flywheel.json`:
{
"exclude_task_tags": ["habit"]
}
After writing, check if MCP is available:
If MCP not loaded yet:
## Restart Required
Configuration written to .mcp.json
**Next Steps:**
1. Restart Claude Code to load the new MCP configuration
2. Say "setup flywheel" again to validate and see your vault stats
(Claude Code needs to restart to load new MCP servers)
If MCP is available, call mcp__flywheel__health_check():
On success → continue to Phase 4
On failure:
## Connection Failed
✗ MCP server not responding
Troubleshooting:
1. Check the vault path exists
2. Ensure npx is available in PATH
3. Restart Claude Code and try again
Common issues:
- WSL users: Path should be /mnt/c/... not C:\...
- Windows users: Config uses "cmd /c npx" wrapper
Call mcp__flywheel__get_vault_stats() and mcp__flywheel__get_folder_structure():
## Flywheel Connected!
### Your Vault
- **Notes**: 147 markdown files
- **Wikilinks**: 523 connections
- **Orphans**: 12 unlinked notes
- **Hub notes**: 5 highly connected
### Folder Structure
├── daily-notes/ (89 notes)
├── projects/ (32 notes)
├── people/ (15 notes)
└── reference/ (11 notes)
### Try These Next
- "check vault health" → Deep analysis with recommendations
- "find orphan notes" → Disconnected notes needing links
- "show hub notes" → Your most connected knowledge
- "do a rollup" → Aggregate daily notes into summaries
### Available Skills
Just describe what you want - Flywheel matches your intent:
- "add log entry: fixed the bug" → Appends to daily note
- "find broken links" → Repairs dead wikilinks
- "what links to Project X" → Graph navigation
| Issue | Response |
|---|---|
| Can't determine platform | Ask: "Are you on Windows, macOS, or Linux/WSL?" |
| Vault path doesn't exist | Warn user, suggest checking path |
| Existing .mcp.json has syntax errors | Show error, offer to create fresh config |
| MCP health check fails | Suggest restart, provide troubleshooting steps |
| Vault empty | Explain Flywheel works best with existing notes |
# Flywheel Setup
## Phase 1: Platform Detected
- Runtime: `win32` (Native Windows)
- Command: `cmd /c npx`
## Phase 2: Configuration
Working directory is your vault - using zero-config!
I'll add this to your `.mcp.json`:
{
"mcpServers": {
"flywheel": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@bencassie/flywheel-mcp"]
}
}
}
**Confirm?** (This will be merged with any existing MCP servers)
[User confirms]
## Phase 2.5: Client Config
Created `.flywheel.json` with defaults.
Edit this file to customize task filtering (e.g., exclude #habit tasks).
## Phase 3: Validating...
✓ MCP server connected
✓ Vault accessible (using working directory)
## Phase 4: Your Vault
Notes: 147 | Links: 523 | Orphans: 12
Folder structure:
├── daily-notes/ (89)
├── projects/ (32)
└── ...
### Next Steps
- "check vault health" - Full analysis
- "find orphan notes" - Unlinked content
- "do a rollup" - Aggregate your notes
check-health - Deep vault health analysisfind-orphans - Unlinked notesrun-rollup - Note aggregation workflowApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.