> ## Documentation Index
> Fetch the complete documentation index at: https://graph-unify-model-roles.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat & ask

> The agent loop: one-shot questions and the REPL

`ask` and `chat` run graph's agent loop — the conversational surface for probing tools, prototyping workflows, and exercising plans. Every tool call here also feeds the [shape cache](/tools/shape-cache), so exploration makes the planner smarter. Anything you'll run twice belongs in a [plan](/plans/overview), and plans get their own surface: the [workbench](/workbench/plan-workbench).

## One-shot: `graph ask`

```bash theme={null}
graph ask "Summarize open urgent issues"
graph ask "Now group them by project" --thread            # continue latest thread
graph ask "…" --thread 62dac762e251                       # continue a specific thread
```

* **Streaming**: the answer streams to stdout; tool activity (dim `→ tool {args}` / `✓ tool 0.8s` lines) goes to stderr. `graph ask "…" > out.md` captures just the answer.
* **Piped stdin** becomes context:
  ```bash theme={null}
  git diff | graph ask "review this change"
  cat error.log | graph ask "what's failing?"
  ```
* **`--json`** buffers and emits a machine-readable envelope instead:
  ```json theme={null}
  {
    "content": "…the answer…",
    "tool_calls_made": 3,
    "usage": {
      "calls": 4,
      "input_tokens": 2055,
      "output_tokens": 100,
      "cost_usd": 0.0077,
      "by_step": [{ "path": "chat", "calls": 4, "cost_usd": 0.0077 }],
      "by_model": [{ "provider": "anthropic", "model": "claude-sonnet-5", "calls": 4 }]
    },
    "thread_id": "62dac762e251"
  }
  ```
  `usage` covers the whole turn, including tokens spent inside any `plan__*`
  tool the agent called — its solver and its steps, not just the agent's own
  rounds. `cost_usd` appears only when [`[pricing]`](/reference/configuration#pricing--per-model-token-prices)
  is configured; the full shape is in [what a run spent](/reference/scripting-contract#what-a-run-spent).
* **`--no-stream`** prints the final answer only, without token streaming.

<Warning>
  Put `--thread` **after** the message. It takes an optional value, so `graph ask --thread "question"` parses the question as a thread id.
</Warning>

## Interactive: `graph chat`

```bash theme={null}
graph chat                      # new thread
graph chat --thread             # resume the most recent
graph chat --thread <id>        # resume a specific one
```

Slash commands inside the REPL:

| Command                | Effect                                               |
| ---------------------- | ---------------------------------------------------- |
| `/thread`              | show the current thread id and title                 |
| `/state`               | dump the conversation (including tool calls) as JSON |
| `/quit`, `/exit`, `/q` | leave (Ctrl-D also works)                            |

Each completed turn prints a dim one-line usage summary to stderr — calls,
tokens, and cost when [`[pricing]`](/reference/configuration#pricing--per-model-token-prices)
is set. It is per turn, not cumulative for the session.

A failed turn keeps the session alive and rolls the conversation back so a retry starts clean. On exit you get a copy-pasteable resume hint:

```
resume with `graph chat --thread 8d36b7003df9`
```

## Reading the output

```
→ plan__project_status {"project":"New Relic"}     ← agent called a plan tool
  → linear__list_projects {"limit":5,…}            ← steps indent under it
  ✓ linear__list_projects 631ms
  ✎ synthesizing answer…                           ← the plan's solver is writing
  …dim streamed report…                            ← solver progress (stderr)
✓ plan__project_status 8.8s
The migration is on track…                         ← the agent's answer (stdout)
```

Dim text is progress; solid text is the answer. The distinction matters for piping — only the answer is on stdout.