raw-cli

raw is a local coding agent for models with limited context. Each agent selects ordered tools, skills and hooks, and can supply a system prompt. Raw ships eleven tools as editable plugins: read_file, write_file, bash, view_image, list_skills, load_skill, list_vars, read_var, todo, ask_user, and process. Todo, Ask, and Process are selected explicitly; they are not added to the starter tool selection. Tools, skills and hooks can also live in the user's config directory or beside a selected agent config. Selected MCP tools remain available. Standard Agent Client Protocol (ACP) lets an IDE or parent agent run sessions.

Install and run

Requires Node.js 22.13+ and Bash for the bash tool. Documentation: raw.tlelabs.com.

npm install -g @tlelabs/raw
raw config init

Run it once without installing with npx @tlelabs/raw --help. To install the latest commit from GitHub instead, use npm install -g github:lploc94/raw-cli; installing from a Git ref runs the prepare build, so it downloads build tooling and takes longer. Each GitHub release also attaches the packed tarball. To work from a checkout, run npm ci (which also builds) and npm install -g ..

config init creates ~/.config/raw/config.json (or $XDG_CONFIG_HOME/raw/config.json) once with setup-capable agent raw; edit the local model ID or add your hosted model. raw "query" uses the configured default_agent, which may name a different agent in an existing config. --config PATH selects another strict JSON config file.

raw --agent raw "Explain the tests in this repository"
raw --agent deepseek "Fix the failing tests"
raw                         # saved REPL with ❯ prompt on an interactive terminal
raw --continue "Follow up on that change"
raw sessions
raw sessions show SESSION_ID
raw --acp --stdio           # IDE/parent agent transport
raw dashboard              # local browser chat and setup
raw dashboard --port 0 --no-open

raw dashboard serves the bundled browser app locally. Create or continue sessions, inspect reasoning/tool activity and context usage, handle matching approvals, and manage agents, models, skills, tools, vars, MCP and packages. Setup and history work without a model connection. Browser preferences stay separate from Raw config; saved config/source changes apply to the next turn of the same session. See the dashboard guide for layout, setup and sharing workflows.

Tool calls run automatically in terminal, headless, dashboard and ACP modes, using your OS account's full permissions. cwd resolves relative paths; it is not a sandbox. An agent can set tools.rules to ask or deny specific tools or patterns. Unmatched tools run without a permission prompt; -y cannot bypass an explicit ask rule.

Models and agents

models holds exact upstream model IDs, API methods, endpoint/auth settings, context metadata and vision capability. An entry in agents selects one model and configures a run. Multiple agents may share a model.

{
  "default_agent": "raw",
  "models": {
    "local": {
      "provider": "ollama",
      "method": "openai-chat-completions",
      "model_id": "YOUR_INSTALLED_MODEL",
      "base_url": "http://127.0.0.1:11434/v1"
    },
    "flash": {
      "provider": "deepseek",
      "method": "openai-chat-completions",
      "model_id": "deepseek-flash",
      "base_url": "https://api.deepseek.com",
      "api_key_env": "DEEPSEEK_API_KEY",
      "context_window_tokens": 1048576
    }
  },
  "agents": {
    "raw": { "model": "local", "system_prompt": "You are a coding assistant. For Raw setup tasks, list selected skills and load only relevant instructions.", "tools": { "use": ["builtin/read_file", "builtin/write_file", "builtin/bash", "builtin/list_skills", "builtin/load_skill"] }, "skills": { "use": ["builtin/configure_raw", "builtin/create_skill", "builtin/create_tool", "builtin/create_hook", "builtin/create_agent", "builtin/add_mcp", "builtin/create_package"] } },
    "deepseek": {
      "model": "flash",
      "tools": { "use": ["builtin/read_file", "builtin/write_file", "builtin/bash"] },
      "request": { "thinking": "enabled", "reasoning_effort": "high", "max_output_tokens": 4096 },
      "compact": { "trigger_tokens": 800000, "keep_recent_turns": 2, "max_output_tokens": 16384 }
    }
  }
}

provider names the service; method selects its wire API (openai-chat-completions, openai-responses, anthropic-messages, or google-generate-content). model_id is sent upstream unchanged. Use api_key_env to read a selected credential from the environment or api_key for a literal value. raw config list reports model/access settings without printing credentials. No old flat-agent schema is accepted. See configuration, config design, and providers.

Tools, images and MCP

For a vision-capable model, set models.<alias>.vision to true and add builtin/view_image to tools.use, then ask raw "Explain screenshot.png"; the model can call view_image with the path. There is no image flag. A text-only model can instead call an external MCP vision-to-text server that returns a description. Search likewise comes from a selected MCP tool returning text.

MCP lives in the same config file. Only servers selected by the active agent are started, and only selected tools enter its model schema:

{
  "mcp": {
    "servers": {
      "search": { "transport": "stdio", "command": "YOUR_SEARCH_SERVER", "args": [] }
    }
  },
  "agents": {
    "research": { "model": "flash", "tools": { "use": ["builtin/read_file", "mcp/search/web_search"] } }
  }
}

Merge these fields into a complete config with models and default_agent. Local stdio and remote Streamable HTTP MCP transports are supported; see MCP. Agent tools.rules matches bundled, local, MCP (mcp/server/tool), and ACP (acp:name) identities with ordered allow, ask, and deny effects. A conditional ask can inspect commands[*].command, so only matching Bash rm calls prompt; see tools.

The npm package includes forkable tool examples and a complete project helper agent with raw.json, prompt.md, tools/, and skills/. Copy the agent directory anywhere, edit its model ID, endpoint, and credentials for the recipient, and run raw --config /path/to/project-helper/raw.json --agent project "task". Its agent/ references resolve beside the copied config. To fork a shipped tool globally, copy examples/tools/bash/ to ~/.config/raw/tools/my_bash/, change the manifest id and name, and select local/my_bash in an agent. See configuration, tools, and skills.

Agents and components can also travel as local .rawpkg archives. Export a configured agent with raw package export --agent NAME --name @owner/name --version 1.0.0 --out DIR, pack it with raw package pack DIR --out FILE.rawpkg, install it on another machine with raw package install FILE.rawpkg --as kit, then bind the recipient model using raw agent add NAME --from pkg/kit/agents/EXPORT --model MODEL_ALIAS. Direct agents can select installed tools and skills without adopting an entire package. Updates preserve the local binding and resume the same session; only effective runtime changes rotate Raw's generated cache key. See packages for inputs, exact dependencies, development links and rollback.

The installed package examples include a complete mixed agent and standalone tool/skill packages. They are editable source, not preinstalled agents; inspect and pack the one you need, then bind it to a recipient config.

Raw ships seven English setup skills for configuring Raw, creating skills, creating tools, creating hooks, composing agents, adding MCP servers, and packaging components for sharing. builtin/create_hook covers events, filters, scripts, selection and verification; agent hooks document the protocol. builtin/create_package guides export or manifest authoring, recipient inputs, validation, packing, installation checks and updates. The packaged skill authoring cheatsheet explains how to write descriptions, procedures, examples and verification criteria. Skill instructions guide the model; they do not enforce a fixed sequence or amount of work.

The three built-ins each accept an ordered batch of up to 16 entries: read_file({"files":[...]}), write_file({"operations":[...]}), and bash({"commands":[...]}). Reads can select full files or 1-based line ranges. A large full read returns complete leading lines with next_line for paging. Writes support overwrite, append, unique text replacement, and SHA-256 guarded line replacement. Bash continues after a nonzero exit and stops on timeout or abort. All batch rows share the configured model-facing maxOutputBytes limit; terminal previews separately show at most 2,000 characters and 10 lines. See tool contracts.

Shared tool UI and editing

Tool views use one block renderer in chat and the sidebar. builtin/ask_user gathers durable structured answers; builtin/process runs bounded background jobs across turns. The dashboard Commands section combines foreground Bash and background jobs, with paged output and policy-controlled Stop actions that remain available during a model turn.

write_file accepts either its exist