quickstart.md

Quickstart

Install

pip install sciogen

That gives you the full indexer, query engine, CLI, MCP server, and explore GUI. Semantic search runs on the built-in deterministic hashing embedder out of the box (keyword-level quality, zero extra downloads).

For real code-optimized semantic search, add the embeddings extra (larger, one model download):

pip install "sciogen[embeddings]"

sciogen not recognized after install?

pip puts the sciogen command in your Python installation's scripts folder, and on some setups that folder is not on PATH (most commonly Windows with the Microsoft Store Python, or pip install --user on Linux/macOS). pip prints a yellow warning about this during install, but it is easy to miss. Three fixes, any one of which works:

Option 1 — run it through Python (no setup needed):

python -m sciogen index .

Option 2 — add the scripts folder to PATH (one-time).

On Windows (PowerShell), find the folder and add it to your user PATH:

# 1. Print the folder pip installed the command into:
python -c "import sysconfig, os; print(sysconfig.get_path('scripts', os.name + '_user'))"

# 2. Add it to your user PATH (paste the folder from step 1 in place of <folder>):
[Environment]::SetEnvironmentVariable('Path', "$([Environment]::GetEnvironmentVariable('Path','User'));<folder>", 'User')

# 3. Open a NEW terminal — existing windows keep the old PATH.

On Linux/macOS, user installs land in ~/.local/bin:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc

Option 3 — install with pipx instead. pipx exists precisely for CLI tools: it isolates the install and manages PATH for you.

pipx install sciogen

Index a project

From the root of any codebase:

sciogen

Bare sciogen indexes the current directory. You'll see the banner, a live progress row per pipeline stage, and a completion summary:

✓ Done! 1,204 nodes · 3,456 edges · indexed in 4.2s
  Ready. Your codebase is now queryable.

The index lives in a .sciogen/ directory at the project root. Add it to your .gitignore (it is machine-specific and regenerable). sciogen index <path> does the same thing for a directory other than the cwd.

Re-run sciogen any time — it is incremental. Unchanged files are skipped via a stat + SHA256 differ, so a no-op re-index is effectively instant and a single-file change takes under a second.

Query it

sciogen search "password hashing logic"        # semantic search
sciogen search "auth flow" --mode hybrid        # + graph expansion
sciogen callers AuthService.login               # who calls this
sciogen callers AuthService.login --depth 3     # up to 3 hops
sciogen impact UserModel.find_by_email          # full blast radius
sciogen deps src/auth/service.py                # imports + transitive deps
sciogen symbol AuthService.login                # typed node info + relations

Every result carries an exact file:line location and — for call/impact queries — a confidence score and hop count. Filter weak edges with --min-confidence 0.8.

Explore it visually

sciogen explore

Opens the knowledge graph in your browser from a single self-contained HTML file. Starts collapsed to file nodes; click a file to reveal its classes and functions, click a function to reveal its call edges. Search jumps to any symbol; the layout toggle switches between force-directed (clusters) and hierarchical (call chains). It's a snapshot — re-run sciogen then sciogen explore after code changes.

Wire it into an agent (MCP)

sciogen mcp .

Runs the Model Context Protocol server over stdio, exposing all eight query tools. See mcp.md for client configuration.

Use it from Python

import sciogen

graph = sciogen.open(".")
graph.index()
print(graph.get_callers("AuthService.login"))

See api.md for the full API.

Configuration

Env var	Effect
SCIOGEN_EMBEDDER	nomic (default) or hash (force the deterministic embedder)
SCIOGEN_WORKERS	Parse worker processes; 0/unset = auto, 1 = serial
SCIOGEN_DATA_DIR	Override the index location (default <project>/.sciogen)