Frequently Asked Questions¶

Common questions and troubleshooting for Obsidian AI Project Management

Table of Contents¶

Installation and Setup
MCP Server Issues
Plugin Issues
Entity Management
Canvas and Visualization
Relationships and Dependencies
Performance and Limits
Workflow Questions

Installation and Setup¶

Q: Do I need both the MCP server and the plugin?¶

A: No, but they work best together.

MCP Server only: You can manage entities via AI, but won't have visual canvas organization
Plugin only: You can visualize entities on canvas, but won't have AI-assisted management
Both together: Full AI-native project management with visual review (recommended)

Q: Which AI assistants are supported?¶

A: Currently supported: - Claude Desktop - Full support - Cursor IDE - Full support

Coming soon: - Cline - Other MCP-compatible clients

Q: Can I use this with an existing Obsidian vault?¶

A: Yes! The system creates its own folders (milestones/, stories/, etc.) and won't interfere with your existing notes.

Q: What if I already have a `milestones/` folder?¶

A: The system will use the existing folder. Make sure existing files don't conflict with the entity ID format (M-xxx, S-xxx, etc.).

MCP Server Issues¶

Q: "MCP tools not available" in Claude/Cursor¶

Solutions:

Restart the AI assistant - Quit completely and reopen
Check config file syntax - Ensure valid JSON (no trailing commas)
Verify Node.js - Run node --version (should be 18+)
Check VAULT_PATH - Must be absolute path with forward slashes
Check logs - Look for errors in AI assistant's developer console

Example correct config:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-accomplishments-mcp"],
      "env": {
        "VAULT_PATH": "/Users/john/Documents/MyVault",
        "DEFAULT_CANVAS": "main.canvas"
      }
    }
  }
}

Q: "No entities found" when asking AI about project¶

Solutions:

Check VAULT_PATH - Verify it points to correct vault
Check entity files exist - Look in milestones/, stories/, tasks/ folders
Check file format - Entities must have valid YAML frontmatter with type field
Restart MCP server - Restart AI assistant to reload index

Q: AI creates entities but they don't appear in vault¶

Solutions:

Check VAULT_PATH - Ensure it's the correct absolute path
Check permissions - Ensure MCP server can write to vault directory
Check for errors - Ask AI "What was the last error?"
Refresh Obsidian - Close and reopen vault

Plugin Issues¶

Q: Plugin doesn't appear in Community Plugins¶

A: The plugin is currently under review. Install from source:

git clone https://github.com/ostanlabs/obsidian_plugin.git
cd obsidian_plugin
npm install && npm run build
cp main.js manifest.json styles.css /path/to/vault/.obsidian/plugins/canvas-project-manager/

Then enable in Obsidian Settings → Community Plugins.

Q: "No active canvas found" error¶

Solutions:

Create a canvas file - Create main.canvas in your vault
Open the canvas - Make sure canvas file is open and focused
Check file extension - Must be .canvas not .md

Q: Canvas is empty after "Populate from vault"¶

Solutions:

Check entity files exist - Look in milestones/, stories/, tasks/ folders
Check frontmatter - Entities must have type field
Check for archived entities - Archived entities won't appear
Check console - Open Developer Console (Ctrl/Cmd+Shift+I) for errors
Try "Reposition nodes" - Run after populating

Q: Nodes overlap or are positioned incorrectly¶

Solutions:

Run "Reposition nodes" - This applies the hierarchical layout algorithm
Check parent relationships - Ensure parent fields are set correctly
Check workstreams - Entities are organized by workstream lanes
Manual adjustment - You can drag nodes manually if needed

Entity Management¶

Q: What's the difference between a Story and a Task?¶

A: - Story (S-xxx): User story or feature description. Contains multiple tasks. Parent is a Milestone. - Task (T-xxx): Actionable work item. Parent is a Story.

Think: Milestone → Story → Task (3-tier hierarchy)

Q: Can I create entities manually in Obsidian?¶

A: Yes, but it's easier to use AI:

Manual creation: 1. Create file in appropriate folder (e.g., milestones/M-001.md) 2. Add YAML frontmatter with required fields 3. Run "Populate from vault" to add to canvas

AI creation (recommended):

"Create a milestone called 'Q1 Launch' with target date March 31"

Q: How do I delete an entity?¶

A: - Via AI: "Delete M-001" or "Archive M-001" (recommended) - Manually: Delete the file from vault, then refresh canvas

Note: Archiving is preferred over deletion (moves to archive/ folder).

Q: Can I rename an entity ID?¶

A: Not recommended. Entity IDs are used in relationships. If you must:

Update the ID in the file's frontmatter
Rename the file to match
Update all references in other entities
Run "Reconcile relationships" command

Better: Create a new entity and archive the old one.

Canvas and Visualization¶

Q: How do I change the canvas layout?¶

A: The plugin uses an automatic hierarchical layout algorithm. To customize:

Run "Reposition nodes" - Applies automatic layout
Manual adjustment - Drag nodes to desired positions
Workstream organization - Entities are grouped by workstream

Q: Can I have multiple canvases?¶

A: Yes! You can create multiple canvas files:

main.canvas - Main project view
engineering.canvas - Engineering workstream only
features.canvas - Feature planning

Use "Populate from vault" on each canvas.

Q: How do I hide certain entity types?¶

A: Use the visibility toggle buttons in the plugin toolbar:

M - Toggle milestones
S - Toggle stories
T - Toggle tasks
De - Toggle decisions
Do - Toggle documents

Q: Can I export the canvas as an image?¶

A: Use Obsidian's built-in canvas export:

Open canvas
Right-click → Export as image
Choose PNG or SVG format

Relationships and Dependencies¶

Q: What's the difference between `parent` and `depends_on`?¶

A: - parent: Hierarchical relationship (Story belongs to Milestone) - depends_on: Dependency relationship (Task A must complete before Task B)

Example:

# T-002 is a child of S-001 and depends on T-001
id: T-002
parent: S-001        # Hierarchy: belongs to S-001
depends_on: [T-001]  # Dependency: needs T-001 to complete first

Q: How do bidirectional relationships work?¶

A: The system automatically maintains both sides:

You set:  S-001.parent = M-001
System:   Automatically adds S-001 to M-001.children

You set:  T-001.depends_on = [T-002]
System:   Automatically adds T-001 to T-002.blocks

Q: "Circular dependency detected" error¶

A: You're trying to create a dependency cycle:

Example cycle:
  A depends on B
  B depends on C
  C depends on A  ← This creates a cycle!

Solution: Review your dependencies and break the cycle.

Q: How do I fix broken relationships?¶

A: Use the reconciliation command:

Via AI:

"Reconcile all relationships"

Via Plugin: 1. Open command palette (Ctrl/Cmd+P) 2. Run "Reconcile all relationships"

This fixes any inconsistent bidirectional relationships.

Performance and Limits¶

Q: How many entities can the system handle?¶

A: Tested with: - ✅ 100 milestones - ✅ 500 stories - ✅ 2000 tasks - ✅ 200 decisions/documents/features

Performance may degrade with very large canvases (>500 nodes).

Q: The canvas is slow with many nodes¶

Solutions:

Use multiple canvases - Split by workstream or milestone
Archive completed work - Moves entities off canvas
Filter by entity type - Hide types you don't need to see
Use AI for navigation - Instead of visual browsing

Q: File sync conflicts with Obsidian Sync¶

A: If using Obsidian Sync:

Don't run MCP and edit manually simultaneously - Choose one at a time
Wait for sync - Let Obsidian Sync complete before AI operations
Use version history - Obsidian Sync keeps versions if conflicts occur

Workflow Questions¶

Q: Should I use AI or the plugin to create entities?¶

A: Use AI for creation, plugin for review:

✅ AI: Fast bulk creation, maintains relationships automatically
✅ Plugin: Visual review, navigation, manual adjustments

Q: How do I collaborate with a team?¶

A: 1. Share vault - Use Obsidian Sync, Git, or shared folder 2. Each person configures MCP - Point to same vault 3. Coordinate changes - Avoid simultaneous edits to same entities 4. Use decisions - Document team decisions in DEC-xxx entities

Q: Can I integrate with other tools (Jira, GitHub, etc.)?¶

A: Not directly, but you can:

Export data - Entities are markdown files, easy to parse
Use AI - Ask AI to generate reports or summaries
Custom scripts - Write scripts to sync with other tools

Q: How do I backup my project data?¶

A: Your data is just markdown files in your vault:

Obsidian Sync - Automatic cloud backup
Git - Version control for vault
File backup - Regular backups of vault folder
Export - Copy entity folders to backup location

Still Need Help?¶

GitHub Issues: Report bugs
GitHub Discussions: Ask questions
Documentation: Read the guides

Last Updated: January 2026

Frequently Asked Questions¶

Table of Contents¶

Installation and Setup¶

Q: Do I need both the MCP server and the plugin?¶

Q: Which AI assistants are supported?¶

Q: Can I use this with an existing Obsidian vault?¶

Q: What if I already have a milestones/ folder?¶

MCP Server Issues¶

Q: "MCP tools not available" in Claude/Cursor¶

Q: "No entities found" when asking AI about project¶

Q: AI creates entities but they don't appear in vault¶

Plugin Issues¶

Q: Plugin doesn't appear in Community Plugins¶

Q: "No active canvas found" error¶

Q: Canvas is empty after "Populate from vault"¶

Q: Nodes overlap or are positioned incorrectly¶

Entity Management¶

Q: What's the difference between a Story and a Task?¶

Q: Can I create entities manually in Obsidian?¶

Q: How do I delete an entity?¶

Q: Can I rename an entity ID?¶

Canvas and Visualization¶

Q: How do I change the canvas layout?¶

Q: Can I have multiple canvases?¶

Q: How do I hide certain entity types?¶

Q: Can I export the canvas as an image?¶

Relationships and Dependencies¶

Q: What's the difference between parent and depends_on?¶

Q: How do bidirectional relationships work?¶

Q: "Circular dependency detected" error¶

Q: How do I fix broken relationships?¶

Performance and Limits¶

Q: How many entities can the system handle?¶

Q: The canvas is slow with many nodes¶

Q: File sync conflicts with Obsidian Sync¶

Workflow Questions¶

Q: Should I use AI or the plugin to create entities?¶

Q: How do I collaborate with a team?¶

Q: Can I integrate with other tools (Jira, GitHub, etc.)?¶

Q: How do I backup my project data?¶

Still Need Help?¶

Q: What if I already have a `milestones/` folder?¶

Q: What's the difference between `parent` and `depends_on`?¶