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.

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 | Progress | 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 Tools > Manage tools in Connect Pro settings 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.

Choose a returned note reference to read its contents.

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.

ChatGPT plugin: In Connect Pro settings, use Connect in the Connect session row, then turn on ChatGPT plugin and check its Remote MCP status. Select Setup beside ChatGPT plugin to find Open ChatGPT plugin and the connection instructions; the plugin link is also in the status bar menu. The shared Connect session also supports the dedicated GPT, which you do not need to open. 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 Desktop apps (Local MCP) > Setup > 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

In Connect Pro settings, choose Tools > Manage tools. The modal contains Tool permissions, Smart actions, and Standalone CLI tools (MCP). You can inspect access while connections are off.

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.

The ChatGPT marker means available when enabled. Check the tool switch and connection status separately.

Know whether a tool reads, proposes, or changes

A read returns information. Dedicated proposal tools defer their source changes to Inbox review. Other enabled tools can change notes or Context data directly.

When enabled, Review Obsidian CLI writes queues Connect-mediated native CLI writes before they run. Expand How review works to see what can be reviewed: exact create and inline append calls show file changes; other writes show the captured command and parameters. Turning this setting off does not apply pending proposals. Client confirmation dialogs are separate from Inbox review.

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, complete-note merge, or coordinated edit set belongs in your notes. Inspect the affected files and evidence, edit permitted text, then confirm once.

Choose the right proposal tool

Corrections and edit sets use references entries with source, excerpt, and optional external. For vault evidence, use an exact note/block key and quotation. For code, outside files, URLs, or user input from chat, set external: true and capture the relevant words. A descriptive label is enough; no working URL, file, or message ID is required. Connect Pro retains that text without fetching, verifying, or tracking the external source. Check whether it actually supports the change; a user requirement is not proof that the feature is implemented.

For example, a fictional chat requirement can be supplied as:

{
  "source": "Current chat / user's delivery requirement",
  "excerpt": "Deliver one offline PDF. Participants must not need a new account.",
  "external": true
}

Corrections accept 1-50 references; edit sets accept up to 50 references and 50 edits independently. Do not send the former flat reference fields or read_dependencies. In an edit set, text: "" deletes a replacement span or creates an empty note; an empty insertion is invalid. Move insert_text remains a separate field. Creation always returns pending; do not send status.

Check the evidence before applying. An older historical record should not be rewritten merely because a later decision differs. References never grant write permission: affected notes must still match the reviewed plan.

For a move, set to_key to an existing source or block key, or an absent vault-relative .md or .txt path for a new note. Connect Pro determines whether the destination exists; do not send destination_mode. placement: "append" inserts at the target end or after line_anchor_text; "prepend" inserts at the target start or before that line. The anchor must match one complete line exactly, including whitespace but excluding CR/LF, and occur once within the selected target. Omit it for a new note. Whole-note placement preserves frontmatter. Do not send link_update_policy; complete-note deletion uses Obsidian link handling. Files change only after approval.

Merge a complete note

Use propose_move_excerpt with a whole-note from_key, a destination in another file as to_key, and delete_source_file: true. Omit from_excerpt to include the complete current source, or supply its entire exact text. The destination can be an existing note or a new note path. 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 Approve to open the final confirmation. The source is marked Moves file to trash. The final confirmation names the affected files and offers Merge and move original to trash, or Create note and move original to trash for a new destination. 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. The merge remains pending.

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 Inbox in the header of Connect Pro settings, 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. Open a card to review it; grouping does not combine approvals. Compact change icons summarize the proposed effects.

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.

Read the captured quotation and its status together. Unknown does not establish that the reference is unchanged; inspect the source when the decision depends on its current content.

For edit sets covering four or more files, use the file list and Previous file / Next file controls to inspect one comparison at a time. Viewed means the current comparison was opened in this Inbox session, not read fully or approved. One approval covers every remaining file change.

This pending proposal aligns the delivery plan, preparation checklist, facilitator brief and unsent participant email around one offline PDF without a new account. The selected comparison is one part of the complete review.

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, complete-note insertion, or edit set. 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. In an edit set, Remove edit confirms removal of one saved operation while keeping the other edits and their drafts. Removing the final edit removes the proposal without changing notes or recording rejection.

For moves, use Change destination to choose another destination. Placement and the exact line anchor remain fixed during review; the new destination must resolve the same anchor when one is supplied. Check any fixed source replacement against the new destination. Different placement, anchor text, or source replacement requires a new proposal. 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.

Match the numbered passages and inspect their order before approval.

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 Approve. This opens the final confirmation directly. The dialog summarizes the effects, affected files and link consequences, with the final action named for the operation. 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.

For a larger edit set, confirmation lists unopened comparisons first. Cancel lets you inspect more files. Proceeding still applies the complete remaining set, not only the files marked Viewed.

Open Proposal actions with the ellipsis for Reject proposal... or Delete proposal.... Rejection records a decision without changing source files; deletion removes the pending item without rejection feedback or source changes. Next proposal leaves the item pending and opens the next review. Applied and rejected items appear in History; History is not an Undo control. An eligible rejected item offers Return to Pending for a new review of the same proposal, without restoring prior consent or changing notes. Applied items cannot return to Pending; execution, storage or recovery records can also block restoration.

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.

The approved merge brings the client decisions into the website plan. After the link update, the dashboard's Delivery agreement link opens the merged content.

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 Captured evidence 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 Approve, inspect the final confirmation, then choose Apply correction to make the target describe the offline handoff. Choose Cancel to keep reviewing, or Proposal actions > 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.

The approved correction changes Handoff plan to one offline PDF without a new account. Its next action remains Send the handout before the session.

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 Approve. 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.

On approval, this proposal creates Client follow-up and leaves a link in Meeting scratchpad. Recap agreement and Parking lot remain unchanged. Created on approval distinguishes the proposed new note from an existing destination.

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.

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.

Review your Connect Pro progress

Open Connect Pro stats from the Connect Pro status-bar menu, or run Smart Connect Pro: Open: Connect Pro stats in the Command Palette. Select Refresh to read the latest saved decisions and tracked activity.

The overview shows approval totals, changed words, returned words, and decisions by proposal type.

Interpret change sizes and measurement coverage

Average, Smallest, and Largest use measured approved proposals. Size groups are Small (0-99 words), Medium (100-999), and Large (1,000+).

Expand What these numbers include to check the measurement rules. Changed-word comparisons ignore surrounding punctuation and exclude automatic backlink updates. Very large unmatched edits are counted conservatively as additions and removals. Approved proposals without sufficient saved text remain in the decision count but are excluded from word and size totals.

Knowledge in use shows the response-tracking start and coverage. Newly tracked completions include error responses. Earlier completion records may include internal forwarding and omit failed calls; their returned-word totals cannot be recovered. The combined completion count does not establish complete historical coverage.

Copy a progress summary

Select Refresh, then Copy summary. The confirmation reads Summary copied with measurement coverage.

Paste into a note or message to keep the totals with their coverage explanation. The copied text distinguishes tracked responses from earlier completion records and includes the measured-proposal fraction.

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.

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.

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