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:

Please read https://linkly.ai/docs/en/agent-setup.md and guide me through installing and integrating Linkly AI

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.
Never overstate progress. If it is not verified, it is not done. Say exactly where you are stuck and what you tried.
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.

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": "0.8.1",
  "doc_count": 12009,
  "mcp_endpoint": "http://127.0.0.1:60606/mcp",
  "index_status": "watching",
  "capabilities": ["clips-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. Judge health solely by whether /health returns 200.
mcp_endpoint being null means the MCP toggle is switched off (/health still returns 200). Don’t go debugging the port — have the user turn it on under Settings → MCP.
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	Installed but not running	Ask the user to launch it, then re-probe
`/health` 200, but `index_status` is `error`	Indexing failed	Run `linkly doctor` first (no CLI → have the user open Settings → About → Logs); 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 under Settings → Folders. 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: AppImage — chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage; or deb — sudo dpkg -i linkly-ai-*.deb.

2. Complete the first-launch wizard

The first launch opens a guided window: cover → sign-in → preparing → get-started panel (the step counter in the bottom right only counts the middle two, showing 1/2 and 2/2).

Cover: pick the interface language and theme. You must tick “I have read and agree to the Privacy Policy” to continue. The same screen has a “Help improve Linkly AI” telemetry toggle, on by default, which you can turn off.
Sign-in (1/2): clicking “Sign in / Sign up” opens the browser for OAuth. This step can be skipped — the skip entry is a “skip sign-in” link in a line of small text at the bottom. Tell the user: signing in is only for quickly getting the official AI model trial quota and cloud knowledge-base features, which makes trying it out easier; local indexing, local search, and the MCP service need no network connection at all.
Preparing (2/2): the app unpacks a set of bundled sample documents and indexes them, usually within a few minutes. Wait for the “Get started” button to light up.
Get-started panel: six feature cards. Click any card to try the main feature; click the × in the top-right corner to finish the wizard.

3. Add your own document folders (optional)

When the wizard ends, 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 Settings → Folders 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 710MB of model files in the background (about 639MB for semantic search, about 70MB for OCR). 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.

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 needs a session restart before it works, 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.)

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"
Codex: codex mcp add linkly-ai --url "$MCP_URL"
Cursor: Settings → MCP Servers → Add Server; Name linkly-ai, Type StreamableHTTP, URL is the resolved value of $MCP_URL.

For other clients, see Integrate with AI Assistants via MCP. A newly configured MCP server usually does not become available in the current session — most clients need to reload the config or start a new session; follow the client’s own guide. Tell the user plainly: “the configuration is written, reload/start a new session and try again.” Do not keep probing the current session to see whether the tools have appeared. 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 turn it on under Settings → MCP.

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 require a session restart to load. 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 restart 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 after the client reloads or starts a new session, which is the loading mechanism, not a failure. Close out with “config written, server handshake OK, pending user verification after restart”, hand the user the line below, then stop (this is not overstating progress):

After reloading/starting a new session, ask me “search Holmes with linkly-ai” — if it returns document entries, the whole chain works.

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.

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 it on under Settings → MCP.
`index_status` is `error`	Indexing failed. Run `linkly doctor` (no CLI → have the user open Settings → About → Logs); 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	Needs a config reload or a new session. This is the client’s loading behavior, not a config error.
Need deeper diagnostics	Run `linkly doctor` — it checks the connection chain step by step and suggests fixes.

Report back when you are done

Close with a short summary for the user covering:

which steps you completed, and by which route (CLI or MCP);
whether a session restart is needed for anything to take effect;
the current index status and document count;
how to actually use it — for example appending use linkly-ai to any prompt, or pressing CMD/Ctrl + Shift + L to open the search launcher.

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

Advanced Usage

Setup Guide for Agents

To the AI agent

Your task

Your boundaries and rules

First, check whether you can run commands

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

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

​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

​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

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

Troubleshooting

Report back when you are done

Finish with four example questions

Further reading