Connect Pro for Obsidian
Connect ChatGPT to existing Obsidian notes and propose improvements for review in Smart Inbox; requires Obsidian Desktop running with Connect Pro.
Documentation
Connect Pro helps your AI app use and improve the Obsidian notes you rely on. Its proposal tools hold suggested changes in Smart Inbox for your review.
This documentation is the canonical reference for Connect Pro's tools, connection and permission requirements, proposal review, and recovery. Its sections provide stable reference points for setup instructions and task-specific guides.
New connection? Connect the ChatGPT plugin (recommended), or explore other setup options.
Already connected? Choose an example.
Need to fix something? Open troubleshooting.
Reference sections
Examples | Connections | Permissions | Inbox review | Practice a correction | Review feedback | Recovery | Smart CLI
Examples and workflows
Start with a read-oriented task. Choose your Connect Pro connection in the app and replace the bracketed values before sending a prompt. Use Tool permissions and the app's current tool list to check availability; installed plugins and access settings determine which examples you can run.
These prompts request limited tasks. They do not replace access controls, and inputs and returned content may be processed by the app's model provider.
Resume from recent notes
Find a useful place to pick up your work without opening every recent note.
Use only Connect Pro for "[vault name]".
Use the read-only recents tool or command to list up to five recent
note references. Do not read their contents or change anything.
If the tool is unavailable, tell me rather than using another connection.
What to expect: note names or references, not note bodies. The tool may return more entries than the app displays; an empty list is valid. Choose one returned note to read next.
Requires: the native recents command and Obsidian CLI support. For its dedicated Local MCP tool, enable that tool's individual switch. Remote GPT uses the native command through its CLI connection.
Find notes about a topic
Find material related by meaning, then decide which sources deserve a closer read.
Use only Connect Pro for "[vault name]".
Find up to five notes about "[topic]" using Smart Lookup.
Use query="[topic]", limit=5, results_collection_key="smart_sources",
and include_content=false. Show the source references and relevance
information actually returned, not quotations or summaries of note text.
Do not change anything. Report a missing tool or index/provider error
instead of using another connection.
What to expect: references you can choose to read, not summaries of their contents. No matches is a valid result. Semantic search may use the configured embedding provider even though this request does not return note bodies.
Requires: Smart Lookup, a ready semantic index/provider, and the permitted smart_lookup_query tool. Remote GPT uses smart:lookup:query with the same arguments.
Earlier-release example, captured with Connect Pro 2.0.1: search within the demo folder for source references, then choose which notes to read. This request did not return their full text.
Same call, a different native result-panel scroll position. The response reports three matches; only its first result object is visible here. The three-row table is the assistant's reference-only answer, not the complete native JSON.
Inspect a named Smart Context
A Smart Context stores source selections for a task. This example lists the notes, blocks, and other sources selected by its current rules and exclusions.
Use only Connect Pro for "[vault name]".
Get the existing Smart Context "[context name]" using
name="[context name]" and output_type="file_tree".
Show its returned name, description, resolved item count, source
references, and diagnostics. Keep missing items and truncation visible.
Do not export source text, create a context, or change its saved rules.
If it is unavailable, tell me rather than using another connection.
What to expect: references to the selected sources, without returning their full text. The item count can include missing sources; check diagnostics for missing items or truncation.
Use manifest instead to inspect saved inclusion and exclusion rules and local settings; its total counts inclusion rules. Names, paths, and descriptions may contain private information.
Requires: Smart Context and smart_context_get (smart:context:get through Remote GPT). To find an existing name first, use smart_context_list or smart:contexts.
Workflows that create review items or change data
To change notes through review, review one useful move in your own notes or practice one correction with the example notes. Both create a pending Inbox item; applying it is a separate decision in Obsidian.
Creating a Smart Context is a direct data change, not an Inbox proposal. With the relevant tools enabled, choose a new name and exact source, use smart_context_create followed by smart_context_add, then inspect the manifest. If only creation succeeds, inspect that context before retrying the add; do not repeatedly create new contexts. Use the installed tools' argument requirements.
Review one useful change in your own notes
After your first successful read, choose two different existing notes: one containing a passage you expect to reuse, and the note where you would naturally look for it. Start with one topic, not a vault-wide cleanup.
Use only Connect Pro for "[vault name]".
Read "[source note path]" and "[existing destination note path]".
Find one useful passage about "[topic]" that belongs in the destination.
Use propose_move_excerpt to propose that move. Keep its factual meaning;
rewrite only where it improves clarity in the destination. Preserve
meaningful history in the source and leave a short link when helpful.
Leave the proposal pending in Smart Inbox and report its item key.
Do not apply it, delete either note, or use direct-write tools.
If no worthwhile move exists or the tool is unavailable, explain why
instead of creating a proposal or using another connection.
What to expect: one pending proposal and no changes to either note. A move removes the selected passage from the source when applied; it is not a copy. The review should show what will move, any revised wording, what will remain at the source, and the destination.
Your decision: inspect both sides in Changes by file. Adjust the proposed insertion when useful, accept an appropriate suggestion unchanged, or reject it. After applying, inspect both saved notes. The source note remains; this is not a complete-note merge.
Requires: access to both notes and the enabled propose_move_excerpt tool. The request does not replace your tool permissions. A useful result is easier-to-find information, not an extra item in the queue. Continue with a task that reads the updated note.
Select and check a connection
For the simplest setup, start with the ChatGPT plugin: no desktop extension or local server URL to configure. Keep the intended vault open in Obsidian Desktop. The getting-started guide explains each option; settings supplies this installation's details.
| Connection | Use it for | Start here |
|---|---|---|
| ChatGPT plugin (recommended) | The easiest way to use ChatGPT with your vault | Open ChatGPT plugin |
| Local MCP | ChatGPT Desktop, Claude Desktop, or other compatible apps on this computer | Desktop setup |
| Smart Connect Pro GPT (legacy) | Existing dedicated GPT; being discontinued | Legacy GPT setup |
ChatGPT plugin: Turn on ChatGPT (Remote MCP) in Connect Pro settings, then use Open ChatGPT plugin in that row or the status bar menu. It requires an active Connect session, but you do not need to open the dedicated GPT. Follow ChatGPT plugin setup.
Local MCP works separately on the same computer as Obsidian. The dedicated Smart Connect Pro GPT is being discontinued as Connect Pro transitions to ChatGPT plugins; its existing connection remains documented for current users. Smart CLI is a separate native command interface, not another app connection.
A running or ready status does not prove the app reached your vault: read a note you recognize. Local transport does not mean the app's model runs locally.
Choose a Local MCP port
Open Advanced > Local MCP port to set an integer from 1024 to 65535. Apply saves the port and restarts Local MCP if it is enabled. Existing desktop-app configurations must then use the new Server URL; changing the port does not update those clients automatically. Leave a working port unchanged unless you need a different one.
Understand tool permissions
Open Settings > Smart Connect Pro > Tool permissions. You can inspect access while connections are off.
| Control | What it controls |
|---|---|
| Smart actions: CLI + Remote GPT | The listed Smart action through Smart CLI and Remote GPT. |
| Smart actions: MCP | The listed action exposed as an MCP tool. |
| Standalone CLI tools (MCP) | Native commands exposed as separate MCP tools. |
| Broad CLI access (Local MCP) | The general obsidian_cli MCP tool, which can call native commands. |
Individual switches do not restrict the broad CLI tool
On Local MCP, when Broad CLI access is on, a native command can remain callable through obsidian_cli even when its individual MCP switch is off. Remote MCP never exposes that generic dispatcher; dedicated native Tools must be individually enabled and eligible. Guarded Smart actions still honor their CLI switches. Turning broad access off removes that path; it does not disable separately enabled tools or Remote GPT's native commands.
These controls are not a global command allowlist. Other enabled tools can provide additional access, and unrelated CLI commands are outside these switches. New Smart actions default to enabled; the native default selection can include writes. Review the actual controls rather than assuming a read-only starting setup.
After changing permissions, refresh your app's tool list. A disabled Smart CLI action is blocked immediately, even if its command remains listed until Obsidian restarts.
An individual MCP switch controls that dedicated tool. Broad CLI access provides a separate path to native commands.
Know whether a tool reads, proposes, or changes
A read returns information. A proposal saves an Inbox item for later review. A direct-write tool can change notes or Context data when invoked. Dedicated proposal tools defer their source changes to Inbox review. Client confirmation dialogs and tool effect labels are separate from that review process.
Keep a request focused
Choose the vault and exact note, block, or named context. Read current content before requesting a change. For blocks, use keys returned by the tools rather than constructing one from a heading.
When the result is unexpected, inspect the request before retrying. Advanced > Tool requests > View requests contains completed request payloads from the current Obsidian session. These can include note content. They are not saved Inbox History and do not include every failure.
Review proposed changes in the Inbox
The Inbox is where you decide whether a proposed correction, move, or complete-note merge belongs in your notes. Review the source and destination, edit the permitted insertion, then confirm the changes once. The workflow below describes Connect Pro 2.0.3.
Choose the right proposal tool
| Tool | Use it to | Keep in mind |
|---|---|---|
propose_correction | Replace one exact claim using a reference excerpt | One independent phrase, sentence, list item, or table cell per proposal. The target excerpt must occur once in the selected target. |
propose_move_excerpt | Move an exact passage, optionally rewriting its insertion | The source file remains unless a complete-note merge explicitly sets delete_source_file: true. This is a move, not a copy. |
propose_move_blocks | Move complete selected blocks and their children, in order | Preserves text and heading levels. Whole-note keys, duplicates, and overlapping parent/child selections are invalid. |
Check whether the correction evidence actually supports the new wording. An older historical record should not be rewritten merely because a later decision differs.
A move must explicitly append to an existing destination or create a new .md or .txt note. Missing append targets and sections are not created automatically. A new destination file is created only when you apply the proposal.
Merge a complete note
Use propose_move_excerpt with a whole-note from_key, its entire exact current text as from_excerpt, and delete_source_file: true. Choose a different existing destination with destination_mode: append, or a new note path with destination_mode: create. Optional insert_text supplies a rewritten insertion; omit it to keep the source text unchanged. A complete-note merge cannot leave source_replacement text behind.
Review Changes by file, comparing the complete source with its destination insertion, then choose Review merge.... The source is marked Moves file to trash. The final confirmation names the affected files and offers Merge and move original to trash. The intact original moves to trash only after the destination is saved and verified. Passage and selected-block moves retain their source notes, even if a note becomes empty. Metadata is not automatically reconciled.
Client review notes and Website launch plan are separate file columns. The first-review sentence is rewritten, while the private-site rule and launch scope remain. Review merge... is still unused.
Source-removing merges include native Obsidian link handling, including older pending merges. No separate link_update_policy argument is needed. Link handling happens during execution, not as a required preflight reference table. Declining, unavailable support, or a link-update failure leaves the content merge applied; inspect the separate link result afterward.
Recognize a pending result
A successful proposal returns an item key, status: pending, and source_files_changed: false. The notes have not changed yet. Do not repeat the request just because it is waiting for review.
An identical, still-valid pending proposal returns the existing key with deduplicated: true. This detects an exact repeat, not a similar idea. Changing only its reason or group does not update that existing item. Rejection does not permanently suppress a future proposal.
Open and organize the Inbox
Use Settings > Smart Connect Pro > Review > Connect Pro Inbox, the ribbon action Open Connect Pro Inbox, or the Command Palette action Open: Connect Pro Inbox view.
Pending holds work awaiting a decision; History holds applied and rejected items. Choose All pending, Ungrouped, or a named group to narrow the queue. Each card has its own Review action; grouping does not combine approvals. Compact change icons summarize the proposed effects.
This demo has five pending items and eighteen earlier History records. Each correction, block move, excerpt move and complete-note merge is reviewed separately.
Inspect and refine the result
Changes by file keeps each affected note identifiable. The file header states whether it will be updated, created or moved to trash.
| Proposal | What to inspect |
|---|---|
| Correction | Expand Reference evidence - read only and check the exact target replacement. Choose Inline or Compare; the comparison stacks in a narrow pane. |
| Selected-block move | Match the numbered source removals with their destination insertions, then inspect Insertion order. |
| Excerpt move | Compare the source removal, any Replacement at source, and the destination insertion. Neutral source context remains outside the move. |
| Complete-note merge | Compare the complete source and destination insertion, including the source's Moves file to trash outcome. |
Blue move labels identify transferred text. Select a move label to highlight the corresponding source and destination passages. Red and green changes distinguish rewritten wording; unchanged text stays neutral. Expand hidden context only when needed to understand the insertion location.
Use Edit replacement text for a correction or Edit proposed text for an excerpt or complete-note insertion. Done editing keeps a review draft; it does not apply the change. Cancel editing returns to the text from the beginning of that editing session. Finish editing before requesting final review.
For moves, use Change destination to choose the intended destination and insertion location. A new note is marked Creates file and Created on approval until application.
For block moves, expand Insertion order to reorder the original selection. Adding or removing blocks requires a new proposal. Check included child sections, heading placement and source removals. Moving a heading does not automatically nest it under the destination heading. Ordinary passage and block moves do not retarget whole-note links.
Select label 1 to match Reader need, select label 2 to match Weekly format, then inspect their order. Both complete sections remain unchanged; the three-note move stays pending. The final hold shows the order controls; complete passages appear earlier in the walkthrough.
Read the caller's intent and open Proposal details for the full explanation and proposal identity. Click a note name to open it, or its folder path to copy the location. The caller's explanation is context to assess, not proof that the change is correct.
Understand link behavior before a complete-note merge
Read the link-behavior message below the file comparison and in the final confirmation. Incoming links are handled during the merge using Obsidian; the pending review does not enumerate a preflight reference scope. Some references, including heading and block targets, may still need attention. Retargeting a note link does not automatically repair a missing or renamed anchor.
Obsidian's existing link-update preference controls whether links update automatically or prompt after the content merge. Declining, unavailable support, or a link-update failure does not undo the content merge. Inspect the recorded link result and affected notes afterward rather than assuming every reference was updated.
Keep reviewing when a source changes
Reopen a pending complete-note merge, or use its available source-refresh control, to read the latest complete source without creating another proposal. An untouched, unchanged insertion follows the current source. A proposed rewrite or explicit insertion draft stays preserved.
When the review reports a source change, inspect the original proposal snapshot against the current source separately from the destination insertion. Deliberately incorporate anything the preserved insertion still needs; refreshing the source does not make that editorial decision for you.
If files change after confirmation, the stale merge is stopped and the review refreshes for another confirmation. Nothing is applied again automatically. Partial excerpts and selected blocks still need a new proposal if their original selection no longer matches.
Confirm, reject, or leave for later
After the comparison matches your intent, choose Review merge..., Review move..., or the displayed apply action. One final dialog, such as Confirm merge or Confirm move, summarizes the effects, affected files and link consequences. Cancel returns to the pending review without applying changes. Decision controls remain available while you inspect a long review.
The final confirmation names both files and the reviewed rewrite. Cancel keeps the proposal pending.
Reject proposal records a decision without changing the source files. Next proposal leaves the current item pending and moves to the next review. More > Delete proposal... removes an unwanted proposal without recording rejection feedback or changing source notes. Applied and rejected items appear in History; History is not an Undo control.
For a complete-note merge, inspect the merge result and native-link result separately. Declining Obsidian's link prompt leaves the merge applied and links unchanged; unavailable support or a link-update failure also leaves the content merge applied. Do not repeat the merge to retry links. Open the destination and affected referring notes to verify the result; use any available link-only review or retry action for the recorded link scope.
In this separate Harbor website example, ChatGPT queues the complete client decisions for unchanged insertion in the working website plan. After Just once updates three captured references across two files, the reviewer follows the dashboard's Delivery agreement link into the saved plan. The earlier pending examples remain intact.
Practice one reviewed change
After setup, use two disposable notes to learn the review loop. This exercise creates a saved proposal and changes the target only if you apply it. It is not a connection requirement.
Propose one correction
Manually prepare a reference note with Deliver one offline PDF. Participants must not need a new account. and a target with We will deliver the workshop in an online workspace. Treat the offline PDF and no-account requirement as the agreed handoff for this exercise. Replace the paths and vault name below:
Use only Connect Pro for "[vault name]".
Read "[reference note path]" and "[target note path]".
Use propose_correction to suggest replacing the online-workspace
claim with one offline PDF and no new account, supported by the reference.
Make one proposal, leave it pending for review in Obsidian, and report
its item key. Do not use a direct-write tool or another connection.
The result should be pending, with source_files_changed: false. Check that the target still promises an online workspace.
Review in Obsidian
Open the Inbox and review that item. Expand Reference evidence - read only and select Compare to check the exact replacement. Edit it only as needed, then inspect the current comparison.
Apply or reject and inspect the outcome
Choose Apply correction, inspect the final confirmation, then confirm to make the target describe the offline handoff. Choose Cancel to keep reviewing, or Reject proposal to retain the target and record rejection. Check the actual target and reference notes, then the item's History entry. The reference should be unchanged by the correction.
Separate fresh Handoff plan example: the approved correction updates the actual note to one offline PDF without a new account. Next action stays Send the handout before the session., the reference is unchanged, and captured History shows 5 Pending / 19 History.
Read the decision and stop the route you used
When enabled, get_proposal_feedback can read the returned item key to show the recorded decision. It does not apply the proposal. Disconnect the connection you used when finished; stopping access does not undo an applied change.
Review a rewritten excerpt move
For a partial move, compare the source removal and destination insertion in Changes by file. Check any Replacement at source and the neutral source context. Edit proposed text opens the insertion draft; finish editing before choosing Review move.... After application, check both notes: the destination should contain the reviewed insertion, and the source should contain the reviewed replacement or remainder. Its original file remains unless this was explicitly a complete-note merge.
This separate proposal would create Client follow-up and leave a deliberate pointer in Meeting scratchpad. Recap agreement and Parking lot remain unchanged. Created on approval distinguishes the proposed new note from an existing destination.
Open Edit proposed text, inspect the PDF recap and the message Changes are kept in this review until approval, then choose Cancel editing. This walkthrough enters no text and ends with the move still pending.
Continue after the first result
After applying a correction, ask your AI app to read the updated note before the next task. Have it identify the current commitment and relevant constraints, then compare its answer with the saved note. The approval record alone does not establish that later requests will use the correction.
After a correction or move, adapt this read-only follow-up:
Use only Connect Pro for "[vault name]".
Read "[updated note path]" again with an available read-only tool.
Use the current note to help with "[next task]".
Identify the source and distinguish what the note states from any
new suggestions. Do not change notes. If the note cannot be read,
report that rather than substituting the earlier conversation.
Check the actual read and whether the response uses the information you kept. A confident answer alone is not evidence that the app read the updated note.
To try another supported AI app, confirm that it connects to the same vault and actually retrieves the updated note. Shared note access does not synchronize conversations or guarantee that the app will select the right information.
Expand to a small project or review batch when the result justifies the setup and review involved. Groups help find related items without combining approvals. Read current sources before proposing new changes; earlier decisions provide context, not permission.
Use proposal feedback
get_proposal_feedback returns saved proposals and decisions so an app can consult related review history. It does not read current source notes, make decisions, or automatically learn preferences.
Use an exact item key alone, or query a filtered list. Lists default to reviewed items, newest review first, and 10 results; limit accepts 1 through 25. Filters include status, proposal type and group. Continue with the returned next_cursor as cursor alone, preserving the original query.
Applied-item comparison | Meaning |
|---|---|
edited | Original proposed and final applied values show what changed during review. |
unchanged | The reviewable values matched. |
unknown | Original comparison evidence is unavailable. Missing proposed values do not mean unchanged. |
A rejected item means the whole proposal was declined. When reviewer_feedback is present, it is the reviewer's explanation for that rejection and applies to that proposal. Without it, do not infer a reason. proposal_reason remains the proposer's rationale. A pending item has no human decision.
Ground observations in item keys and relevant cases. Repeated items, a filtered page, or an empty result do not establish a general preference. Current instructions and current source text still govern the next task.
Understand approval, recovery, and stopping
Use Inbox review for the dedicated proposal tools. Other write-capable tools are not automatically held for approval there.
If a source changes, refresh and inspect the preview. Complete-note merges can continue with the same pending proposal and current source; preserved rewrites still need your review. For a partial excerpt or selected block that no longer matches, read current content and make a new proposal. If a new-note path becomes occupied, choose the intended destination again; creation does not silently become append.
Manual recovery required
Stop and inspect the named files and saved review state. A failed application can leave partial changes or an unresolved decision. The item stays blocked; simply inspecting or rejecting it does not repair files or clear the recovery requirement. Avoid a blind retry.
Connect Pro checks writes and attempts recovery after a partial failure, but it cannot guarantee full rollback across multiple files. The Inbox has no Undo command. Native link updates for complete-note merges are a separate recorded phase, not universal link or anchor repair. Keep a backup or version-history workflow.
An indexing warning after a successful application is different from a failed write. Inspect the notes and refresh indexing rather than applying the same change again.
Turning off ChatGPT (Remote MCP), stopping Local MCP, or disconnecting the legacy Smart Connect Pro GPT stops new requests through the chosen connection. These controls do not undo changes or guarantee cancellation of requests already running. Turning off one connection does not automatically turn off the others or Smart CLI.
Access from another device
For ChatGPT on another device, start with the ChatGPT plugin and keep the intended Obsidian Desktop vault open and connected through ChatGPT (Remote MCP). Local MCP works only for an app on the same computer; its 127.0.0.1 address is not a public endpoint. A running local server does not establish remote availability. The dedicated GPT is a legacy connection being discontinued in favor of the ChatGPT plugin.
Smart CLI Pro
Smart CLI exposes registered Obsidian commands for the same Smart actions. Enable host CLI support and check Advanced > Obsidian CLI integration. The installed command metadata determines available arguments.
| Smart tool | Smart CLI command |
|---|---|
smart_source_read | smart:source:read |
smart_lookup_query | smart:lookup:query |
smart_context_list | smart:contexts |
smart_context_get | smart:context:get |
propose_correction | smart:propose:correction |
propose_move_excerpt | smart:propose:move:excerpt |
propose_move_blocks | smart:propose:move:blocks |
get_proposal_feedback | smart:get:proposal:feedback |
These commands require the corresponding available, enabled action. A CLI proposal still creates a pending Inbox item. It does not bypass review.
smart_source_read uses an exact existing Smart Source key; for a vault note, use its source key rather than a block key or guessed title. A permitted native read command instead uses its own file-path arguments. Follow the live schema when resolving a note.
Older instructions may mention smart:help or smart:skills; they are not available commands in this implementation. Use the current command inventory instead.
Troubleshooting
Go to FAQ and troubleshooting for a symptom and its next check.
Related documentation
Getting started | Connect Pro FAQs | Smart Plugins documentation