02 Getting Started

Getting Started

From clone to first verified fact in ~10 minutes (indexing time depends on corpus size).

---

Requirements

Item	Value	Notes
Python	3.13+	declared in requires-python; verified on 3.14. The venv module is mandatory (some app-bundled interpreters lack it)
PowerShell	7.6+ (pwsh, Core)	only for scripts/*.ps1; the Python path works anywhere
OS	Windows — verified; Linux/macOS — should work, not verified	the product was developed and measured on Windows
Privileges	none	everything installs into the user profile
Disk	~2.5 GB (venv + deps) · ~1 MB of index per 1–2 source files · +240 MB model · +5–6 GB optional Joern layer	the installer checks free space before starting
Network	PyPI at install; HuggingFace once for the embedding model	corporate TLS inspection? See below

⚠️ Windows: Microsoft Store Python stub. If python opens the Store instead of running, you have the App Execution Alias, not an interpreter. Install Python from python.org or disable the alias (Settings → Apps → Advanced app settings → App execution aliases). The installer detects and explains this case.

---

Install (Windows / PowerShell)

git clone https://github.com/paulmann/RAGRAF.git
cd RAGRAF
pwsh -NoLogo -NoProfile -File scripts/install.ps1

What happens: environment checks (pwsh, python, venv, disk) → venv in ~/.ragraf/venv → dependencies → launch verification → summary table. Every step ends with a check — the script does not «pretend to install». A full transcript lands in ~/.ragraf/logs/install-<ts>.log; attach it to any issue report.

Useful variants:

# install + prepare a corpus for your project (no model download)
pwsh -File scripts/install.ps1 -Project C:\work\myproject

# ...plus full indexing (downloads the ~240 MB embedding model)
pwsh -File scripts/install.ps1 -Project C:\work\myproject -Index

# indexing without vectors: no download; lexical (BM25) search works
pwsh -File scripts/install.ps1 -Project C:\work\myproject -Index -NoVectors

# corporate TLS inspection network
pwsh -File scripts/install.ps1 -WithTruststore

# slow network / VM: scale all timeouts
pwsh -File scripts/install.ps1 -TimeoutScale 3

# CI: machine-readable summary
pwsh -File scripts/install.ps1 -Project C:\ci\proj -Index -SummaryJson out\install.json

Exit codes: 0 success · 1 install error · 2 bad arguments · 3 unsuitable environment.

Install (Linux / macOS / any Python 3.13+)

git clone https://github.com/paulmann/RAGRAF.git
cd RAGRAF
python -m venv .venv
. .venv/bin/activate           # Windows: .venv\Scripts\Activate.ps1
pip install -e .               # or: pip install -r requirements.txt
ragraf --version

No-install path (wrapper adds src/ itself):

python tools/ragraf.py --version

---

Your first corpus

1. Prepare

ragraf ensure C:\work\myproject

ensure is the one-command entry: it finds an existing corpus, creates one for an unknown directory (inspecting contents to pick languages/excludes/thresholds), and rebuilds a stale index. Its status field says what happened: actual · reindexed · created · not_a_project · error.

A directory «not looking like a project» (no .git, no manifests) is refused as not_a_project — deliberately, so a home directory or a drive root never becomes a corpus.

2. Verify the environment

ragraf -p <config> selftest          # report on 11 components
ragraf -p <config> selftest --json   # machine-readable (used by the installer)

⚠️ selftest always exits 0 — it is a report, not a gate. Read the checks: python, tree_sitter, php_grammar, sqlite_vec, fastembed, tiktoken, fts5, vec0_loadable, embedding_model are required; joern, java are optional (absent → capability=degraded, slice unavailable).

3. Ask

ragraf -p <config> query search "reindex delay"
ragraf -p <config> query symbol --name corpus_hash
ragraf -p <config> query code --name corpus_hash
ragraf -p <config> query callers --name dedupe
ragraf -p <config> query impact --target Facade --depth 2

4. Check freshness after edits

ragraf -p <config> check             # compare checksum; reindex if changed
ragraf -p <config> drift --scan      # register differences WITHOUT touching the index
ragraf -p <config> status            # revision, coverage, ledger size

Flag order matters: global --project/-p and --json go before the subcommand (ragraf --json -p cfg query search …); the subcommand's own flags go after it. Exception: ensure has its own --json placed after it (ragraf ensure <dir> --json).

---

Attaching to an agent (MCP)

{
  "mcpServers": {
    "ragraf": {
      "command": "python",
      "args": [
        "/path/to/RAGRAF/tools/ragraf-mcp.py",
        "--project", "/path/to/RAGRAF/config/mycorpus.yaml",
        "--agent", "my-agent",
        "--agent-kind", "external"
      ]
    }
  }
}

--project is required. --agent/--agent-kind only separate call statistics (without them calls log as unknown). Full protocol details, the working regimen and the ready-to-paste AGENTS.md block: MCP Integration.

---

Optional: the Joern layer (slice, interprocedural calls)

Without it the product works and says so (capability=degraded). With it, slice unlocks and M2 recall was measured to rise 0.771 → 0.858.

# downloads JDK 21 (Adoptium) + Joern CLI (GitHub release), verifies SHA-256, unpacks, self-checks
pwsh -File scripts/install-joern.ps1 -Download

# or verify locally placed artifacts (no network)
pwsh -File scripts/install-joern.ps1

Requirements & gotchas (external php in PATH for PHP corpora, -J-Xmx form, memory): CPG & Joern Layer.

---

TLS inspection (corporate proxy)

Symptom: the model download dies with certificate verify failed.

pip install truststore          # or: install.ps1 -WithTruststore

Measured: without it — refusal; with it — 240 MB in 9.2 s. Not needed on home networks. The model cache directory is overridden by RAGRAF_MODEL_CACHE; read operations never download the model.

---

Where things live

Path	What
~/.ragraf/venv	the environment created by install.ps1
~/.ragraf/models	embedding model cache (RAGRAF_MODEL_CACHE overrides)
~/.ragraf/logs	installer transcripts
<project>/.ragraf/	the index — add to that project's .gitignore
<repo>/config/*.yaml	corpus configs (machine-local, git-ignored by design)
<repo>/.tools/	optional JDK + Joern (~5–6 GB, git-ignored)
catalog/catalog.json	the machine's development registry (git-ignored)

---

Smoke-test checklist (what «installed» means)

• ragraf --version prints ragraf 0.1.0
• ragraf ensure <some project dir> returns created or actual
• ragraf -p <cfg> selftest — all 9 required components OK
• ragraf -p <cfg> query search "<something>" returns hits with path:line
• python tests/test_lang_routing.py → 56 checks pass (portable suite)
• installer summary table: 0 errors

If a step fails → Troubleshooting.

---

Next: Architecture → · Operations Reference →