// Reference
Everything you need to get started, every slash command explained, recommended models, and solutions to common problems.
// Jump to
// First run
After installing Proverbs, open any project folder in your terminal and run proverbs.
Here is what happens and what to do next.
cd into your project folder. Proverbs uses the current
working directory as the project root for all file operations.
cd ~/my-project && proverbs
/scan on first launch. Proverbs will detect your stack, frameworks,
import aliases, lint config, and git history. This context is injected into every
subsequent prompt automatically.
/model <name>. Use /models to list all available
model backends.
.script file in your project root with your conventions, rules,
and architecture notes. Proverbs auto-loads it on startup and injects it into every
prompt. Use /script to view or edit it from inside Proverbs.
/help at any time to see all commands.
// Commands
Control how the model thinks, reasons, and checks its own work.
| /think | Enable extended reasoning mode. The model works through the problem step-by-step before responding. Slower but more accurate for complex tasks. |
| /cot | Chain-of-thought prompting. Forces the model to show its reasoning inline. Useful for debugging logic errors or understanding why a suggestion was made. |
| /critique | After generating a response, have the model critique its own output for bugs, edge cases, and improvements. Then apply fixes automatically. |
| /attempts [n] | Set number of self-correction attempts (default: 2). The model regenerates and improves its answer up to n times. Higher = better quality, slower response. |
| /plan | Generate a change plan before executing. Lists every file to be modified, the reason, and the approach. Confirm before Proverbs writes anything. |
| /ctx [n] | Manually set the context window size in tokens. Default is auto-detected from the model. Reduce to speed up responses; increase for large codebases. |
| /compress | Summarize and compress the current conversation context. Frees up token space when approaching the context window limit without starting a new session. |
| /memory | View or edit persistent memory. Facts stored here are injected into every session automatically — useful for project-wide rules, your name, team standards. |
| /tokens | Show current token usage for the active conversation. Displays prompt tokens, completion tokens, and remaining context window space. |
| /truncate [n] | Truncate conversation history to the last n messages. Keeps the most recent context while clearing older messages to free context window space. |
| /full | Show the full context window — all messages in the current conversation, including system prompt, injected file context, and all turns. |
| /context | Show what project context, .script rules, memory, and injected files are currently in the model's context window. |
| /preload [files] | Pre-load specific files into the context window at session start. Useful for large core files (e.g. schema.prisma, types.ts) that are referenced constantly. |
| /highlight [file] | Re-inject a file into context and flag it as the primary focus. The model treats this file as the current subject for all subsequent messages. |
| /validate | Run a validation pass on the last generated code. Checks for syntax errors, type mismatches (if TypeScript), and obvious logic bugs without running tests. |
| /ml [task] | the training pipeline task mode. Optimized prompting for training scripts, model evaluation, data pipelines, and tensor operations. |
Scan and understand your codebase. These commands build the context Proverbs uses to generate accurate, project-aware responses.
| /scan | Auto-detect project stack, frameworks, package.json / pyproject.toml, import aliases, lint config, and recent git history. Results injected into every subsequent prompt. |
| /script | View or edit the project's .script file — your persistent coding rules, architecture notes, and conventions. Loaded automatically on every session start. |
| /conventions | Extract and display coding conventions detected from your existing code — naming patterns, file structure, comment style, and import ordering. |
| /deps [file] | List all dependencies of a specific file. Shows what it imports and what imports it. Essential before refactoring shared utilities. |
| /depgraph | Build and display the full project dependency graph. Shows all import relationships. Highlights circular dependencies and orphan files. |
| /index | Index the entire project for semantic search. Builds an embedding vector store of all code files. Required before using /semrag or /rag. |
| /rag [query] | Keyword-based retrieval-augmented generation. Searches your indexed codebase and injects the most relevant files into the next prompt. |
| /semrag [query] | Semantic (vector) RAG. Finds code by meaning, not just keywords. "Find all authentication logic" returns relevant files even if they don't contain the word "auth". |
| /embed [file] | Generate and store embeddings for a specific file or directory. Use after adding new files to keep the semantic index current. |
| /search [query] | Text search across the codebase with ripgrep-style pattern matching. Supports regex. Results are formatted and injected into context. |
| /knowledge [topic] | Query the project knowledge base — accumulated facts from previous sessions, scan results, and manually stored notes about this codebase. |
| /recommend | Get auto-generated recommendations for the current codebase — potential refactors, missing tests, security improvements, and performance issues. |
| /planner | Open the task planner. Break a large feature into atomic steps, assign files to each step, and execute them in order with full context preserved. |
| /project | Display a summary of the current project — detected stack, file counts, last scan date, active model, and .script file status. |
| /test | Run the project's test suite (jest, vitest, or pytest auto-detected). Feed test failures back to the model for automatic fix-and-retry. |
Commands for working with files, diffs, context, and the clipboard.
| /diff [file] | Show a unified diff of the last change made to a file by Proverbs, or git diff if no Proverbs edit exists. Color-coded additions and deletions. |
| /undo [file] | Restore a file to its state before the last Proverbs edit. Every write is auto-backed-up. Specify a file or undo the most recent change with no argument. |
| /paste | Paste clipboard content directly into the conversation. Useful for pasting error messages, stack traces, or code snippets without file access. |
| /copy | Copy the last Proverbs response or a specified file's content to the system clipboard. |
| /fetch [url] | Fetch a URL and inject the content into context. Supports web pages, JSON APIs, and raw file URLs. Useful for referencing documentation or API specs. |
| /docs [query] | Search official documentation for a library or framework. Fetches and summarizes relevant docs pages and injects examples into context. |
| /image [path] | Load an image file into context (requires a multimodal model). Useful for describing UI screenshots, diagrams, or design mockups to Proverbs. |
| /screenshot | Capture the current terminal or a specified window and load it into context. Requires a multimodal model. Useful for debugging visual UI issues. |
| /ui [desc] | Generate UI component code from a plain-English description. Proverbs writes the component, adds types, and matches your existing style conventions. |
| /voice | Toggle voice input mode. Speak your prompt instead of typing. Requires a local whisper.cpp installation or a compatible STT model. |
Save, restore, and manage your conversations across terminal sessions.
| /save [name] | Save the current conversation to disk with an optional name. Saved sessions include full message history, model, CWD, and injected context. |
| /sessions | List all saved sessions for the current project. Shows session name, date, message count, and the model used. |
| /resume [name] | Resume a saved session. Restores full conversation history. You pick up exactly where you left off, with full context intact. |
| /clear | Clear the current conversation history and start a fresh context. Does not delete saved sessions. Useful when switching tasks mid-session. |
| /exit | Exit Proverbs. Prompts to save the current session if unsaved changes exist. |
| /help | Display the in-terminal help reference — all slash commands with short descriptions. Equivalent to this page, formatted for the terminal. |
| /admin | Open the admin panel — system diagnostics, plugin status, index health, model cache size, session storage usage, and config overview. |
| /watch [file] | Watch a file for changes and automatically re-inject it into context when it changes on disk. Useful when editing a file externally while talking to Proverbs. |
| /plugins | List installed plugins and their exposed tools. Plugins live in ~/.proverbs/plugins/. Drop any .js file there to add custom tools the model can call. |
Git-aware commands for committing, reviewing history, and understanding diffs in context.
| /gitlog [n] | Show the last n commits (default 20) with author, date, message, and changed files. Injected into context so the model understands recent history. |
| /gitdiff [ref] | Show the git diff from a branch, commit, or HEAD. Inject into context so the model can review or explain changes. Defaults to unstaged changes. |
| /commit [msg] | Stage all modified files and commit with the provided message. If no message is given, the model generates a concise commit message from the diff. |
| /autocommit | Enable automatic commits after every successful file write. Each commit includes an auto-generated message describing the change. Disable with /autocommit off. |
Settings, appearance, and output formatting controls.
| /config [key] [val] | Read or write any config value. E.g. /config theme dark, /config stream true. Run /config with no args to see all current settings. |
| /cwd [path] | Change the working directory without restarting. All subsequent file operations use the new path. Run with no argument to display the current CWD. |
| /highlight [on|off] | Toggle syntax highlighting for code blocks in terminal output. On by default when the terminal supports colors. Disable for plain-text piping. |
| /finetune | Collect conversation examples, format as training data, and run the Proverbs training pipeline. |
Switch, route, and manage the models Proverbs uses for inference.
| /model [name] | Switch the active model. Set PROVERBS_MODEL_PATH to point to a .pt checkpoint. |
| /models | List available model backends and the currently active one. |
| /route [backend] | Set the inference backend: proverbs (default), gguf, lmstudio, openai, or claude. Each backend has independent model config. Use /route to switch without restarting. |
| /fallback [on|off] | Enable or disable cloud fallback routing. When on, tasks that exceed local model capabilities are automatically routed to the configured cloud API. Disabled by default. |
| /context [n] | Set the active model's context window size. Overrides the model default. Useful when a model supports larger context than Ollama reports. |
// What to run
These are the supported model backends for Proverbs. Start the inference server with
~/.proverbs/venv/bin/python -m inference.server.
| Model | Hardware | Details | Strength | Best For |
|---|---|---|---|---|
| proverbs-local | Your Mac | 12M params trained on your sessions | Recommended | Best for your specific codebase |
| proverbs-colab | Colab GPU | 58M params trained on code corpus | Powerful | Best general coding assistant |
| Any GGUF model | Any | Set PROVERBS_GGUF_PATH | Flexible | Instant fallback, no training needed |
// Fixes
Common errors and how to resolve them.
~/.proverbs/venv/bin/python -m inference.server~/.proverbs/venv/bin/python -m inference.server before launching the CLI./compress to summarize history, or /truncate 10 to keep only the last 10 messages./embed to update the semantic index. Otherwise /semrag and /rag won't find the new files./plan first. Review the plan and confirm. This prevents unintended edits./undo to restore the previous version immediately.| Error | Solution |
| Error: connect ECONNREFUSED 127.0.0.1:11434 | Proverbs server is not running. Start it with: ~/.proverbs/venv/bin/python -m inference.server |
| Error: model not found | Model not found. Set PROVERBS_MODEL_PATH to your checkpoint path, or start with the GGUF fallback. |
| Response truncated mid-sentence | Context window exceeded. Run /compress to summarize history, or reduce injected files. Use /ctx to check current window size. |
| command not found: proverbs | npm global bin is not in PATH. Run npm install -g proverbs-ai again, then add $(npm bin -g) to your shell PATH. Restart terminal. |
| /semrag returns no results | The project has not been indexed. Run /index to build the full vector index, or /embed for a specific directory. |
| Slow responses on first prompt | Model cold-start. Ollama loads the model into RAM on first inference. Subsequent prompts are fast. The 7B model loads in ~2-5s on 16 GB RAM. |
| File write permission denied | Proverbs cannot write to the project directory. Check file permissions with ls -la and ensure your user owns the project folder. Run chmod -R u+w . to fix. |
| Plugin not loading | Plugin syntax error or wrong location. Plugins must be valid CommonJS .js files in ~/.proverbs/plugins/. Run /plugins to see error details. |
| Cloud fallback API key error | No API key configured for the fallback provider. Run /config fallback.apiKey YOUR_KEY. Keys are stored locally in ~/.proverbs/config.json. |