Configure the CLI

Everything on this page is optional. Remi works with no configuration at all. Claude Code's files (CLAUDE.md, .claude/commands, .claude/skills, .claude/agents, .mcp.json and plugins) work as they are, so a project set up for Claude Code is ready for Remi.

Where your settings liveCopy Anchor Link

When the files disagree on a single value, such as model, the later file in the table wins. Lists, such as permission rules, are combined.

{
  "model": "Remi Auto",
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm test:*)", "Bash(git diff:*)", "Edit(src/**)"],
    "deny": ["Read(secrets/**)"],
    "ask": ["Bash(git push:*)"]
  },
  "notifications": "bell",
  "theme": "light"
}

• notifications: bell (the default) rings the terminal bell when Remi waits for you, and when a long turn finishes. off turns it off.
• theme: dark or light. Leave it out and Remi asks your terminal.
• host: { "enabled": false } stops this folder taking messages from your phone or the web. See Pick up anywhere.

Trust a folderCopy Anchor Link

The first time you run remi in a folder, it asks whether you trust it. Say no and Remi quits. Your answer is saved, and trusting a folder also trusts everything inside it.

Anyone can commit a file to a repo. So a folder's own files that start programs, that Remi uses without you asking, or that loosen the rules wait until you trust the folder:

Your own files in ~/.remi/ always count. Trusting a folder doesn't stop Remi asking before it changes files or runs commands: your mode and your rules decide that.

remi -p never asks. In a folder you haven't trusted, it runs as the "Not trusted" column says. To trust the folder for one run, in CI for example, set REMI_TRUST_FOLDER=1.

Choose what runs without askingCopy Anchor Link

ModesCopy Anchor Link

Press Shift+Tab in the app to change mode, use --mode for one run, or set permissions.defaultMode in your settings.

The Autopilot sandbox. On macOS, and on Linux with bwrap installed, a command in Autopilot can read anything but can only write inside the project, temporary folders and tool caches, and can't reach the network. Remi still asks before:

• commands that need the network, such as installs, pushes and curl;
• commands that name a file that may hold secrets, such as .env or a key;
• deleting files, git commands that lose work, and running as another user;
• reaching outside the project folder;
• commands too complex for Remi to read safely.

To let the sandbox reach the network, set "sandbox": { "network": true } in your settings. On Windows, and on Linux without bwrap, there's no sandbox, so Autopilot asks before commands.

RulesCopy Anchor Link

Rules say which tools run without asking (allow), which always ask (ask) and which never run (deny). They use Claude Code's syntax:

In the app, /permissions lists every rule in force and the file it comes from. To add one, use /permissions allow, deny or ask with the rule:

/permissions allow Bash(npm test:*)

It's saved in .remi/settings.local.json and applies straight away. /permissions remove with the rule takes it out.

A few things to know:

• For a && b to run without asking, every part has to be allowed. A deny rule on any part blocks the whole command.
• Commands that only look, such as ls, git status and git diff, never ask. Where there's a sandbox, they run in one that can't write or reach the network.
• Edits to files that run things later, such as .remi/, .claude/, .mcp.json, .git/hooks/ and .vscode/, always ask, unless a rule names them.

Files that may hold secretsCopy Anchor Link

Remi doesn't read these unless an allow rule names them: .env and .env.* (but not templates such as .env.example), .envrc, .dev.vars, *.pem, *.key, *.p12, *.pfx, SSH keys, .git/config, .npmrc, .netrc, .pypirc, *.tfvars and credentials*.json. An @ mention never attaches one, and searches skip them.

Before command output is sent to Remi, keys, tokens and passwords in it are replaced with [redacted]. Your terminal still shows the real output.

Work in more than one folderCopy Anchor Link

Remi works in the folder you started in. To let it use another folder too, such as a sibling repo, start with --add-dir, or use /add-dir in the app:

remi --add-dir ../shared

The same rules apply in the other folder. To make it permanent, add "permissions": { "additionalDirectories": ["../shared"] } to your settings.

Tell Remi about your projectCopy Anchor Link

AGENTS.md is where you tell Remi how a project works: how to build and test it, its conventions, and what to leave alone. Remi sends it with every message.

# AGENTS.md
- Run `npm run check` before saying you're done. It runs the types, lint and tests.
- API types stay snake_case, as the server sends them.
- Don't edit files under `generated/`. Run `npm run codegen` instead.

• Where Remi looks: AGENTS.md (or REMI.md, or CLAUDE.md) in the project and in each folder between the repo's root and where you started. For notes that apply to every project, use ~/.remi/AGENTS.md.
• Write a first version: run /init in the app.
• Add a line: type # always use pnpm in the app.
• Edit it: /memory edit opens the folder's file in your editor, and /memory edit ~ opens yours. The next message reads it again.
• See what's sent: /context shows how full the conversation is, the instruction files, the skills, the agents and the tools. If it left a file out, it says why.

A project's instruction file must be a Markdown file inside its folder. If it links to a file elsewhere, or to a file that may hold secrets, Remi skips it.

Make your own commandsCopy Anchor Link

A command is a prompt you keep in a file and run by name. Save this as .remi/commands/fix-issue.md:

---
description: Fix a GitHub issue
argument-hint: <issue number>
---
Fix issue #$1. Read the issue, find the cause, fix it, and run the tests.

Then type /fix-issue 42 in the app, or run remi -p "/fix-issue 42". Remi sends the prompt with 42 in place of $1.

• Where they're read: ~/.remi/commands/ for yours, and .remi/commands/ and .claude/commands/ in the project. A file in a subfolder becomes /folder:name.
• Arguments: $ARGUMENTS is everything after the command, and $1 to $9 are the words one by one. A command that uses neither gets the arguments added at the end.
• A project's commands load only once you trust the folder.

Teach Remi a skillCopy Anchor Link

A skill teaches Remi how to do a particular task, and Remi loads it when a request matches. It's a folder with a SKILL.md, in Claude Code's format. Save this as .claude/skills/release-notes/SKILL.md, next to a template.md:

---
name: release-notes
description: Write release notes from the changes merged since the last release
---
List the pull requests merged since the last tag, then write the notes in template.md's shape.

Ask for release notes and Remi loads the skill before it starts. /release-notes runs it directly.

• Where they're read: ~/.remi/skills/ for yours, and .claude/skills/ and .remi/skills/ in the project.
• What Remi can read: the skill's instructions, and the files in its folder, such as template.md. Never anything outside it, and never a file that may hold secrets.
• Who runs it: add disable-model-invocation: true to keep a skill to /name, or user-invocable: false to keep it to Remi.
• A project's skills load only once you trust the folder. /context lists the skills Remi has.

Hand big searches to a subtaskCopy Anchor Link

Some questions mean reading many files: "find every place that writes a session file". Remi can hand those to a subtask: a second Remi that can only read, does the searching in its own chat, and brings back just what it found. Your conversation doesn't fill up with every file it opened. Remi decides when to use one, or you can ask: "use a subtask to find every caller of saveSession".

A subtask only reads. Your deny rules and the files that may hold secrets apply inside it, and anything that would ask is refused. It stops after 15 minutes and counts towards your plan like any turn. To turn subtasks off, add Task to permissions.deny.

Custom agents give a subtask a name, instructions and fewer tools, in Claude Code's format. Save this as .claude/agents/code-finder.md:

---
name: code-finder
description: Finds where something is implemented and explains how the pieces fit
tools: Read, Grep, Glob
---
Search the code for what you're asked about. Answer with the files and lines that matter, and a short explanation of how they connect.

Remi runs the one that fits, or the one you name: "ask code-finder where retries are handled". Agents live in ~/.remi/agents/, and .claude/agents/ or .remi/agents/ in the project. tools: can only name read-only tools (Read, Grep, Glob, LS and Skill).

Run your scripts at set momentsCopy Anchor Link

Hooks are commands Remi runs at set moments, in Claude Code's format, so existing hooks work as they are. Add them to your settings:

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "npx prettier --write ." }] }
    ]
  }
}

• When they run: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop and SessionEnd.
• What they get: the event as JSON on standard input.
• What they can do: exit with 0 to carry on. On SessionStart and UserPromptSubmit, what they print is added for Remi to read. Exit with 2 to block: the tool doesn't run, or the message isn't sent, and Remi is told why.
• Where they run: sh on macOS and Linux, and Git Bash on Windows when it's installed.

A project's hooks run only once you trust the folder.

Add MCP serversCopy Anchor Link

MCP servers give Remi another service's tools, such as your issue tracker or a database.

In your Remi accountCopy Anchor Link

remi mcp add https://mcp.example.com/mcp

Use the server's MCP address from its own docs. The server is added to your Remi account, so it works in every Remi app: the web, your phone, Remi Desktop and here. If it needs a sign-in, your browser opens. Remi keeps the sign-in on its side, so it isn't stored on this computer.

remi mcp list and /mcp show your servers. remi mcp remove takes one out.

On this computerCopy Anchor Link

Remi reads .mcp.json in the project, the same file Claude Code uses:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

${VAR} is read from your environment, so keys don't go in the file. To add a server from the command line:

remi mcp add --scope user --transport http github https://api.githubcopilot.com/mcp/

--scope user keeps it in ~/.remi/mcp-servers.json, for every project; Remi Desktop reads that file too. Servers that need a sign-in show "needs a sign-in" in remi mcp list: run remi mcp login with the server's name.

Remi asks before using an MCP tool, unless the server marks it read-only or a rule allows it. A project's own servers start only once you trust the folder.

Add pluginsCopy Anchor Link

A plugin bundles skills, commands, agents, hooks and MCP servers in one folder, in Claude Code's format:

deploy-tools/
├── .claude-plugin/plugin.json
├── commands/status.md
├── skills/deploy/SKILL.md
├── agents/reviewer.md
├── hooks/hooks.json
└── .mcp.json

Try one for a single run:

remi --plugin-dir ./deploy-tools

To keep it, put it in ~/.remi/plugins/deploy-tools/. Each part is named after the plugin, such as /deploy-tools:status. In the app, /plugin lists what's loaded and anything left out, with why.

Remi loads plugins only from folders on your computer, not from marketplaces. A project's plugins in .remi/plugins/ load only once you trust the folder.

Change the status lineCopy Anchor Link

As in Claude Code, your own command can draw the line under the input box:

{ "statusLine": { "type": "command", "command": "~/.remi/statusline.sh" } }

It gets the session as JSON on standard input, and the first line it prints replaces Remi's.

Connect your editorCopy Anchor Link

Zed, JetBrains IDEs, Neovim and Emacs can run Remi as their AI agent through remi acp. Your editor shows the chat, the changes and the permission requests. Remi works in the project the editor has open.

Sign in from a terminal first:

remi login

If your editor can't find remi, use the full path from which remi instead of remi.

{
  "agent_servers": {
    "Remi": {
      "type": "custom",
      "command": "remi",
      "args": ["acp"],
      "env": {}
    }
  }
}

{
  "agent_servers": {
    "Remi": {
      "command": "remi",
      "args": ["acp"],
      "env": {}
    }
  }
}

require("avante").setup({
  provider = "remi",
  acp_providers = {
    remi = { command = "remi", args = { "acp" } },
  },
})

In Emacs, agent-shell can run Remi through an agent config whose client runs remi acp, defined the way agent-shell defines its built-in agents.

Your editor's modes, model picker, / commands and /undo work as in the terminal. When your editor offers it, Remi edits its open buffers and runs commands in its terminal.

Use Remi from another agentCopy Anchor Link

remi mcp serve lets other agents ask Remi things over MCP, with your connected apps and web search. For Claude Code:

claude mcp add --transport stdio remi -- remi mcp serve

Use Remi in scripts and CICopy Anchor Link

remi -p answers once and exits. See Ask once, from a script for the options.

Where nobody can sign in in a browser, use a token:

remi token create --name ci

Environment variablesCopy Anchor Link

These change what the installer does:

Set them before the install command:

curl -fsSL https://remiapp.ai/install.sh | REMI_INSTALL_DIR=~/bin sh