AI agent

The agent helps you chat about your project, propose edits, run tools, and follow multi-step plans. By default it is local-first (Ollama on desktop); you can add cloud providers if you want.

Open the Agent panel from the browser sidebar.

Set up a model

1. Open Preferences → Agent (or use the model picker in the agent panel).
2. Add or enable a provider (a named config: backend + URL + model).
3. Use Test connection / model list when available, then select a model.
4. On desktop, the default is Ollama at http://localhost:11434.

Examples of backends: Ollama, llama.cpp, Cloudflare Workers AI / AI Gateway, Google AI Studio, Groq, OpenRouter, NVIDIA NIM, Cerebras, GitHub Models, OpenCode.

Provider enable/disable is stored with the project so teammates sharing .rope_notes/preferences.toml see the same options.

Chat and context

• Type in the prompt field and send.
• Mention files with @path (typeahead suggests project files). Ranges like @path:10-40 are supported where applicable.
• Drag files from Explorer into the agent context chips.
• Open editor tabs are indexed automatically so the agent can see relevant snippets (within a token budget — watch the budget bar in the panel).

Modes

Switch REPL mode in the panel:

Edits

When the agent proposes a change:

1. Review the ghost preview and/or diff.
2. For multi-file proposals, switch among files in the proposal UI.
3. Accept to apply, or Reject / cancel to discard.

Destructive edits may ask for confirmation. File access is gated by permissions.

Skills

Skills are reusable instruction packs. Invoke them with slash commands (e.g. /skill-name) from the prompt field typeahead.

• Bundled skills ship with the app (note-taking, Flutter helpers, TDD, …).
• Project skills live in .rope_notes/skills/ as SKILL.md files.

Plans

1. Ask for a plan or use /plan (a bare /plan can pick up recent chat context).
2. Plan artifacts are stored under .rope_notes/ (plan-*.md, checklist.md, tasks.md).
3. Switch to Execute / apply flow to work through checklist items iteratively.

Those managed plan files are protected from casual agent overwrites during execution.

Memory

Project memory (persistent notes)

• /remember — store a short note the agent should always see.
• /forget — remove notes (as supported by the command).

Notes live in .rope_notes/memory.json (capped in size).

Semantic memory (optional)

Under Preferences → Agent, enable Semantic memory to index paragraphs from open documents for hybrid search (on-device embeddings). Requires a HuggingFace token for the EmbeddingGemma model download the first time. Indexes are in-memory for the session; project memory notes above are separate and persistent.

Permissions

Agent file access is controlled by .rope_notes/permissions.toml:

• Path allow/deny patterns
• Directory allow/deny
• Web-fetch policy (when the agent fetches URLs)

If permissions are missing, writes are denied until a permissions file exists. Opening a project can create a default permissive file so you are not blocked on first use — tighten it for sensitive repos.

Sessions and history

Chat turns are saved under .rope_notes/sessions/. You can:

• Continue the last chat (preference)
• Search/filter past sessions in the agent panel
• Browse a session as read-only markdown in the history view

Each session can also keep a console.md log of tool/orchestrator events.

Other useful commands

Examples handled in the agent (availability depends on mode/backend):

Platforms

Privacy tip

Prefer local backends (Ollama / llama.cpp) when you do not want source code sent to a third party. Cloud providers send prompts and context to their APIs according to their policies.