← docgrity home

How it works

Last updated: 6 September 2026

The pipeline

1. Collect — repo markdown (**/*.md, capped at 200 files). node_modules, build output and git-ignored files always excluded.
2. Pair locally — candidate pairs via local TF-IDF cosine similarity. Deterministic, instant, free — no AI at this stage.
3. Assess — only the top pairs (25 default) hit the model via vscode.lm (your Copilot or a local model). Duplicate + contradiction share one call per pair; open-question checks pre-filter for signals first.
4. Validate — strict-JSON schema or rejected; every evidence excerpt verified verbatim against your files (hallucination guard).
5. Show — activity-bar view, Problems-panel squiggles on the exact evidence, an interactive dashboard, and a markdown report. Every finding records model, prompt version and confidence.
6. Act, with approval — right-click → Raise GitHub issue. A drafted title/body (evidence, next step, potential owner from git log) is shown in a modal; nothing posts until you click Create issue.

Modes & checks

• docgrity.mode: report-and-issue (default) or report-only — issue-raising hidden and blocked at command level. Set report-only globally, override per-workspace where you want to act.
• docgrity.checks.*: duplicates, contradictions and open questions are independent toggles — fewer checks, fewer model calls, faster scans.
• Results land in four places: the Docgrity activity-bar view, the Problems panel, the interactive dashboard (Open findings dashboard) and a shareable markdown report.
• Potential owners come from the last git author of each file — always labelled potential, never auto-assigned.

Choosing your model

Easiest: run Docgrity: Select AI model from the command palette. Manual: docgrity.model.vendor / docgrity.model.family.

Option	Setup	Privacy
GitHub Copilot (default)	Sign in — nothing to configure. Any model in Copilot's picker (Claude, GPT, Gemini) works.	Your Copilot subscription's terms
Local Ollama	ollama pull llama3.1, then Copilot Chat → Manage models → add it; select with Select AI model.	Nothing leaves your machine
Remote Ollama	cloudflared tunnel --url http://localhost:11434, point Manage models at the tunnel URL. Quick tunnels change URL on restart — use a named tunnel + Cloudflare Access for stability and safety.	Your own infra
Other extensions	Any extension registering vscode.lm models — set its vendor id.	Per provider

Outside the editor — CLI & Action

Copilot only exists inside VS Code, so the CLI/Action use direct providers: ollama (default, keyless, private) · anthropic / openai / gemini (BYO key: api_key: ${{ secrets.DOCGRITY_API_KEY }}) · github-models (retiring — on HTTP 410, switch provider). Summary: Copilot keyless in the editor · Ollama keyless everywhere · BYO key for hosted models in CI.

No-agent mode — no AI at all

Pure algorithms, fully offline. Extension: docgrity.engine: no-agent. CLI: docgrity scan --provider none. Action: provider: none.

Check	No-agent behaviour
Duplicates	Verbatim shared-block detection + TF-IDF. Confidence is measured (actual overlap); paraphrased duplication needs AI.
Open questions	Explicit markers (TODO, TBD, FIXME, ???, "open question"…) — deterministic, high confidence.
Contradictions	Require AI intelligence — skipped and clearly noted. Never guessed at heuristically.

Evidence stays verbatim, owners come from git history, findings are marked method: heuristic, and confidence is shown on every surface — squiggles, tree, reports, CLI output and issue bodies.

Model quality note: prompts demand strict JSON with verbatim evidence. Small local models (<8B) fail validation more often — failed responses are rejected safely: fewer findings, never corrupted ones. Recommended local minimum: llama3.1:8b.

Cost, security & troubleshooting

• Bounded cost — pair selection is local; caps (maxFiles/maxPairs) bound model calls; shared calls per pair; scans are cancellable with partial results kept.
• Untrusted input — doc content can't override agent instructions; all model output is schema-validated; evidence verified verbatim before recording.
• Tokens & git — GitHub tokens come from VS Code auth, used only for approved issue posts, never logged. Git commands are read-only, no shell.
• No telemetry, no servers. See the privacy policy.
• “No language model available” — sign in to Copilot or configure docgrity.model.*; no findings — lower docgrity.thresholds.*; logs — Output panel → Docgrity (never contains doc content or tokens).

← Back to home