Devour/README.md

Devour

Feed your AI real docs so it stops repeating the same mistakes.

Code quality and review workflows are powered by peteromallet/desloppify, integrated behind Devour commands.

Code Health Scorecard

Why Devour exists

I built Devour because AI tools kept drifting away from official docs, then repeating wrong patterns in later prompts.

Devour fixes that loop with a local-first workflow:

1. scrape official docs,
2. keep them in your project,
3. search and ask against that local corpus,
4. sync updates when sources change.

What works today

• devour init creates a complete local workspace
• devour scrape supports URL, language-specific docs, local files, GitHub repos, OpenAPI specs, and --sources
• devour get supports language/framework shortcuts (now including Next.js, Svelte, Angular, Remix, SolidJS, Express)
• devour query is now functional (local lexical index)
• devour ask is hybrid local-first with live fallback when local relevance is weak
• devour sync updates configured sources and reindexes
• devour status reports real local health/statistics
• devour push <path> imports local docs into the workspace and reindexes
• devour serve local mode runs JSON-RPC over stdio (devour_query, devour_status, devour_scrape, devour_ask, devour_sync)
• devour auto routes natural-language intent to the right command
• devour verify smoke runs opt-in live checks and writes reports

Experimental

• devour serve --remote is available as an experimental HTTP RPC mode
• remote push workflows are intentionally not enabled as stable behavior yet

Quick start

1) Build

go mod download
go build -o devour ./cmd/devour

2) Initialize

./devour init

3) Get docs fast

./devour get go net/http --format markdown
./devour get nextjs routing
./devour get express middleware

4) Search locally

./devour query "json unmarshal"

5) Ask a docs-grounded question

./devour ask --lang go "how to parse json" --format text

6) Let Devour route intent automatically

./devour auto "how to use useEffect in react"
./devour auto "https://pkg.go.dev/net/http"

Core commands

Command	Purpose
devour init [path]	Create config + local storage directories
devour get <language> <keyword>	Shortcut fetch from curated official docs
devour scrape <source>	Scrape one source directly
devour scrape --sources sources.yaml	Scrape multiple configured sources
devour query <text>	Search local indexed docs
devour ask --lang <lang> <question>	Structured answer using local-first + live fallback
devour sync	Sync configured sources and rebuild index
devour status	Show docs/index/source health
devour push <path>	Import local docs into workspace
devour serve	Start local stdio JSON-RPC server
devour auto "<intent>"	Auto-route intent to command
devour verify smoke	Live smoke verification report
devour quality ...	Thin passthrough to desloppify
devour review ...	Holistic subjective review workflow via desloppify review
devour scorecard	Generate desloppify badge output via scan

Quality Prerequisite

Install desloppify before running devour quality / devour review / devour scorecard:

pip install --upgrade "desloppify[full]"

AI Setup Prompt (Copy/Paste)

Install or update desloppify, then scan this codebase for code quality issues
(dead code, duplication, complexity, smells). It tracks findings persistently
across sessions and reports a health score.

Requires Python 3.11+. Install from PyPI:
pip install --upgrade desloppify
# Recommended for deepest coverage (tree-sitter + Python security adapter):
pip install --upgrade "desloppify[full]"
desloppify update-skill codex    # pick yours: claude, cursor, codex, copilot, windsurf, gemini

Use Devour wrappers (delegates to desloppify):
devour quality scan --path .
devour quality status
devour quality next

Direct equivalent commands:
desloppify scan --path .
desloppify status
desloppify next

--path is the directory to scan (use "." for the whole project, or "src/" etc).
Language is auto-detected. To override: desloppify --lang python scan --path .
(note: --lang goes BEFORE the subcommand)

Fix what it finds, then:
desloppify resolve fixed <id> --note "what changed" --attest "I have actually [DESCRIBE THE CONCRETE CHANGE YOU MADE] and I am not gaming the score by resolving without fixing."

For false positives:
desloppify resolve wontfix <id> --note "reason" --attest "I have actually verified this is intentional/false-positive and I am not gaming the score by resolving without fixing."

If subjective scores feel stale or inflated:
desloppify scan --path . --reset-subjective

Because state persists, run regularly (for example before each push).
If anything seems wrong/confusing in desloppify itself, capture a repro and ask
whether to log an upstream issue.

If you need to debug desloppify internals:
git clone https://github.com/peteromallet/desloppify.git /tmp/desloppify

Supported get / ask languages and frameworks

• Go (go, golang)
• Rust (rust)
• Python (python, py)
• Java (java)
• Spring (spring)
• TypeScript (typescript, ts)
• React (react)
• Vue (vue)
• Nuxt (nuxt)
• Docker (docker)
• Cloudflare (cloudflare, cf)
• Astro (astro)
• C# (csharp, cs)
• Kotlin (kotlin, kt)
• PHP (php)
• Ruby (ruby, rb)
• Elixir (elixir, ex)
• Next.js (next, nextjs)
• Svelte (svelte)
• Angular (angular, ng)
• Remix (remix)
• Solid (solid, solidjs) via github.com/solidjs/solid-docs
• Express (express, expressjs)

Run devour languages for examples, or devour languages --format json for automation.

Config

Devour reads devour.yaml (or --config).

New additive sections:

• indexing: local lexical index defaults
• verification: live smoke timeout defaults

Starter config: devour.example.yaml.

Real-world verification

Run live smoke checks (opt-in):

./devour verify smoke

Reports are saved to devour_data/verify/smoke-<timestamp>.json.

JSON-RPC local server

devour serve (local mode) accepts JSON-RPC 2.0 methods:

• devour_query
• devour_status
• devour_scrape
• devour_ask
• devour_sync

Development

Test

go test ./...

Typical integration loop

./devour init
./devour scrape https://pkg.go.dev/net/http --type godocs
./devour query "http client"
./devour ask --lang go "timeout example"
./devour sync
./devour status

License

MIT (LICENSE).