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 or a configured reachable endpoint on mobile); 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.

Review on mobile

Android presents proposed agent and filesystem changes as focused review items. Move through one hunk at a time, add a comment, accept or reject the change, defer it, or run the available validation without reconstructing the task on a desktop. The same approval boundary applies: a proposal is not written merely because the agent produced it.

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.