SemanticFS Skill#

SemanticFS provides semantic search over your local filesystem. Instead of running multiple grep/find/ls/cat commands to locate code or files, ask SemanticFS once and get back exact paths and line ranges.

When to use#

Use this skill whenever you need to:

• Find a file, function, class, or symbol by name or description
• Locate where a concept is implemented (e.g. "authentication logic", "error handling for uploads")
• Navigate an unfamiliar codebase without reading every file
• Replace a chain of grep, find, ls, or cat commands

Do not use this skill if:

• The directory hasn't been indexed yet (run semanticfs index build first)
• You need to write or modify files (SemanticFS is read-only)

Prerequisites#

SemanticFS must be installed and the target directory must be indexed:

bash

# Install (Linux/macOS)
curl -sSfL https://raw.githubusercontent.com/Navneeth08k/semanticFS/main/scripts/install.sh | bash

# Index your workspace
semanticfs --config ~/semanticfs.toml index build

Starting the server#

SemanticFS must be running before you can search:

bash

# Start HTTP server (runs in background)
semanticfs --config ~/semanticfs.toml serve mcp &

# Check it's up
curl -s http://localhost:9464/health/live && echo "SemanticFS is running"

If you get a connection refused error, the server is not running. Start it with the command above.

Searching the codebase#

Replace grep -r "pattern" . with:

bash

curl -s -X POST http://localhost:9464/search \
  -H "Content-Type: application/json" \
  -d '{"query": "YOUR QUERY HERE", "limit": 10}' \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)
for r in data.get('hits', []):
    print(f\"{r['path']}:{r['start_line']}-{r['end_line']}  {r.get('snippet','')[:100]}\")
"

Example queries:

• "Python function signature extraction"
• "CLI argument parsing entry point"
• "database connection pool"
• "error handling file upload"
• "AuthService login method"

Getting a directory map#

Replace ls -la src/ or tree src/ with:

bash

curl -s "http://localhost:9464/map?path=src" \
  | python3 -c "import sys, json; print(json.dumps(json.load(sys.stdin), indent=2))"

Use path=. for the workspace root.

Output format#

Search results are returned as:

text

path/to/file.py:40-95  extract_signatures_python — extracts function signatures from...

Each result includes:

• path: file path relative to workspace root
• start_line / end_line: exact line range containing the relevant code
• snippet: short excerpt of the matching content

Always read the specific lines from the file to verify before acting on them.

Guardrails#

• SemanticFS is read-only — it never modifies files
• Only searches directories that have been indexed ( semanticfs index build)
• If results look wrong, re-run semanticfs index build to refresh
• Index automatically includes only source files (excludes node_modules, .venv, target/, .git, etc.)

Troubleshooting#

No results returned:

• Check the index was built: semanticfs --config ~/semanticfs.toml health
• Try a broader query (e.g. "authentication" instead of "JWT token refresh logic")

Connection refused:

• Start the server: semanticfs --config ~/semanticfs.toml serve mcp &

Stale results after code changes:

• Re-index: semanticfs --config ~/semanticfs.toml index build
• Or run incremental update: semanticfs --config ~/semanticfs.toml index update

Diagnose the full setup:

bash

semanticfs --config ~/semanticfs.toml doctor