npx mcp-obsidian-vault

graph TB
    subgraph Clients["AI Clients"]
        CC[Claude Code]
        OC[opencode]
        CX[Codex CLI]
    end

    subgraph MCP["mcp-obsidian-vault"]
        direction TB
        NT["Note Tools<br/><small>read, create, update, delete<br/>search, tags, wikilinks, daily</small>"]
        TT["Task Tools<br/><small>create, claim, update, complete<br/>projects, dashboard</small>"]
        CT["Context Tools<br/><small>get_context, log_decision<br/>log_discovery</small>"]
        GS["Git Sync<br/><small>commit, pull, push<br/>auto-sync on write</small>"]
    end

    subgraph Vault["Obsidian Vault (filesystem)"]
        direction TB
        Notes["Notes/"]
        Tasks["Tasks/<br/><small>DASHBOARD.md</small>"]
        Dec["Decisions/"]
        Disc["Discoveries/"]
    end

    subgraph Remote["Remote"]
        GH["GitHub / GitLab"]
        Phone["Phone<br/><small>Obsidian Git plugin</small>"]
    end

    CC & OC & CX -->|MCP Protocol| MCP
    NT --> Notes
    TT --> Tasks
    CT --> Dec & Disc
    GS -->|auto-push| GH
    GH -->|pull| Phone

    style MCP fill:#1a1a2e,stroke:#e94560,color:#fff
    style Vault fill:#16213e,stroke:#0f3460,color:#fff
    style Clients fill:#0f3460,stroke:#533483,color:#fff
    style Remote fill:#1a1a2e,stroke:#533483,color:#fff

claude mcp add obsidian -- npx -y mcp-obsidian-vault

claude mcp add obsidian \
  -e OBSIDIAN_VAULT_PATH=/path/to/your/vault \
  -e GIT_AUTO_SYNC=true \
  -- npx -y mcp-obsidian-vault

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-obsidian-vault"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

{
  "mcp": {
    "obsidian": {
      "type": "local",
      "command": [
        "sh", "-c",
        "OBSIDIAN_VAULT_PATH=/path/to/your/vault GIT_AUTO_SYNC=true npx -y mcp-obsidian-vault"
      ],
      "enabled": true
    }
  }
}

[mcp_servers.obsidian]
command = "npx"
args = ["-y", "mcp-obsidian-vault"]

[mcp_servers.obsidian.env]
OBSIDIAN_VAULT_PATH = "/path/to/your/vault"
GIT_AUTO_SYNC = "true"

git clone https://github.com/t-rhex/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install && npm run build
OBSIDIAN_VAULT_PATH=/path/to/vault node build/index.js

# Force npx to fetch the latest
npx -y mcp-obsidian-vault@latest

# Or clear the npx cache entirely
npx clear-npx-cache

git pull origin main
npm install && npm run build

npx -y mcp-obsidian-vault --version
# Or ask your AI agent: "What version of mcp-obsidian-vault are you running?"

claude mcp remove obsidian

# Remove the cached package
npx clear-npx-cache

rm -rf obsidian-mcp-server

"Read my Projects/roadmap note"

"Search my vault for anything about authentication"

"Create a task to refactor the auth module, high priority"

"What's the current context? Call get_context."

"I need to build a REST API for user management. Set up a project with tasks for:
  1. Design the database schema (research)
  2. Set up Express with TypeScript (code)
  3. Implement CRUD endpoints (code, depends on 1 and 2)
  4. Add JWT authentication (code, depends on 3)
  5. Write integration tests (code, depends on 4)
  6. Write API documentation (writing)"

Tasks/
├── DASHBOARD.md                                          # auto-generated summary
└── user-management-api/                                  # project subfolder
    ├── proj-2026-03-09-a1b2c3-user-management-api.md     # project note
    ├── task-2026-03-09-d4e5f6-design-database-schema.md  # pending (no deps)
    ├── task-2026-03-09-g7h8i9-set-up-express.md          # pending (no deps)
    ├── task-2026-03-09-j0k1l2-implement-crud.md          # blocked (waits on 1, 2)
    ├── task-2026-03-09-m3n4o5-add-jwt-auth.md            # blocked (waits on 3)
    ├── task-2026-03-09-p6q7r8-write-tests.md             # blocked (waits on 4)
    └── task-2026-03-09-s9t0u1-write-api-docs.md          # pending (no deps)

"Claim the database schema task and start working on it."

"What's the project status?"
→ 1/6 complete (17%), 2 in progress, 3 blocked

"Log a decision: we chose Zod over Joi for validation because of TypeScript inference."

"Log a discovery: the Stripe webhook endpoint requires idempotency keys or charges double."

"Call get_context to see what's in progress."

"Add these tasks to the User Management API project:
  - Add rate limiting middleware (code)
  - Add password reset flow (code, depends on JWT auth)
  - Security audit (research, depends on rate limiting and password reset)"

Session 1: "Create a task to fix the memory leak in the worker pool"
           → agent claims it, investigates, logs progress, runs out of context

Session 2: "Call get_context"
           → sees the in-progress task, picks up from the agent log
           → completes the fix, marks task done

Session 3: "Call get_context"
           → sees the completed task, continues to next priority

"Append to today's daily note: deployed v2.1 to staging, waiting on QA"

"What did I log yesterday?"

path: "Projects/my-note.md"     # .md added automatically if missing
includeRaw: false                # include unparsed content

path: "Projects/new-idea"
content: "# My Idea\n\nSome content here."
frontmatter: { "tags": ["idea", "project"], "status": "draft" }
overwrite: false                 # fails if note exists (default)

path: "Projects/my-note"
content: "## New Section\n\nAdded content."
mode: "append"                   # "replace" | "append" | "prepend"
frontmatter: { "status": "in-progress" }

path: "Projects/old-note"
permanent: false                 # true for hard delete

query: "meeting notes"
regex: false
caseSensitive: false
folder: "Projects"               # limit to subfolder
maxResults: 20

path: "Projects"                 # defaults to vault root
recursive: true
maxDepth: 5
notesOnly: false                 # true to filter to .md files only

path: "Projects/my-note"
action: "add"                    # "list" | "add" | "remove"
tags: ["important", "review"]

action: "append"                 # "get" | "create" | "append"
date: "today"                    # "today" | "yesterday" | "tomorrow" | "2025-03-08"
content: "- Met with team about roadmap"

action: "backlinks"              # "resolve" | "backlinks" | "outlinks" | "unresolved"
path: "Projects/my-note"

action: "sync"                   # full pull + commit + push
message: "update notes"          # optional commit message

title: "Implement auth module"
description: "Build JWT-based authentication for the API."
priority: "high"                 # "critical" | "high" | "medium" | "low"
type: "code"                     # "code" | "research" | "writing" | "maintenance" | "other"
depends_on: ["task-abc-123"]     # task IDs that must complete first
scope: ["src/auth.ts"]           # advisory: files this task modifies
acceptance_criteria: ["Tests pass", "Docs written"]
timeout_minutes: 120

status: "pending"                # or "all"
priority: "high"                 # or "all"
type: "code"                     # or "all"
tags: ["auth"]                   # filter by tags
assignee: "claude-code-1"
unassigned_only: true
project: "proj-..."              # filter by project

task_id: "task-2026-03-09-abc123"
assignee: "claude-code-1"
worktree_branch: "worktree-auth-api"      # optional — for parallel multi-agent work
worktree_path: "/repo/.claude/worktrees/auth-api"  # optional

task_id: "task-2026-03-09-abc123"
status: "in_progress"
log_entry: "Found root cause — null check missing in auth middleware."

task_id: "task-2026-03-09-abc123"
summary: "Auth module implemented with JWT support."
deliverables: ["src/auth.ts", "https://github.com/org/repo/pull/42"]
status: "completed"              # "completed" | "failed" | "cancelled"

title: "Auth Rewrite"
description: "Rewrite authentication to use JWT tokens."
tasks: [
  { title: "Design API schema", type: "research" },
  { title: "Implement JWT", type: "code", depends_on_indices: [0] },
  { title: "Write tests", type: "code", depends_on_indices: [1] },
  { title: "Update docs", type: "writing" }
]

project_id: "proj-2026-03-09-abc123"
tasks: [
  { title: "Add rate limiting", type: "code" },
  { title: "Security audit", depends_on_existing: ["task-..."] }
]

project_id: "proj-2026-03-09-abc123"

project_id: "proj-..."           # optional: focus on one project
hours: 48                         # lookback window (default: 48)
include_completed: true

title: "Use JWT over session tokens"
context: "Need stateless auth for microservices."
decision: "JWT with RS256, 15min access tokens, refresh rotation."
alternatives: ["Session tokens with Redis", "API keys"]
consequences: ["Stateless (good)", "Revocation needs deny-list (tradeoff)"]

title: "gray-matter crashes on undefined values"
discovery: "js-yaml throws when serializing undefined. Strip before serialize."
impact: "high"
recommendation: "Filter with Object.entries().filter() first."
category: "bug"

task_id: "task-2026-03-09-abc123"
action: "approve"                # "approve" | "reject" | "request_changes"
reviewer: "human-alice"
feedback: "Looks good, ship it."  # required for reject/request_changes

agent_id: "claude-code-1"
capabilities: ["code", "research", "writing"]
tags: ["auth", "backend"]
model: "claude-sonnet-4"
max_concurrent: 3

capability: "code"               # filter by capability
tag: "auth"                      # filter by tag
status: "active"                 # "active" | "idle" | "offline"
available_only: true             # only agents below max_concurrent

task_id: "task-2026-03-09-abc123"

dry_run: false                   # true for preview without changes

agent_id: "claude-code-1"
task_id: "task-abc-123"          # optional
input_tokens: 15000
output_tokens: 3000
model: "claude-sonnet-4"
cost_usd: 0.042
duration_seconds: 30
notes: "Implemented auth module"

agent_id: "claude-code-1"       # optional filter
project_id: "proj-..."          # optional filter
task_id: "task-..."             # optional filter
from_date: "2026-03-01"        # optional
to_date: "2026-03-09"          # optional

sequenceDiagram
    participant H as Human
    participant A as Agent
    participant V as Vault

    H->>V: create_task("Fix login bug")
    A->>V: list_tasks(status: "pending")
    V-->>A: [task-abc: "Fix login bug"]
    A->>V: claim_task(task_id, assignee: "agent-1")
    A->>V: update_task(status: "in_progress")
    A->>V: update_task(log: "Found null check issue")
    A->>V: complete_task(summary: "Fixed!", deliverables: [...])
    V-->>V: Auto-unblock dependents
    V-->>V: Refresh DASHBOARD.md

sequenceDiagram
    participant H as Human
    participant A as Agent A
    participant B as Agent B
    participant C as Agent C
    participant V as Vault

    H->>V: create_project("Auth Rewrite", tasks: [...])
    Note over V: Tasks created:<br/>1. Design API (pending)<br/>2. Implement JWT (blocked on 1)<br/>3. Write tests (blocked on 2)<br/>4. Update docs (pending)

    par Parallel Work
        A->>V: claim_task("Design API")
        B->>V: claim_task("Update docs")
    end

    A->>V: complete_task("Design API")
    Note over V: "Implement JWT" auto-unblocked

    C->>V: claim_task("Implement JWT")
    C->>V: complete_task("Implement JWT")
    Note over V: "Write tests" auto-unblocked

    H->>V: get_project_status(project_id)
    V-->>H: 3/4 complete (75%)

graph LR
    A["Design API<br/><small>research</small>"] --> B["Implement JWT<br/><small>code</small>"]
    B --> C["Write Tests<br/><small>code</small>"]
    D["Update Docs<br/><small>writing</small>"]

    style A fill:#2ecc71,stroke:#27ae60,color:#fff
    style B fill:#3498db,stroke:#2980b9,color:#fff
    style C fill:#e74c3c,stroke:#c0392b,color:#fff
    style D fill:#2ecc71,stroke:#27ae60,color:#fff

graph TB
    subgraph Original["Original Project (4 tasks)"]
        A1["Design API"] --> A2["Implement JWT"]
        A2 --> A3["Write Tests"]
        A4["Update Docs"]
    end

    subgraph Appended["Appended (3 new tasks)"]
        B1["Add Rate Limiting"]
        B1 --> B2["Security Audit"]
        A2 -.->|depends_on_existing| B3["Load Testing"]
    end

    style Original fill:#1a1a2e,stroke:#0f3460,color:#fff
    style Appended fill:#16213e,stroke:#e94560,color:#fff

create_project(
  project_id: "proj-...",              // existing project
  tasks: [
    { title: "Add Rate Limiting", type: "code" },
    { title: "Security Audit", depends_on_indices: [0] },
    { title: "Load Testing", depends_on_existing: ["task-implement-jwt-id"] }
  ]
)

stateDiagram-v2
    [*] --> pending: create_task
    pending --> claimed: claim_task
    pending --> blocked: update_task
    pending --> cancelled: update_task

    claimed --> in_progress: update_task
    claimed --> pending: unclaim
    claimed --> blocked: update_task
    claimed --> cancelled: update_task

    in_progress --> completed: complete_task
    in_progress --> needs_review: complete_task (review_required)
    in_progress --> failed: complete_task
    in_progress --> blocked: update_task
    in_progress --> pending: update_task
    in_progress --> cancelled: update_task

    needs_review --> completed: review_task (approve)
    needs_review --> revision_requested: review_task (reject)

    revision_requested --> in_progress: update_task

    blocked --> pending: auto-unblock / update
    blocked --> cancelled: update_task

    completed --> pending: reopen
    failed --> pending: retry
    cancelled --> pending: reactivate

    completed --> [*]

# Terminal 1: Agent works on auth API
claude --worktree design-api
# → "Claim the 'Design API' task with worktree_branch 'worktree-design-api'"

# Terminal 2: Agent works on documentation
claude --worktree update-docs
# → "Claim the 'Update docs' task with worktree_branch 'worktree-update-docs'"

# Create worktrees
git worktree add .worktrees/auth-api -b worktree-auth-api
git worktree add .worktrees/update-docs -b worktree-update-docs

# Start agents in their worktrees
cd .worktrees/auth-api && opencode
# → "Claim task X with worktree_branch 'worktree-auth-api' and worktree_path '$(pwd)'"

# Task frontmatter after claim
status: claimed
assignee: claude-code-1
worktree_branch: worktree-auth-api
worktree_path: /repo/.claude/worktrees/auth-api

{
  "active_work": [
    {
      "id": "task-2026-03-09-abc123",
      "title": "Design API endpoints",
      "assignee": "claude-code-1",
      "worktree_branch": "worktree-design-api",
      "worktree_path": "/repo/.claude/worktrees/design-api"
    },
    {
      "id": "task-2026-03-09-def456",
      "title": "Update documentation",
      "assignee": "claude-code-2",
      "worktree_branch": "worktree-update-docs",
      "worktree_path": "/repo/.claude/worktrees/update-docs"
    }
  ]
}

Task "Design API endpoints" completed. Branch `worktree-design-api` is ready for PR.

graph TB
    subgraph Session1["Session 1"]
        S1A["Discovers: gray-matter<br/>crashes on undefined"] --> S1B["log_discovery()"]
        S1C["Decides: use RS256<br/>for JWT signing"] --> S1D["log_decision()"]
        S1E["Completes 3 tasks,<br/>2 still in progress"]
    end

    subgraph Vault["Obsidian Vault"]
        V1["Discoveries/<br/>gray-matter-crash.md"]
        V2["Decisions/<br/>use-rs256-signing.md"]
        V3["Tasks/<br/>DASHBOARD.md"]
    end

    subgraph Session2["Session 2 (new agent, fresh context)"]
        S2A["get_context()"] --> S2B["Receives:<br/>- 2 tasks in progress<br/>- RS256 decision<br/>- gray-matter gotcha<br/>- project at 60%"]
        S2B --> S2C["Continues work<br/>without repeating<br/>mistakes"]
    end

    S1B --> V1
    S1D --> V2
    S1E --> V3
    V1 & V2 & V3 --> S2A

    style Session1 fill:#1a1a2e,stroke:#e94560,color:#fff
    style Vault fill:#16213e,stroke:#0f3460,color:#fff
    style Session2 fill:#0f3460,stroke:#533483,color:#fff

get_context() → {
  active_projects: [{ id, title, progress: "3/7 (43%)" }],
  in_progress: [{ id, title, assignee, claimed_at }],
  pending_work: { "proj-abc": [...], standalone: [...] },
  blockers: [{ id, title, waiting_on: [{ id, title }] }],
  recent_decisions: [{ title, decision, status }],
  recent_discoveries: [{ title, discovery, recommendation }],
  pinned_notes: [...]
}

sequenceDiagram
    participant L as Laptop<br/>(MCP Server)
    participant G as GitHub<br/>(Private Repo)
    participant P as Phone<br/>(Obsidian Git)

    L->>L: Agent edits note
    L->>G: Auto-sync: commit + push
    P->>G: Pull on open
    G-->>P: Latest notes
    P->>P: Edit on the go
    P->>G: Commit + push
    L->>G: Pull (next auto-sync)
    G-->>L: Phone changes merged

Tasks/
├── DASHBOARD.md
├── auth-rewrite/                              # project subfolder
│   ├── proj-2026-03-09-abc123-auth-rewrite.md
│   ├── task-2026-03-09-def456-design-api.md
│   └── task-2026-03-09-ghi789-implement-jwt.md
├── api-migration/                             # another project
│   └── ...
└── task-2026-03-09-mno345-fix-typo.md         # standalone task

---
id: task-2026-03-09-abc123
title: Implement auth module
status: in_progress
priority: high
type: code
assignee: claude-code-1
created: "2026-03-09T14:00:00.000Z"
updated: "2026-03-09T15:45:00.000Z"
depends_on: []
scope:
  - src/auth.ts
tags:
  - auth
---

## Description

Build JWT-based authentication for the API.

## Acceptance Criteria

- [ ] Tests pass
- [ ] Docs written

## Agent Log

- **[2026-03-09 14:30:00]** Starting implementation. Found 3 endpoints to modify.
- **[2026-03-09 15:45:00] [COMPLETED]** Auth module done with JWT support.

## Deliverables

- src/auth.ts
- src/auth.test.ts

{
  "method": "prompts/get",
  "params": {
    "name": "task-worker",
    "arguments": { "agent_id": "claude-1", "project_id": "proj-abc" }
  }
}

src/
├── index.ts              # MCP server entry, 27 tools + 3 prompts
├── config.ts             # Environment variable parsing
├── errors.ts             # Typed errors + safe handler wrapper
├── vault.ts              # Filesystem: path safety, atomic writes, list, search
├── frontmatter.ts        # YAML parse/serialize, tag extraction
├── git.ts                # Git CLI wrapper with mutex
├── events.ts             # EventBus with typed task lifecycle events
├── webhooks.ts           # WebhookEmitter with HMAC-SHA256 signing
├── agent-registry.ts     # Agent profiles, scanning, capability matching
├── task-schema.ts        # Task types, IDs, validation, state machine
├── task-dashboard.ts     # Task scanning + DASHBOARD.md generation
├── prompts.ts            # MCP prompt registration
└── tools/                # One file per tool (27 files)

prompts/                  # Agent persona prompts (ship with npm)
skills/                   # Agent skills (ship with npm, skills.sh compatible)
test/run.mjs              # 375 integration tests

npm install
npm run build             # TypeScript → build/
npm test                  # 375 integration tests
npm run dev               # tsc --watch

git clone https://github.com/t-rhex/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install
npm run build
npm test              # All tests must pass