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": 512 }
    }
  }
}

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 existing operations array or a strict multi-file patch. Patch preflight stages all files before mutation; later I/O failures report partial completion and stop subsequent changes. Files changed records successful tool writes, including completed rows in an interrupted call. It does not track Git state or shell edits. See tools, processes, and the verification evidence.

Mermaid fences and tool diagram blocks share a lazy renderer in chat and the sidebar, with source/copy controls and readable failure fallback. See diagrams and the local diagram example.

Conversation, compact and cache

The REPL saves turns across process restarts. Use raw --continue for the latest session in this workspace, raw --resume ID for a specific saved cwd, and raw sessions show ID --before CURSOR to page older visible history. Host commands are /compact, /clear, /stats, and /exit; /clear starts a new saved session. Without compact.trigger_tokens, compaction is manual. With it, Raw estimates the complete next request, emits visible compact progress, and sends bounded summary requests to the selected model when the threshold is reached. It excludes image base64 from summary prompts and retains a stable main cache key until a deliberate compact boundary. Cache reuse depends on the upstream service; a cache hit is only claimed when its usage counters report one. See CLI sessions and context and cache.

--system-prompt or RAW_SYSTEM_PROMPT overrides an agent's system_prompt or system_prompt_file, then Raw's default. --max-steps defaults to 10000 inference requests, --max-output-bytes to 8192 text bytes per tool result, and --request-timeout-ms to 120000. Use raw --help for flags and exit codes.

Terminal appearance

Raw highlights Markdown code fences and source previews in an interactive terminal, shows tool progress, and ends a one-shot run with context, reported usage, and a copyable resume command. Set root ui in config.json or override it per run with --display compact|normal|verbose, --reasoning hidden|summary|full, --color auto|always|never, --icons auto|unicode|ascii, and --theme terminal|dark|light. For example, raw --theme dark --display verbose "Inspect this module" shows a longer bounded tool preview. Redirected answer text keeps its original bytes and terminal status stays on stderr. Terminal output describes palette roles, coverage rules, fallbacks, and a no-network preview gallery.

ACP and development

raw --acp --stdio serves standard Agent Client Protocol v1. raw --acp --ws --host 127.0.0.1 --port 8765 serves a local WebSocket endpoint. Parent agents can import createAcpClient and register temporary reverse tools; ACP and the parent example document the flow.

npx playwright install chromium firefox webkit
npm run check
npm run test:overhead
npm run test:package
npm run test:web
npm exec --yes --package=node@22 -- node scripts/verify-runtime.mjs
npm exec --yes --package=node@24 -- node scripts/verify-runtime.mjs

Tests use local provider/MCP/ACP fixtures. Verification records gates and limits. Source modules live in bin/, src/config.ts, src/agent.ts, src/compact.ts, src/llm/, src/tools/, and src/acp/.

Runtime variables

Agents can select named read-only values from config, environment, files or executable providers. Use raw vars list and raw vars get now without invoking a model. The starter raw agent includes current UTC time. Models can use list_vars/read_var or pass commands[].env_refs to Bash; use-only values need not be returned to the model. See the variable contract and the forkable host-info provider.

License

MIT