This is the practical setup guide. We assume you have Claude Desktop installed and you want StrataFS to act as Claude’s eyes on your code and docs. Five minutes if your shell is friendly.

What you’ll have at the end

Claude Desktop will see four new tools — stratafs.search, stratafs.get_chunk, stratafs.list_sources, stratafs.stat — and will use them automatically when you ask code-related questions. Example:

You: What does auth/middleware/refresh.go do?

Claude: Let me look. (calls stratafs.search) The file implements the OAuth refresh-token flow. RefreshToken(ctx, raw) validates a refresh JWT against the keys in internal/session/jwt.go, exchanges it for a new short-lived access token (15 min), and rotates the refresh token per RFC 6819 §5.2. The rotation policy is documented in docs/runbooks/auth-rotation.md. …

Claude is not making this up. It read your file. The accuracy is yours, not the model’s.

Step 1 — install StrataFS

Pick one:

# macOS / Linux / Windows via npm
npm install -g stratafs

# Python users
pip install stratafs

# macOS / Linux via Homebrew
brew tap neul-labs/stratafs && brew install stratafs

# Docker (any OS)
docker run -d --name stratafs \
  -p 8080:8080 -p 8081:8081 \
  -v $HOME:/data:ro \
  ghcr.io/neul-labs/stratafs:latest

For the npm/pip/brew installs, the binary is on your PATH as stratafs.

Step 2 — initial config

stratafs config init

This writes ~/.stratafs/config.toml. Open it and add the directories you want indexed:

[[sources]]
name = "code"
type = "local"
path = "/Users/you/work"

[[sources]]
name = "docs"
type = "local"
path = "/Users/you/Documents/engineering"

Save. Then start the server:

stratafs serve

This runs the REST API on port 8080 and — the one we care about — the MCP server on port 8081. The first run will index everything; you’ll see throughput in the logs (typically 50–100 files/sec).

Step 3 — register the MCP server with Claude Desktop

Open Claude Desktop’s MCP config. On macOS this is:

~/Library/Application Support/Claude/claude_desktop_config.json

On Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add the StrataFS entry. If you have other MCP servers, merge it into the existing mcpServers object — don’t replace.

{
  "mcpServers": {
    "stratafs": {
      "url": "http://localhost:8081/mcp"
    }
  }
}

Save the file.

Step 4 — restart Claude Desktop

Fully quit Claude Desktop (not just close the window — Cmd-Q on macOS, right-click the tray icon on Windows) and reopen. MCP servers are discovered on launch.

Step 5 — confirm it loaded

Open a fresh chat. Type:

Can you list the tools you have available?

Claude should mention stratafs.search, stratafs.get_chunk, stratafs.list_sources, and stratafs.stat among the tools. If those four don’t appear, see the troubleshooting section below.

Step 6 — ask a real question

What’s the entry point of the code source? Find the file that owns auth.

Claude will call stratafs.list_sources first to see what’s configured, then stratafs.search for “auth entry point”, read the trimmed snippets, and answer with citations. The answer cites real file paths in your repository.

That’s it. You now have an AI assistant that has read your code.

Useful one-liners once it’s working

Three patterns I run constantly:

Find where a concept lives:

“Where do we handle JWT refresh in this codebase?”

Cross-source synthesis:

“What does the docs source say about rate limits, and where in the code is that enforced?”

Incident triage:

“We’re seeing 429s in production. Search for rate-limit configuration, then find the metrics dashboard for it.”

In each case Claude will run multiple stratafs.search calls — and StrataFS’s pre-shaped, sub-100ms responses keep the back-and-forth fast.

Troubleshooting

Tools don’t appear after restart. Confirm the JSON file is valid (jq . < claude_desktop_config.json should not error). Then check Claude’s logs:

  • macOS: ~/Library/Logs/Claude/
  • Windows: %APPDATA%\Claude\logs\

The startup log mentions each MCP server it tried to connect to and the result.

stratafs.search returns nothing. Verify the index is populated:

stratafs sources stats
# → code: 12 484 files, 87 220 chunks, last sync 12s ago

If the chunk count is zero, the worker pool hasn’t caught up yet — wait 60 seconds and try again. If it stays at zero, check stratafs queue list --status failed for parsing errors.

Claude says it can’t reach the tools. The MCP server probably isn’t running. Confirm:

curl -s http://localhost:8081/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

You should get a JSON-RPC response listing the four tools. If you get connection refused, restart stratafs serve (or check the systemd/launchd unit if you’re running as a service).

Permission errors on the indexed directory. StrataFS reads with the credentials of the user running it. If you ran stratafs serve from a regular shell but pointed it at a directory owned by another user, you’ll see “permission denied” entries in the queue. Either fix permissions or run stratafs serve as the right user.

Running it as a background service

For day-to-day use, you don’t want to keep a terminal open. The native installers register a service automatically; if you installed via npm/pip, set up your own:

macOS (launchd):

cat > ~/Library/LaunchAgents/com.neullabs.stratafs.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.neullabs.stratafs</string>
  <key>ProgramArguments</key>
  <array><string>/usr/local/bin/stratafs</string><string>serve</string></array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>
EOF
launchctl load ~/Library/LaunchAgents/com.neullabs.stratafs.plist

Linux (systemd user service):

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/stratafs.service <<EOF
[Unit]
Description=StrataFS semantic filesystem
[Service]
ExecStart=/usr/local/bin/stratafs serve
Restart=always
[Install]
WantedBy=default.target
EOF
systemctl --user enable --now stratafs.service

Either way, after the next login the MCP server is up before Claude Desktop launches.

This is the most useful five minutes of MCP setup we’ve seen. Try it and tell us what queries surprise you. Issues, ideas: github.com/neul-labs/stratafs/issues.