# Notebook agents

> Work with a local coding agent in a notebook or connect one over MCP.

> **Developer preview**
>
> Notebook agent tools may change during the preview. Review the Git diff after agent edits, just as you would after making the same change in the visual editor.

## Chat inside a notebook

![A Renart notebook with its local agent chat open beside the document, showing the agent picker, Ask and Edit modes, and a prompt composer](https://getrenart.com/docs-media/notebook-agent.webp)

Install and sign in to Codex, Claude Code, or OpenCode on the machine where Renart runs. Open **Build → Notebooks**, select a notebook, and choose **AI** in its sidebar. Renart discovers available clients on `PATH`; it does not ask for or store a provider API key.

Choose a client and one of two capability modes:

- **Ask** can inspect the open notebook and search the current workspace catalog: blocks, dependency graph, diagnostics, source provenance, asset descriptions, lineage, materialization policy, and bounded result schemas/samples. It cannot edit files or run cells.
- **Edit** can prepare, validate, and apply semantic notebook changes and can add notebook data sources, and run the cells needed to verify them. Selecting Edit authorizes those actions for the turn; the resulting files remain ordinary, reviewable Git changes.

Use the **@** control in the composer to attach notebook cells or workspace assets to a message. References are sent as stable semantic identities rather than pasted file paths, so the agent can inspect the exact object you mean.

If the agent needs a decision, it can pause and show a short questionnaire in the conversation. Answer it there and the same turn continues; you do not need to restate the task. Stopping or starting a new chat also cancels a pending question.

An Edit turn can also ask for read-only access to a configured data connection. You can approve an existing connection or create one in the normal Renart connection form. Credentials remain inside Renart: the agent receives only the connection name and can perform bounded catalog discovery and sample queries for that turn. Access ends with the turn. DuckDB notebook data does not require this extra approval.

When an agent adds a source from DuckDB, Renart can run it through the same local read-only path as a manually added source. A newly added source on another warehouse remains pending until you review and run its first import in the UI; the agent cannot silently transfer an unknown amount of remote data into the notebook.

The panel starts in Ask whenever it opens, so an earlier Edit choice does not silently carry into the next task.

The chat shows progress such as reading the notebook outline, validating changes, or running cells. Changes appear in the notebook through the same server and workspace event stream as normal UI edits, so you can watch the document update alongside the conversation. **Stop** cancels the provider and its MCP process tree. **New chat** clears the current transcript and local provider session.

Chats are bounded in-memory runtime state. They survive page navigation and a temporary event-stream reconnect, but a Renart restart clears them; no prompt or answer is written into the repository. Each provider and Ask/Edit mode has a separate resumable session.

Renart starts native-chat agents in a private non-repository directory and connects them to a notebook-scoped MCP server. Ask mode does not register write or run tools. If a provider tries to use generic shell, filesystem, or web tools instead of Renart’s notebook tools, Renart stops that turn and shows the blocked activity. This is a focused local workflow, not a sandbox for an untrusted binary.

## Connect an external coding agent

`renart mcp --workspace .` starts a local stdio MCP server for one Git-backed workspace. It connects to the Renart process that already owns the workspace, or starts the same notebook services in-process when the IDE is closed. It does not open another network listener.

The server exposes semantic notebook operations rather than arbitrary paths or REST endpoints. An agent can inspect notebook outlines, blocks, dependencies, diagnostics, source provenance, bounded result samples, and searched catalog entries with lineage and materialization context. It can prepare and validate a revision-bound change, but writing files requires the separate `apply_notebook_change_set` tool. Runs are explicit and asynchronous; executing Python additionally requires `allow_python: true`.

Renart’s MCP server does **not** provide shell, filesystem, Git, connection configuration, credential, arbitrary SQL, or generic HTTP tools. A coding agent may have those capabilities independently, depending on how you configure that client. This integration is a cooperative local workflow, not a sandbox for the whole agent process.

### Before connecting

Install the `renart` binary somewhere on the coding agent’s `PATH`, and run the agent from the workspace you want it to use. Renart never writes an agent configuration file for you.

### Codex

Run this from the workspace:

```bash
codex mcp add renart -- renart mcp --workspace .
codex mcp list
```

Codex also supports project-local `.codex/config.toml`. If you use that form, keep write approval enabled:

```toml
[mcp_servers.renart]
command = "renart"
args = ["mcp", "--workspace", "."]
cwd = "."
default_tools_approval_mode = "writes"
tool_timeout_sec = 3600
```

See the [official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) for configuration scope and current client options.

### Claude Code

Add the server to the current project only:

```bash
claude mcp add --scope local --transport stdio renart -- \
  renart mcp --workspace .
claude mcp list
```

The `--` is significant: everything after it is the stdio server command. See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) for scope, trust, and permission settings.

### OpenCode

Add a local server to `opencode.jsonc`:

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "renart": {
      "type": "local",
      "command": ["renart", "mcp", "--workspace", "."],
      "cwd": ".",
      "enabled": true
    }
  },
  "permission": {
    "renart_*": "allow",
    "renart_apply_notebook_change_set": "ask",
    "renart_run_notebook_cells": "ask"
  }
}
```

This allows inspection and change preparation while requiring confirmation before authored files change or notebook code runs. Use `opencode mcp list` to check the connection. See the [OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers/) for current configuration and per-agent tool controls.

### Suggested agent instruction

Add this instruction to the local, untracked agent configuration you use for the workspace:

```text
When working on Renart notebooks, inspect and modify them only through the
Renart MCP tools. Start with list_notebooks and get_notebook_outline. Read only
the blocks and bounded result samples needed for the task. Prepare a semantic
change set, validate it, show me the proposed operations and diagnostics, and
wait for approval before apply_notebook_change_set. Never use shell or direct
filesystem edits for notebook files. Run cells only when requested; set
allow_python only after the Python code has been reviewed.
```

### Removing the integration

Use `codex mcp remove renart` or `claude mcp remove renart`, or remove the `renart` entry from `opencode.jsonc`. No notebook data or Renart runtime state is stored in the agent configuration.