FAQ
About Raw
Section titled “About Raw”Is Raw a coding agent or a framework?
Section titled “Is Raw a coding agent or a framework?”Both. Out of the box, raw config init creates a coding agent that reads, edits and runs code. Underneath, Raw is a harness: the agent loop, context compaction, saved sessions, approvals, a terminal REPL, a local dashboard and the Agent Client Protocol. The tools, skills, hooks, prompts and policies are files you can change, so you can turn it into a different agent without writing that machinery yourself.
What can I build with it?
Section titled “What can I build with it?”Anything that is an agent working with tools in a loop. Common starting points are a coding agent that follows your team’s conventions, an operations agent limited to approved commands, and an internal assistant that reaches your systems through MCP without a shell. See Design an effective agent for how to shape one.
Is Raw free to use at work?
Section titled “Is Raw free to use at work?”Yes. Raw is released under the MIT license, which allows commercial use and modification.
Does Raw collect telemetry?
Section titled “Does Raw collect telemetry?”No. Raw connects to the model endpoints and MCP servers that you configure, and the dashboard is served from your own machine.
Models
Section titled “Models”Which models can I use?
Section titled “Which models can I use?”Any model reachable through one of four wire methods: OpenAI-compatible Chat Completions, OpenAI Responses, Anthropic Messages and Google Generate Content. That covers OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, Ollama, llama.cpp and other compatible servers. See Models and agents.
Does Raw work with small local models?
Section titled “Does Raw work with small local models?”Yes, and it was built with them in mind. Each agent sends only the tools it selects, skills load on demand, and long sessions are compacted automatically once you declare the model’s context window. A small model still has limits: keep its agent lean, as described in Design an effective agent.
Can different agents use different models?
Section titled “Can different agents use different models?”Yes. Each agent names one model. You can run a local model for routine tasks and a hosted model for harder ones, each with its own tools and prompt.
Customizing
Section titled “Customizing”Should my system prompt be short?
Section titled “Should my system prompt be short?”Short enough to leave room for the work, long enough that the model does not have to guess. The prompt is sent on every step, so on a small context window every extra token is paid many times. But a prompt that leaves out your conventions or your definition of done costs more in wrong guesses and retries. Put occasional procedures in skills and enforce safety with rules. Design an effective agent explains the trade-off with numbers.
How do I change a built-in tool?
Section titled “How do I change a built-in tool?”Open the tool in the dashboard Library and choose Fork to local, or copy it from the examples. The copy is yours to edit, including its description and schema. Select the copy in place of the built-in. See Tools.
How do I add a tool of my own?
Section titled “How do I add a tool of my own?”Write a folder with a tool.json manifest and an index.mjs entry, then select it on the agent. You can also connect an MCP server and select its tools. See Tools and MCP.
My model keeps calling a tool wrong. What should I change?
Section titled “My model keeps calling a tool wrong. What should I change?”Simplify the tool’s arguments before you add instructions. Weaker models make more mistakes as a schema grows: nested objects, arrays of objects, many required fields and fields of several types are the usual causes. Prefer one action per call with flat fields, familiar names such as path or command, and one complete example in the description. See Keep tool parameters simple.
Why does my agent not use its skills?
Section titled “Why does my agent not use its skills?”An agent that selects skills must also select builtin/list_skills and builtin/load_skill. The model then decides from each skill’s description whether to load it, so the description should say when the skill applies. See Skills.
Do I have to restart a session after changing an agent?
Section titled “Do I have to restart a session after changing an agent?”No. Changes to an agent, a tool or a skill apply from the next turn, including in a session that is already open.
Sharing
Section titled “Sharing”How do I share my agent with my team?
Section titled “How do I share my agent with my team?”Export it as a .rawpkg package with its tools and skills. By default, export turns your variable values and paths into inputs that each recipient fills in, and your session history is never copied. See Packages.
Can I use Raw from my editor?
Section titled “Can I use Raw from my editor?”Yes, from any editor or parent agent that speaks the Agent Client Protocol. Run raw --acp --stdio. See ACP.
Can I run Raw in scripts?
Section titled “Can I run Raw in scripts?”Yes. raw "task" runs one task and exits. Redirected output stays plain, and the exit code tells a script whether the task completed. See the CLI reference.
Safety and data
Section titled “Safety and data”Is Raw a sandbox?
Section titled “Is Raw a sandbox?”No. Tools run with your operating system account’s permissions, and the working directory is not a boundary. Use tool rules to ask before or deny specific calls, and run untrusted work inside a container or a separate account. See Permissions.
Where are my sessions and settings stored?
Section titled “Where are my sessions and settings stored?”The config is ~/.config/raw/config.json, or under $XDG_CONFIG_HOME when it is set. Sessions are kept in a private database under ~/.local/state/raw/, or under $XDG_STATE_HOME. On Windows, ~ is your user folder, so these are %USERPROFILE%\.config\raw\ and %USERPROFILE%\.local\state\raw\. Sessions are removed after 30 days by default. See Sessions.
Which operating systems are supported?
Section titled “Which operating systems are supported?”Raw runs on macOS, Linux and Windows 10/11, and every change is tested on all three. It needs Node.js 22.13 or later. On Windows it runs natively, without WSL: install Git for Windows for the bash tool, or use the powershell tool, which raw config init selects when Git Bash is missing. Managed background processes work on all three systems. See Install Raw.