Claudian Manager

Automatically install, update, and troubleshoot the Claudian Obsidian plugin. This skill solves problems directly rather than giving instructions — only guide the user when manual action is truly unavoidable.

Core Principle

Deliver results, not instructions. Fix configuration files, download files, run commands, diagnose issues — all automatically. Only involve the user when you absolutely must (e.g., restarting Obsidian, enabling a plugin in the UI, or providing their vault path if you can't locate it).

Installation (Default Method)

When the user asks to install Claudian, do this automatically:

1. Get vault path: Ask once if you don't know it, or search common locations (~/Documents/Obsidian, ~/Obsidian, etc.)

2. Download latest release files:

   VAULT_PATH="<path>"
   LATEST_TAG=$(gh repo view YishenTu/claudian --json latestRelease -q '.latestRelease.tagName')
   
   mkdir -p "$VAULT_PATH/.obsidian/plugins/claudian"
   
   gh release download "$LATEST_TAG" --repo YishenTu/claudian \
     --pattern "main.js" --pattern "manifest.json" --pattern "styles.css" \
     --dir "$VAULT_PATH/.obsidian/plugins/claudian"

3. Verify files exist:

   ls -lh "$VAULT_PATH/.obsidian/plugins/claudian/"

4. Tell the user: "Claudian is installed. Restart Obsidian and enable it: Settings → Community plugins → toggle Claudian on."

That's it. No lengthy explanations, no options menu. Just install it.

Alternative: From Source (Only When Needed)

Only use this if:

• The user explicitly wants to develop/debug
• GitHub release download fails
• The user needs unreleased features

cd "$VAULT_PATH/.obsidian/plugins"
git clone https://github.com/YishenTu/claudian.git
cd claudian
npm install
npm run build

Updating Claudian

When the user asks to update, do this automatically:

1. Detect current installation type:

   if [ -d "$VAULT_PATH/.obsidian/plugins/claudian/.git" ]; then
     # Source installation
   else
     # Manual/release installation
   fi

2. For release installations (most common) — just replace files:

   CURRENT_VERSION=$(jq -r .version "$VAULT_PATH/.obsidian/plugins/claudian/manifest.json")
   LATEST_TAG=$(gh repo view YishenTu/claudian --json latestRelease -q '.latestRelease.tagName')
   
   if [ "$CURRENT_VERSION" = "$LATEST_TAG" ]; then
     echo "Already on latest version $CURRENT_VERSION"
   else
     gh release download "$LATEST_TAG" --repo YishenTu/claudian \
       --pattern "main.js" --pattern "manifest.json" --pattern "styles.css" \
       --dir /tmp/claudian-update
     
     cp /tmp/claudian-update/* "$VAULT_PATH/.obsidian/plugins/claudian/"
     echo "Updated from $CURRENT_VERSION to $LATEST_TAG. Restart Obsidian."
   fi

3. For source installations:

   cd "$VAULT_PATH/.obsidian/plugins/claudian"
   git pull
   npm install
   npm run build
   echo "Updated to latest commit. Restart Obsidian."

4. For community plugin installations — detect by checking if files have no .git and match release checksums, then guide:

- "Your Claudian was installed via Community Plugins. Go to Settings → Community plugins → Check for updates, then click Update next to Claudian."

Don't ask which method to use. Detect and execute.

Troubleshooting — Automatic Diagnosis and Fixes

Issue 1: "spawn claude ENOENT" / "Claude CLI not found"

Auto-fix sequence:

1. Check if Claude CLI exists:

   CLAUDE_PATH=$(which claude 2>/dev/null || where.exe claude 2>/dev/null)
   if [ -z "$CLAUDE_PATH" ]; then
     echo "Claude CLI not installed"
   fi

2. If found, configure it in Claudian:

   # Read current settings
   SETTINGS_FILE="$VAULT_PATH/.claudian/settings.json"
   
   # Update or create settings with correct CLI path
   jq --arg path "$CLAUDE_PATH" '.claudePath = $path' "$SETTINGS_FILE" > /tmp/settings.tmp
   mv /tmp/settings.tmp "$SETTINGS_FILE"
   
   echo "Configured Claude CLI path: $CLAUDE_PATH. Restart Obsidian."

3. If not found, check common locations (Windows native, npm global, volta, nvm):

   # Windows native
   [ -f "/c/Users/$USER/AppData/Local/Claude/claude.exe" ] && CLAUDE_PATH="..."
   
   # npm global
   NPM_ROOT=$(npm root -g 2>/dev/null)
   [ -f "$NPM_ROOT/@anthropic-ai/claude-code/cli-wrapper.cjs" ] && CLAUDE_PATH="..."
   
   # volta
   [ -f "$HOME/.volta/bin/claude" ] && CLAUDE_PATH="..."

4. If still not found, install it:

   # Try npm first (fastest)
   npm install -g @anthropic-ai/claude-code
   
   # Then configure
   CLAUDE_PATH=$(which claude)
   # ... update settings as above

5. Only if all fails, guide the user: "Claude CLI not found. Download from https://code.claude.com/ and run ! which claude to get the path, then tell me."

Issue 2: npm CLI and Node.js in Different Directories

Auto-fix:

1. Detect the issue:

   CLAUDE_DIR=$(dirname $(which claude 2>/dev/null))
   NODE_DIR=$(dirname $(which node 2>/dev/null))
   
   if [ "$CLAUDE_DIR" != "$NODE_DIR" ]; then
     echo "Path mismatch detected"
   fi

2. Fix via environment variables:

   SETTINGS_FILE="$VAULT_PATH/.claudian/settings.json"
   
   # Add Node.js path to Claudian's environment
   jq --arg nodepath "$NODE_DIR" '.environment.PATH = ($nodepath + ":$PATH")' "$SETTINGS_FILE" > /tmp/settings.tmp
   mv /tmp/settings.tmp "$SETTINGS_FILE"
   
   echo "Added Node.js path to Claudian environment. Restart Obsidian."

3. Alternative: Install native Claude CLI (more reliable):

   echo "Recommended: Install native Claude CLI from https://code.claude.com/ to avoid this issue."
   # But don't wait for user — proceed with environment fix above

Issue 3: Plugin Won't Enable or Crashes

Auto-diagnosis:

1. Check file integrity:

   PLUGIN_DIR="$VAULT_PATH/.obsidian/plugins/claudian"
   
   if [ ! -f "$PLUGIN_DIR/main.js" ] || [ ! -f "$PLUGIN_DIR/manifest.json" ]; then
     echo "Missing plugin files. Reinstalling..."
     # Run installation sequence above
   fi

2. Check for JavaScript errors in logs (if accessible):

   # Check Claudian's log directory
   ls -la "$VAULT_PATH/.claudian/" 2>/dev/null

3. Search recent GitHub issues:

   gh issue list --repo YishenTu/claudian --limit 10 --state open --search "crash OR enable OR \"won't start\""

4. If a known issue found with a fix, apply it. If not, reinstall:

   rm -rf "$PLUGIN_DIR"
   # Run installation sequence

Issue 4: After Update, Things Broke

Auto-response sequence:

1. Check what changed recently:

   # Get recent issues mentioning breaking changes
   gh issue list --repo YishenTu/claudian --limit 20 --state all --search "breaking OR \"not working\" OR \"stopped working\"" --json title,url,createdAt --jq '.[] | select(.createdAt > (now - 7*24*3600))'
   
   # Check recent releases
   gh release list --repo YishenTu/claudian --limit 3

2. Check provider CLI versions:

   claude --version 2>/dev/null
   codex --version 2>/dev/null

3. If a known issue found, apply the fix. Common patterns:

- Provider CLI changed authentication → reconfigure auth

- Config format changed → migrate settings file

- API breaking change → rollback to previous working version

4. Rollback if needed:

   # Find previous working version from user
   PREV_VERSION="<previous-tag>"
   
   gh release download "$PREV_VERSION" --repo YishenTu/claudian \
     --pattern "main.js" --pattern "manifest.json" --pattern "styles.css" \
     --dir "$VAULT_PATH/.obsidian/plugins/claudian"
   
   echo "Rolled back to $PREV_VERSION. Restart Obsidian."

Issue 5: Provider-Specific Issues (Codex, Opencode, Pi)

Auto-check sequence:

1. Verify provider CLI exists:

   which codex 2>/dev/null || echo "Codex not found"
   which opencode 2>/dev/null || echo "Opencode not found"
   which pi 2>/dev/null || echo "Pi not found"

2. Check provider configuration in Claudian settings:

   jq '.providers' "$VAULT_PATH/.claudian/settings.json"

3. Search provider-specific issues:

   gh issue list --repo YishenTu/claudian --search "codex OR opencode OR pi" --state open --limit 10

4. Fix common provider issues:

- Missing CLI → Install it: npm install -g @<provider>

- Wrong path → Update settings with correct path

- Auth issues → Run provider's auth command: codex auth login, etc.

Research Protocol

Claudian is a downstream integration of rapidly-evolving tools. Before applying generic fixes:

1. Search GitHub issues FIRST:

   gh issue list --repo YishenTu/claudian --search "<error message keywords>" --state open

2. Check recent releases for breaking changes:

   gh release list --repo YishenTu/claudian --limit 5
   gh release view --repo YishenTu/claudian  # Read release notes

3. Check upstream CLI changes (Claude Code, Codex):

   gh release list --repo anthropics/claude-code --limit 3

4. Search across repos if no match in Claudian issues:

   gh search issues "<error message>" --limit 10

Do this research before attempting fixes, not after they fail.

When Manual Action is Unavoidable

Only involve the user when you truly cannot proceed:

1. Restarting Obsidian — you can't do this remotely

2. Enabling the plugin in Obsidian UI — Settings → Community plugins → toggle on

3. Providing vault path — if you can't find it and common locations don't exist

4. Interactive authentication — some CLIs require browser auth flows

5. Escalating to GitHub — if no known fix exists, collect diagnostics and guide user to open an issue

For everything else — downloading files, editing configs, installing dependencies, running commands — do it automatically.

Quick Reference

| Item | Path |

|------|------|

| Plugin files | <vault>/.obsidian/plugins/claudian/ |

| Claudian settings | <vault>/.claudian/settings.json |

| Claude provider data | <vault>/.claude/ or ~/.claude/projects/ |

Platform Notes

Windows

• Use claude.exe (native) or cli-wrapper.cjs (npm), never .cmd/.ps1
• Path command: where.exe claude

macOS/Linux

• GUI apps don't inherit terminal PATH
• Path command: which claude
• Common locations: ~/.volta/bin/, ~/.nvm/versions/node/.../bin/

Output Style

After fixing an issue, report concisely:

✅ Good: "Fixed. Claude CLI configured at /usr/local/bin/claude. Restart Obsidian."

❌ Bad: "I've located the Claude CLI at /usr/local/bin/claude and updated your Claudian settings file at <vault>/.claudian/settings.json by modifying the claudePath field. You should now restart Obsidian to apply these changes. Here's what I did: [3 paragraphs]..."

When you need user action, be specific and brief:

✅ Good: "Restart Obsidian and enable Claudian in Settings → Community plugins."

❌ Bad: "Now you need to restart Obsidian. To do this, close the application completely and reopen it. Then navigate to Settings by clicking the gear icon..."