Setup Guide for Agents

This page is written primarily for AI agents, not for people. If you use an AI assistant with shell access — Claude Code, Codex, Cursor, and the like — copy the line below and send it to your assistant. It will read this page and walk you through the setup:

Set up https://linkly.ai/docs/en/agent-setup.md

You are welcome to read on yourself — this is also a complete setup guide. It is just written more bluntly than most, with a heavy emphasis on how to tell whether each step actually worked. If your AI assistant cannot access the web, use Copy page in the top-right corner to grab this page as raw Markdown and paste it in directly.

To the AI agent

Everything below is addressed to you. Read all of it before you start.

Your task

Guide the user through installing and integrating Linkly AI. You are done when:

The Linkly AI desktop app is installed, initialized, and indexing — the bundled samples alone are enough; the user’s own documents are a bonus; and
You — or another AI tool the user owns — can genuinely call Linkly AI’s retrieval tools and find a real document.

Your boundaries and rules

Some things you can do yourself; others must be handed to the user. Do not overstep, and do not assume an outcome on the user’s behalf:

You can do yourself: run probe commands, install the CLI, configure MCP, install Skills, run verification commands, interpret errors, report back. For anything that installs software, show the command and get consent first.
The user must do: download and run the installer, complete the setup wizard, add document folders in the app, grant system permissions. These are GUI actions — you cannot do them.

And a few hard rules:

Probe before you act. The user may be half set up already, or reinstalling — do not blindly run through every step from the top.
Verify every step. Each step states its acceptance check. If the check does not pass, do not move on.
When the user must act, say everything at once, then stop and wait for a single reply. Do not split one task into several rounds of back-and-forth confirmation.
Show install commands and get consent before running them — especially anything that downloads and executes a script from the network.
Once MCP or Skills config is written, do not keep probing the current session to see whether the tools appeared. New tools only arrive once the client reloads — that is the loading mechanism, not a fault. Writing the config successfully completes the step; leave the rest of the verification until after the user reloads.
Never overstate progress. If it is not verified, it is not done. Say exactly where you are stuck and what you tried.
Do not ask the user for an API key (starting with lkai_) or a LAN access token, and do not run linkly auth set-key for them. These work like keys to the user’s local library; anything that passes through a conversation is sent to the model provider and kept in the chat history. To sign in, use the two-step linkly auth login flow (see R2–R4 in the remote branch) — the user only approves in the browser. If the user sends you a key or token anyway, do not use it; tell them to revoke it and create a new one in the dashboard (https://linkly.ai/dashboard/integrations), or, for a LAN token, regenerate it under View MCP connection settings in the desktop app.
Do not bypass permission, security, or verification requirements. When Troubleshooting doesn’t cover a problem, run linkly doctor first and check the relevant official guide; if you use an approach not listed here, state your reason and re-verify.

First, check whether you can run commands

This guide assumes you have shell access — Claude Code, Codex, Cursor, Gemini CLI, and the like. If you are an online application without a shell, such as ChatGPT or Claude.ai on the web, you cannot run the probe commands below and cannot install the CLI — the one thing that still applies is that the desktop app must be installed (relay Step 1 to the user in full). How you connect (remote MCP, uploading Skills, and so on) varies a lot per application, so read https://linkly.ai/docs/llms.txt, find the integration guide for the application you are running in (for example “Using Linkly AI in ChatGPT”), and follow that page to guide the user — do not generalize from this one.

Then, check whether the desktop app belongs on this machine

Steps 0–4 assume the desktop app runs on the same computer as you. If it never will — you are a bot on a remote server, in a container or on a cloud VM, while the user’s desktop app (if any) is on another computer — do not ask the user to install the desktop app where you are. Skip Steps 0–4 and follow Remote branch: no desktop app on this machine below instead. If you can’t tell, ask the user once.

Step 0: Probe the current state

Run this batch first, then use the result to decide where to start. macOS / Linux (bash / zsh):

echo "--- 1. port file ---"
cat ~/.linkly/port 2>/dev/null || echo "NO_PORT_FILE"
echo ""
echo "--- 2. health ---"
PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port 2>/dev/null)
curl -sf --max-time 5 "http://127.0.0.1:${PORT:-60606}/health" || echo "UNREACHABLE"
echo ""
echo "--- 3. cli ---"
linkly --version 2>/dev/null || echo "NO_CLI"
echo "--- 4. status ---"
linkly status --json 2>/dev/null || echo "NO_STATUS"
echo "--- 5. skills ---"
ls ~/.claude/skills/linkly-ai/SKILL.md ~/.agents/skills/linkly-ai/SKILL.md 2>/dev/null || echo "NO_SKILLS"

Windows (PowerShell):

Write-Output "--- 1. port file ---"
$port = 60606
if (Test-Path "$HOME\.linkly\port") {
  Get-Content "$HOME\.linkly\port"
  $port = (Get-Content "$HOME\.linkly\port" | ConvertFrom-Json).port
} else { Write-Output "NO_PORT_FILE" }
Write-Output "--- 2. health ---"
try { Invoke-RestMethod "http://127.0.0.1:$port/health" -TimeoutSec 5 | ConvertTo-Json -Compress } catch { "UNREACHABLE" }
Write-Output "--- 3. cli ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly --version } else { Write-Output "NO_CLI" }
Write-Output "--- 4. status ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly status --json } else { Write-Output "NO_STATUS" }
Write-Output "--- 5. skills ---"
if ((Test-Path "$HOME\.claude\skills\linkly-ai\SKILL.md") -or (Test-Path "$HOME\.agents\skills\linkly-ai\SKILL.md")) { Write-Output "SKILLS_OK" } else { Write-Output "NO_SKILLS" }

How to read the results

/health is the single most reliable probe. When the service is running it returns HTTP 200 and a JSON body:

{
  "version": "1.1.0",
  "doc_count": 12009,
  "mcp_endpoint": "http://127.0.0.1:60606/mcp",
  "index_status": "watching",
  "capabilities": ["clips-v1", "reveal-v1", "clip-tags-v1"]
}

Key points:

Never hardcode port 60606. It is only the default; if the port is taken the app increments upward. Always read the real port from ~/.linkly/port, whose contents are compact JSON: {"port":60606}.
A port file does not mean the service is running. The file is left behind when the app is force-killed or crashes. A /health 200 proves that the service is healthy, but an unreachable /health is inconclusive inside an AI-agent network sandbox because the sandbox may block localhost.
mcp_endpoint being null means the MCP toggle is switched off (/health still returns 200). Don’t go debugging the port — have the user click the Agent icon at the bottom of the main window’s left sidebar to open the Agent usage page, then turn on the Allow local access switch under Management (or click Start on the Stopped card).
index_status values: watching (finished — the CLI shows Up to date), scanning, indexing, idle, error.
doc_count is the number of indexed documents — use it to gauge indexing progress, not as hard proof that the user’s files landed: it’s just a total, and 151 vs 150 is barely distinguishable when only a file or two was added.

State table

Match top to bottom and follow the first row that hits (the table routes on link state along a single axis, so the rows are mutually exclusive):

Probe result	Meaning	Start at
No port file, `/health` unreachable	Not installed, or never launched	Step 1
Port file exists, `/health` unreachable	Desktop stopped, or probe is sandboxed	Use configured MCP; otherwise approve a retry outside the network sandbox. Ask the user to launch Desktop only if that retry also fails
`/health` 200, but `index_status` is `error`	Indexing failed	Run `linkly doctor` first and read the Local group (no CLI → have the user open `logs/app.log` via Settings → General → App Data → Open); don’t continue until it recovers
`/health` 200, but `linkly status` doesn’t work	App ready, CLI missing (or can’t connect)	Step 2
`/health` 200 and `linkly status` fine, but Skills not installed	Chain ready, Skills missing	Step 3
All of the above ready, and Skills installed	Essentially set up	Step 4 verification

Note: whichever step you enter at, if doc_count is only at sample level (~150), suggest — in your final report — that the user add their own folders by clicking Add folder in the Library sidebar of the main window. It is not a blocker; keep going.

Step 1: Install and initialize

This step is entirely manual — you cannot do any of it. Give the user the full sequence below in one message, then stop and wait for a single “done” reply. Do not walk through it item by item across multiple rounds. Here is what to relay to the user (rephrase in your own voice if you like, but cover all five parts):

1. Download and install

Go to https://linkly.ai/#download and grab the build for your operating system.

macOS: double-click the .dmg to mount it, drag the LinklyAI icon into Applications, then launch it from Launchpad.
Windows: double-click the .exe and follow the wizard (installs to the user directory by default), then launch it from the Start menu.
Linux: x86_64 AppImage — chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage (requires glibc 2.35 or newer, e.g. Ubuntu 22.04+ / Debian 12+; if it will not start, follow the Linux AppImage troubleshooting guide).

2. Complete the first-launch wizard

The first launch opens a guided window: cover → Bring your files in → Connect an agent → All set (the step counter only counts the middle two, showing 1/2 and 2/2). The interface language and appearance can be switched from the bottom-right corner of every screen.

Cover: you must tick “I have read and agree to the Privacy Policy” to continue. The same screen has a “Help improve Linkly AI (anonymous)” telemetry option, ticked by default, which you can untick.
Bring your files in (1/2): Sample files is required; the app indexes it in the background, so there is nothing to wait for. Documents, Desktop, and Downloads below are unticked by default — tick them as needed. On macOS, ticking one brings up a system permission prompt; click Allow.
Connect an agent (2/2): click Install next to Install the Linkly CLI and Skills, and the app installs the CLI and Skills in the background; Keep the CLI and Skills up to date is on by default. Nothing is installed unless you click Install — you can also install them later from the Agent usage page in the main window.
All set: click Get started to finish the wizard and open the main window’s home page.

The wizard has no sign-in step. Tell the user: signing in is only for features like the official AI model quota and cloud knowledge bases; local indexing, local search, and the MCP service need neither sign-in nor a network connection.

3. Add your own document folders (optional)

If no folders were ticked during the wizard, only the bundled sample documents are indexed — the user’s own files are not. Worth suggesting, but not required: the samples are enough to try Linkly AI out, and folders can be added at any time later. Either way works:

Open Library in the main window’s left sidebar, click Add folder, and add the directories to index (Documents, Downloads, a project directory, and so on);
Or drop files into the ~/LinklyAI folder — it is watched by default, so anything placed there is indexed automatically.

If the system reports insufficient permissions (common on macOS), go to System Settings → Privacy & Security → Full Disk Access, add Linkly AI, then restart the app. Suggest the user add their own folders that hold lots of local files — Documents, cloud drives, NAS, and the like — to the index.

4. Know that models are downloading in the background (no action needed, but tell the user)

After first launch the app downloads roughly 890MB of model files in the background (about 639MB for semantic search, about 249MB for OCR; turning on audio/video transcription later downloads another ~161MB speech-to-text model). Depending on the connection this can take from a few minutes to over an hour. During that window:

Keyword search works immediately and is completely unaffected;
Semantic search waits for the download and indexing to finish. Until then search automatically falls back to keyword-only (full-text) retrieval — relevance drops slightly. That is expected behavior, not a fault.

5. Reply once when all of it is done

Once all of the above is done, reply to the user once in a grateful tone — you will take over the rest.

Acceptance check: /health returns 200 and doc_count is above 0. If you just finished the wizard and doc_count is still 0 while index_status is scanning/indexing, the samples are still being ingested — retry every 10 seconds, up to 6 times; if it’s still 0, treat it as the error case in Troubleshooting. If the user added their own folders, doc_count will be clearly above the sample level; if they did not, that is no reason to hold up the rest. After the user replies: if the user clicked Install on the Connect an agent screen, the CLI and Skills may already be installed. The CLI lives at ~/.linkly/bin/linkly (%LOCALAPPDATA%\linkly\bin\linkly.exe on Windows), and the Skills at ~/.agents/skills/linkly-ai/.

Re-run the Step 0 probe first. Skip whatever is already installed in Step 2 Option A and Step 3 — don’t install it again.
If the linkly command isn’t found, have the user open a new terminal window first.
Exception: if you are Claude Code and ~/.claude/skills/linkly-ai doesn’t exist, the Skills are still invisible to you (Claude Code doesn’t read ~/.agents/skills). In that case, still run linkly skills install — it adds that link.

Step 2: Connect the tool path

There are two routes, and they are not mutually exclusive. Install the CLI first: it works the moment it’s installed, so you can call it and close the loop within the current session; MCP only works once the client reloads, so you can’t verify it on the spot. This is only a “can I self-verify in this session” priority — it does not mean the CLI is better than MCP as a product. If the user also wants Linkly AI in another AI tool, you can set up both. Don’t hardcode the port in any command below. At the start of this step, pull the real port into a variable and reference it from then on:

PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port)
MCP_URL="http://127.0.0.1:$PORT/mcp"

On PowerShell, reuse the $port from Step 0: $mcpUrl = "http://127.0.0.1:$port/mcp".

Option A: Install the CLI (recommended)

Show the user the command, explain that it downloads and executes an install script from the network, and get consent before running it: macOS / Linux:

curl -sSL https://updater.linkly.ai/cli/install.sh | sh

Or via Homebrew:

brew tap LinklyAI/tap
brew install linkly

Windows (PowerShell):

irm https://updater.linkly.ai/cli/install.ps1 | iex

Any platform (requires a Rust toolchain):

cargo install linkly-ai-cli

The install script installs the CLI and adds it to your PATH. If linkly is not found afterwards, have the user open a new terminal window (PATH changes don’t apply to already-open windows), or invoke the full path directly:

macOS / Linux: installed at ~/.linkly/bin/linkly, with PATH added to .zshrc / .bashrc / .profile;
Windows: installed at %LOCALAPPDATA%\linkly\bin\linkly.exe, modifying the user-level PATH.

Acceptance check: linkly --version prints a version, and linkly status --json returns JSON containing app_version and doc_count. (In the human-readable linkly status, that field is labeled Docs: and carries thousands separators; for programmatic checks always use --json.) Then name yourself on every call. Add --client <your-app-name> to every linkly command from here on — --client claude-code, --client cursor, whatever you are called. The desktop app keeps a local access log so the user can see which AI applications read their documents; without a name your calls land there as an anonymous local entry. It is a label, not a credential: it grants nothing and is never checked against anything.

Option B: Configure MCP

Use this when the CLI is awkward to install in the user’s environment, or when they want Linkly AI across several AI tools. Use the $MCP_URL from the start of Step 2 (i.e. http://127.0.0.1:$PORT/mcp) — do not hardcode 60606. Common clients:

Claude Code: claude mcp add --transport http linkly-ai "$MCP_URL?client=claude-code"
Codex: codex mcp add linkly-ai --url "$MCP_URL?client=codex"
Cursor: Settings → MCP Servers → Add Server; Name linkly-ai, Type StreamableHTTP, URL is the resolved value of $MCP_URL with ?client=cursor appended.

About ?client=: the desktop app keeps a local access log so the user can see which AI applications read their documents, and this is what gives the calls a name there. Use your own application’s name. It is a label, not a credential: it grants nothing and is never checked against anything, so leaving it off costs nothing but the name. (Over the remote tunnel there is nothing to add — the name comes from the OAuth login instead.) For other clients, see Integrate with AI Assistants via MCP. A newly configured MCP server usually does not become available in the current session — the vast majority of clients read the tool list once, at the moment the session starts. This is the client’s loading mechanism, not a configuration error, so do not keep probing the current session to see whether the tools have appeared. How to reload: relay both options to the user, and have them try the first one first.

Start a new conversation (for command-line tools, quit and open a new session). A conversation that is already running keeps the tool list it started with; a new one picks up the latest.
Quit the client completely, then reopen it. Use this when the first option doesn’t help — and note that closing the window is not quitting: on macOS press Cmd + Q or choose Quit from the menu bar, on Windows check that it also exited from the tray.

Acceptance check: the configuration was written successfully. To confirm the server itself is healthy without restarting anything, send a handshake directly (replace $MCP_URL with the resolved value):

curl -sf --max-time 5 -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'

A response containing "serverInfo":{"name":"linkly-ai" means the MCP service is healthy; a 403 means the MCP toggle is off — have the user go to the Agent usage page and turn on the Allow local access switch under Management (or click Start on the Stopped card).

Step 3: Install Skills

Skills teach you how to use Linkly AI’s tools well — search first, then outline, then read the parts that matter — which measurably improves retrieval quality. Strongly recommended. Again, show the command and get consent before running it:

npx skills add LinklyAI/linkly-ai-skills

If npx is unavailable, clone manually:

# Claude Code (user level)
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.claude/skills/linkly-ai

# Codex CLI
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.agents/skills/linkly-ai

Some users can’t reach GitHub — download our fallback package from the Linkly CDN instead:

https://updater.linkly.ai/skills/linkly-skills-latest.zip

To install for a specific client only (e.g. -a claude-code / -a codex) or other methods, see Using Skills. If the target directory already exists, it’s already installed — skip it (to update, cd in and git pull). Skills also need a reload to take effect, the same way as in Step 2 — start a new conversation first, and quit the client completely if that doesn’t help. The acceptance check is that the files landed in the right directory — not that the current session can already invoke them. Remind the user to reload afterwards. Acceptance check: a SKILL.md file exists at any of these paths — ~/.claude/skills/linkly-ai/SKILL.md (Claude Code user level), .claude/skills/linkly-ai/SKILL.md (project level), ~/.agents/skills/linkly-ai/SKILL.md (Codex). npx skills add picks one automatically based on the detected client, so just check these three paths afterwards.

Step 4: End-to-end verification

If you installed the CLI (Option A): run one real search to confirm the whole chain works. Check doc_count first — at sample level (~150), search a word from the sample library (e.g. Holmes); clearly above sample level means the user added their own folders, so use a word likely to appear in their documents:

linkly search "Holmes" --json

Success means: real document entries came back (when running on the samples only, hitting the sample docs counts as success too). If you only went the MCP route (Option B): you cannot finish this step within the current session — the tools only appear once the client reloads, which is the loading mechanism, not a failure. Close out with “config written, server handshake OK, pending user verification after the reload”, repeat the two reload options from Step 2, hand the user the line below, then stop (this is not overstating progress):

After reloading, send me this: “search Holmes with linkly-ai”. If it returns document entries, the whole chain works.

After the reload it is a brand-new session, and the you on the other side has none of this context. So that handover line has to carry everything it needs — the server name, the term to search — and must never read like “carry on from where we left off”. If a CLI search comes back empty, don’t jump to blaming the model — with the model not ready, search only degrades to keyword-only and won’t return empty. Check in order: is the query reasonable → is doc_count 0 (samples still ingesting, see the Step 1 acceptance check) → did the user add folders → is the format supported. Use linkly status --json to read index_status: indexing means it’s still building the index or downloading models — just wait; error → see Troubleshooting. Note: in the brief gap between the end of scanning and the start of content extraction, index_status shows watching (i.e. Up to date) prematurely. Do not judge readiness from a single sample — check again a few seconds later, or watch whether doc_count is still climbing.

Remote branch: no desktop app on this machine

This branch replaces Steps 0–4 when the machine you run on has no Linkly AI desktop app — a bot on a remote server or in a container, for example — and the user’s desktop app, if they have one, is on another computer. You reach the user’s content through the cloud. In the login below the user approves in the browser and the CLI stores the key itself — the key never passes through the conversation, and the user doesn’t copy anything.

R1: Install the CLI

Use the install commands from Option A in Step 2, with the same rule: show the command and get consent first. Acceptance check: linkly --version prints a version. linkly status fails here — there is no desktop app on this machine, so that is expected.

linkly auth status --json

If remote.valid is true, the user is already signed in — skip to R5. If it is null, the gateway couldn’t be reached — retry later and do not log out.

linkly auth login --no-wait --json

It returns {"status":"pending","url":…,"user_code":…,"expires_in":600} straight away. If it fails, the message names the command to run next — follow it.

R3: Hand the link to the user, then stop and wait

Send the user everything in one message, then stop and wait for a single reply:

the url — they can open it on any device, a phone included;
the user_code — they should check that the page shows the same code before clicking Authorize;
that the link is valid for 10 minutes, and that the page shows which account is being authorized, so they can make sure it is the right one.

linkly auth login --wait --json

Success is {"status":"ok","account":…,"plan":…,"key_preview":…}. On timeout, run the same command again — the link stays valid until it expires. On expired or denied, start over from R2. The user saying “done” is not proof. Trust only the CLI output: until --wait returns "status":"ok", the login has not finished.

Run R2 and R4 in the same environment, as the same system user, with the same config directory. The pending login is stored there; a fresh container, another user, or a different LINKLY_CONFIG_DIR cannot see it.
Serving several users? Give each user their own LINKLY_CONFIG_DIR (one directory holds one account), and set it on every command you run for that user, e.g. LINKLY_CONFIG_DIR=~/.linkly-alice linkly auth login --no-wait --json.
If your environment gets rebuilt and the credentials are gone, just log in again from R2.

R5: Verify in three layers

Check and report each layer separately — one passing says nothing about the next.

Login succeeded: linkly auth status --json shows "valid": true, along with the plan. This only proves the account; it does not prove any content is reachable.
Cloud search works (the Free plan is enough): with a cloud library the user has linked — ask the user if you don’t know one — run:
linkly search "<query>" --remote --library cloud://<owner>/<slug>
Real results mean it works. If the user has no cloud library, say this layer was skipped — not that it passed.
Local search works (the documents on the user’s desktop): this needs Pro and the desktop app online, with Remote Access connected (see Remote Access). Check first:
linkly doctor --remote
If the tunnel is connected, run linkly search "<query>" --remote and expect real results. If the desktop app is offline or the tunnel is not connected, report exactly that and tell the user to open the desktop app, turn on the Allow remote access (internet) switch under Management on the Agent usage page, and wait for the status to show Connected — do not claim success.

Troubleshooting

Symptom	Cause and fix
`/health` connection refused	The desktop app is not running. Ask the user to launch it and retry.
Port file exists but `/health` fails	Stale file from an unclean shutdown. Ask the user to relaunch the app.
Port unreachable but the app is running	60606 was taken and the port incremented. Read the real port from `~/.linkly/port`.
`/health` fine but the handshake returns 403	The MCP toggle is off. Have the user turn on the Allow local access switch on the Agent usage page (or click Start on the Stopped card).
`index_status` is `error`	Indexing failed. Run `linkly doctor` and read the Local group (no CLI → have the user open `logs/app.log` via Settings → General → App Data → Open); don’t continue until it recovers.
`linkly` command not found	Have the user open a new terminal; macOS/Linux use `~/.linkly/bin/linkly`, Windows use `%LOCALAPPDATA%\linkly\bin\linkly.exe`.
PowerShell says the script is blocked	Execution-policy restriction. Have the user run `Set-ExecutionPolicy -Scope Process -Bypass` in the same window (that window only) and retry, or use `cargo install linkly-ai-cli`.
Empty search	Don’t blame the model first (when the model isn’t ready it degrades to full-text and won’t return empty). Check in order: query, whether `doc_count` is 0, whether the user added folders, whether the format is supported.
`index_status` stuck at `indexing`	Normal for large collections or an in-flight model download. Watch whether `doc_count` is climbing.
Permission errors on macOS	System Settings → Privacy & Security → Full Disk Access, add Linkly AI, restart the app.
MCP configured but tools never appear	The client hasn’t reloaded yet. Have the user start a new conversation; if that doesn’t help, quit the client completely and reopen it (closing the window doesn’t count). This is the loading mechanism, not a config error.
Need deeper diagnostics	Run `linkly doctor` — it checks every connection this machine can use (the local desktop, plus remote and LAN when configured), one group each with advice; read the group for the connection you are setting up.

Report back when you are done

Close with a short summary for the user covering:

which steps you completed, and by which route (CLI, MCP, or the remote branch — for the remote branch, which of the three layers passed);
whether a reload is needed for anything to take effect — and if so, spell out both options (“start a new conversation” / “quit the client completely and reopen”);
the current index status and document count;
how to actually use it — for example appending use linkly-ai to any prompt, pressing Cmd/Ctrl + L to open the search launcher, or Cmd/Ctrl + K to open the main window (users upgrading from an older version keep the shortcuts they set before).

If any step could not be completed, say so plainly: where you got stuck, what you tried, and what the user can do next.

Finish with four example questions

End your report with four questions the user can copy and try immediately. Tailor them to the user’s actual material whenever you can: Take a moment to see what they indexed — run the explore tool (linkly explore on the CLI) to get the shape of the collection, and search a few themes if you need more detail. Then write four questions they would genuinely ask: grounded in their own documents and concerns, not generic filler like “summarize my documents.” A good question makes the user think “that is clearly about my files.” If the user has not added their own documents yet (doc_count is still at the sample-only level), use these four, which target the bundled sample library:

Read A Life in 10 Years and analyze the recurring life patterns across Samuel Pepys’s decade of diaries — and the blind spots he himself may never have seen.
What really makes Sherlock Holmes win? Read the 12 cases in Detectives Library, distill his case-solving formula, then turn Holmes’s method into a checklist for diagnosing complex business problems.
What did America’s founders truly fear? Read the entire Federalist Papers and give me an answer. Explain how they designed a system that pits ambition against ambition and faction against faction — then translate that logic into governance principles for today’s AI companies or internet platforms.
After reading firsthand memories from hundreds of formerly enslaved people, what do American history textbooks least dare to spell out? Answer based on the WPA Slave Narratives.

Getting Started

Core Features

Connect Your AI Tools

For AI Agents

Setup Guide for Agents

To the AI agent

Your task

Your boundaries and rules

First, check whether you can run commands

Then, check whether the desktop app belongs on this machine

Step 0: Probe the current state

How to read the results

State table

Step 1: Install and initialize

1. Download and install

2. Complete the first-launch wizard

3. Add your own document folders (optional)

4. Know that models are downloading in the background (no action needed, but tell the user)

5. Reply once when all of it is done

Step 2: Connect the tool path

Option A: Install the CLI (recommended)

Option B: Configure MCP

Step 3: Install Skills

Step 4: End-to-end verification

Remote branch: no desktop app on this machine

R1: Install the CLI

R3: Hand the link to the user, then stop and wait

R5: Verify in three layers

Troubleshooting

Report back when you are done

Finish with four example questions

Further reading

​To the AI agent

​Your task

​Your boundaries and rules

​First, check whether you can run commands

​Then, check whether the desktop app belongs on this machine

​Step 0: Probe the current state

​How to read the results

​State table

​Step 1: Install and initialize

​1. Download and install

​2. Complete the first-launch wizard

​3. Add your own document folders (optional)

​4. Know that models are downloading in the background (no action needed, but tell the user)

​5. Reply once when all of it is done

​Step 2: Connect the tool path

​Option A: Install the CLI (recommended)

​Option B: Configure MCP

​Step 3: Install Skills

​Step 4: End-to-end verification

​Remote branch: no desktop app on this machine

​R1: Install the CLI

​R1.5: Check for an existing login

​R2: Start the login

​R3: Hand the link to the user, then stop and wait

​R4: Finish the login

​R5: Verify in three layers

​Troubleshooting

​Report back when you are done

​Finish with four example questions

​Further reading

To the AI agent

Your task

Your boundaries and rules

First, check whether you can run commands

Then, check whether the desktop app belongs on this machine

Step 0: Probe the current state

How to read the results

State table

Step 1: Install and initialize

1. Download and install

2. Complete the first-launch wizard

3. Add your own document folders (optional)

4. Know that models are downloading in the background (no action needed, but tell the user)

5. Reply once when all of it is done

Step 2: Connect the tool path

Option A: Install the CLI (recommended)

Option B: Configure MCP

Step 3: Install Skills

Step 4: End-to-end verification

Remote branch: no desktop app on this machine

R1: Install the CLI

R1.5: Check for an existing login

R2: Start the login

R3: Hand the link to the user, then stop and wait

R4: Finish the login

R5: Verify in three layers

Troubleshooting

Report back when you are done

Finish with four example questions

Further reading