# Core concepts

> Short definitions of the models, agents, tools, skills, hooks, MCP servers, variables, packages and sessions that make up Raw.

Raw is configured in one JSON file, `config.json`. Its main parts are models, agents and the capabilities that agents select. The sections below define each part and link to the page with the details.

## Models

A **model** entry (`models.<alias>`) describes one connection to an upstream model. It names the provider, the wire method, the exact model ID sent to the service, the endpoint, where the credential comes from, and optional metadata such as the context window and whether the model accepts images.

A model alias such as `local` is only a name inside your config. The `model_id` value is sent to the service unchanged.

See [Models and agents](https://raw.tlelabs.com/docs/guides/models-and-agents/).

## Agents

An **agent** (`agents.<name>`) is a runnable configuration. It selects one model alias and sets everything a run needs: the system prompt, tools, skills, hooks, variables, limits and request options.

Several agents can use the same model with different tools or settings. The `default_agent` field chooses the agent when you do not pass `--agent`. You can also set `RAW_AGENT` in the environment.

See [Models and agents](https://raw.tlelabs.com/docs/guides/models-and-agents/).

## Tools

A **tool** is an action the model can request, such as reading a file, writing a file, or running a shell command. Raw ships eleven bundled tools, including `read_file`, `write_file`, `bash`, `list_skills`, `load_skill`, `list_vars` and `read_var`.

An agent exposes only the tools it lists in `tools.use`, in the order listed. Tool IDs use a source prefix: `builtin/` for bundled tools, `local/` for tools in your config directory, `agent/` for tools beside the selected config file, and `mcp/<server>/<tool>` for MCP tools.

Tools run with your operating system permissions. Read [Permissions](https://raw.tlelabs.com/docs/guides/permissions/) before you rely on tool rules.

See [Tools](https://raw.tlelabs.com/docs/extend/tools/).

## Skills

A **skill** is a Markdown instruction file (`SKILL.md`) that the model can load when it needs it. The model first lists the skills an agent selected, then loads only the ones that apply to the task. Raw ships seven setup skills, for example for configuring Raw or creating hooks.

Skills guide the model. They do not enforce a fixed sequence of steps.

See [Skills](https://raw.tlelabs.com/docs/extend/skills/) and [Skill authoring](https://raw.tlelabs.com/docs/extend/skill-authoring/).

## Hooks

A **hook** is a command that Raw runs at a named event. The events include `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop` and `SessionEnd`. An agent selects hooks in `hooks.use`, and they run in that order.

Hook commands run with your operating system permissions. A `PreToolUse` hook can block a tool call.

See [Hooks](https://raw.tlelabs.com/docs/extend/hooks/).

## MCP servers

An **MCP server** is an external tool provider that speaks the Model Context Protocol. You define servers in the top-level `mcp.servers` object. A server does nothing until an agent selects one of its tools, so unselected servers are never started.

Raw supports local `stdio` servers and remote Streamable HTTP servers.

See [MCP](https://raw.tlelabs.com/docs/extend/mcp/).

## Variables

A **variable** is a named, read-only value that an agent can read at run time, such as the current UTC time or a value from an environment variable. Variables are declared in the top-level `vars` object. An agent selects the ones it may use in its `vars` list.

Use `raw vars list` and `raw vars get NAME` to inspect them without starting a model.

See [Variables](https://raw.tlelabs.com/docs/extend/variables/).

## Packages

A **package** bundles agents, tools, skills, hooks, variables and MCP definitions into one `.rawpkg` archive. You export a configured agent, pack it, and install it on another machine. The recipient then binds the package agent to their own model with `raw agent add`.

See [Packages](https://raw.tlelabs.com/docs/extend/packages/).

## Sessions

A **session** is a saved conversation. Raw stores each session with its history and the context the model uses, so you can resume it later from the terminal or the dashboard. Sessions expire after a retention period measured from their last activity, seven days by default.

See [Sessions](https://raw.tlelabs.com/docs/guides/sessions/).

## Next steps

- [Quickstart](https://raw.tlelabs.com/docs/start/quickstart/) runs a first task.
- [Configuration reference](https://raw.tlelabs.com/docs/reference/configuration/) lists every field.
