// We're here

Support &
Community.

Get help with Proverbs. Report a bug, ask a question, or join the community of developers building offline-first with local models.

"Where there is no guidance, a people falls, but in an abundance of counselors there is safety." — Proverbs 11:14

// Get in touch

Contact

Two channels. Pick what fits your issue. GitHub Issues is preferred for bugs and feature requests — it keeps a public record that helps other users.

📧
Email Support Human reply
For license questions, billing, security disclosures, or anything that should stay private. Response within 48 hours on business days (Mon–Fri, EST).
stizzyraxx@gmail.com
🐛
GitHub Issues Public
For bug reports, feature requests, and documentation improvements. The preferred channel for anything technical — your issue helps the whole community.
Open an Issue →
💬
GitHub Discussions
Questions, ideas, show-and-tell, and general conversation about Proverbs, local coding models, and offline-first development. The community reads and replies here.
Join Discussion →

// Common issues

Frequently Asked Questions

Terminal-style answers to the most common questions about Proverbs.

proverbs — faq.txt
# Most common questions and their answers

Q: Does Proverbs send my code to the internet?
A: No. When using Ollama (the default), every token is generated on your machine. Nothing leaves. If you enable /fallback and configure a cloud API key, only prompts you send during that fallback session go to that provider. The default is always local-only.

Q: Is Proverbs free?
A: Yes. The core tool is free and open-source. You pay for the hardware it runs on. Cloud fallback (optional) uses your own API key billed directly by the provider. There is no Proverbs subscription.

Q: Can I use it on Windows?
A: Yes. Windows 10+ with PowerShell 5.1+. Install Ollama for Windows from ollama.com, then run the install.ps1 script. All features work. WSL2 also works with the Linux installer.

Q: Which model should I start with?
A: qwen2.5-coder:7b is the default and recommended starting point — 4.7 GB, runs on 8 GB RAM, fast, and accurate for most coding tasks. See the Help page for the full model comparison table.

Q: How do I add my own tools / extend Proverbs?
A: Drop a CommonJS .js file in ~/.proverbs/plugins/. Export a tools array following the plugin schema (see the GitHub wiki). The model can call your tools in the next session automatically. Run /plugins to verify loading.

Q: I made a mistake and Proverbs wrote the wrong file. Help!
A: Type /undo. Every file Proverbs touches is backed up in ~/.proverbs/backups/ before the write. /undo restores the most recent backup. You can also manually copy from ~/.proverbs/backups/<filename>.bak.

Q: Does it work without git?
A: Yes. Git integration (/gitlog, /gitdiff, /commit) is optional. All file read/write, RAG, scanning, and smart coding features work without a git repo. The /scan command detects whether git is available and adjusts accordingly.
Proverbs is slow. How do I speed it up? +
Speed depends on the model and hardware. To improve it: (1) Use a smaller model — qwen2.5-coder:7b generates ~20 tokens/sec on an M1 Mac vs ~8 for the 14B. (2) Reduce context — run /compress to summarize history and free up window space. (3) Enable GPU offload in Ollama settings. (4) Close other GPU-heavy applications while Proverbs is running.
Can Proverbs work with my existing Claude Code CLAUDE.md rules? +
Yes. Create a .script file in your project root and paste in the relevant content from your CLAUDE.md. Proverbs auto-loads .script on startup and injects it into every prompt. You can also run /script to create or edit it from inside Proverbs.
How do I update Proverbs to the latest version? +
Run npm install -g proverbs-ai@latest. This replaces the globally installed version. Your config, sessions, knowledge base, and backups in ~/.proverbs/ are not affected by updates.
Does semantic search (/semrag) work without internet? +
Yes. Proverbs uses a local embedding model (nomic-embed-text via Ollama) to generate vectors. Run ollama pull nomic-embed-text once, then /index to build the project index. All vector operations run entirely offline after that.
Can I run Proverbs on a server / headless machine? +
Yes. Proverbs is a pure CLI tool. Install Ollama on the server, pull a model, then install Proverbs. SSH in and run proverbs in your project directory as normal. Works in tmux, screen, or any persistent terminal session.
My company blocks external package registries. Can I install offline? +
Yes. Download the Proverbs source from GitHub and install with npm install -g . from the project directory. For Ollama, download the binary directly from the GitHub releases page on a networked machine and transfer it. All runtime operations are offline.

// Hardware

System Requirements

Minimum and recommended specs per platform. The 7B model is the baseline — larger models require more RAM.

🍎
macOS
  • macOS 12 Monterey or later
  • Node.js 18 or later
  • 8 GB RAM minimum (16 GB recommended)
  • 10 GB free disk (model + index)
  • Apple Silicon (M1+) for best speed
  • Recommended: M1/M2 Mac, 16 GB RAM
🪟
Windows
  • Windows 10 (build 19041) or later
  • PowerShell 5.1 or later
  • Node.js 18 or later
  • 8 GB RAM minimum (16 GB recommended)
  • NVIDIA GPU (6 GB+ VRAM) for acceleration
  • Recommended: RTX 3060+ or 32 GB RAM
🐧
Linux
  • Ubuntu 20.04 / Debian 11 or later
  • Node.js 18 or later
  • 8 GB RAM minimum
  • NVIDIA GPU with CUDA 11.8+ (optional)
  • AMD GPU with ROCm 5.4+ (optional)
  • Recommended: 16 GB RAM, CUDA GPU
☁️
Cloud / VPS
  • Any Linux distribution
  • CPU-only works but is slower
  • 16 GB RAM for 7B CPU inference
  • A10G / L4 GPU for 14B+ models
  • SSH or web terminal access
  • Recommended: GPU instance for 7B+ models

// Reporting

How to Report a Bug

Good bug reports get fixed fast. Follow these steps to give us everything needed to reproduce and fix the issue on the first try.

1
Check existing issues first. Search GitHub Issues for your error message. If it exists, add a comment with your system info rather than opening a duplicate.
2
Collect system info. Run proverbs --version, ollama --version, node --version, and note your OS and hardware (CPU/GPU/RAM).
3
Reproduce with minimal steps. Write the shortest sequence of commands that triggers the bug. Strip everything unrelated. Paste the exact terminal output.
4
Describe expected vs actual behavior. What did you expect to happen? What actually happened? Include the exact error message, including any stack trace.
5
Open the issue on GitHub. Use the Bug Report template. Link to any relevant code or config (never paste API keys or secrets). If the bug involves file writes, show the diff with /diff.
bug-report-template.txt
## Bug Report

**Environment:**
- Proverbs version: X.X.X
- OS: macOS 14.4 / Ubuntu 22.04 / Win 11
- Node.js: 20.x
- Ollama: 0.X.X
- Model: qwen2.5-coder:7b
- RAM: 16 GB / GPU: none / M2

**Steps to reproduce:**
1. cd ~/any-project
2. proverbs
3. /scan
4. [exact command that causes bug]

**Expected behavior:**
[What should happen]

**Actual behavior:**
[What actually happens + error output]

**Additional context:**
[Screenshots, diffs, config snippets]
"Iron sharpens iron, and one man sharpens another." — Proverbs 27:17

// Together

Community

Proverbs is built in public. Join the community of developers building offline-first with local models — contribute code, share plugins, or just hang out.

⭐
GitHub Repo
Read the source, fork it, open PRs. All core development happens here. Give it a star if Proverbs saved you a cloud bill.
View on GitHub
💬
Discussions
Ask questions, share model recommendations, post plugins you built, and show off what you coded offline. Open to all.
Join Discussions
🧩
Plugin Gallery
Browse community-built plugins — database tools, deployment helpers, specialized language toolchains, and more.
Browse Plugins
🤝
Contributing
Bug fixes, new slash commands, documentation, plugin examples — all welcome. Read CONTRIBUTING.md before opening a PR.
How to Contribute