Documentation

Install

1. Download the DMG from the Releases page of the project on GitHub.
2. Open the DMG and drag Right Here to Applications.
3. Open Right Here from Applications.

Or install it with Homebrew, from the project's own tap:

brew install --cask boyugou/tap/right-here

Right Here must run from your Applications folder. A copy that runs from the DMG or from Downloads cannot set up: the window asks you to move it, and rh setup refuses.

To update, drag the new app over the old one and choose Replace, or run brew upgrade --cask right-here. Then open Right Here and press Install or Repair. Your config file stays as it is.

You can also build Right Here yourself. You need Xcode 26 or later and xcodegen:

brew install xcodegen
./script/install_local.sh     # builds the app, copies it to ~/Applications and runs rh setup

Set up

There are three ways to set up. All three run the same steps.

• In the app: choose your terminal, your editor and your agents, and press Set Up.
• In a terminal: run rh setup.
• With an AI assistant: see below.

Setup does these steps, in this order:

1. It makes the config file, if there is none.
2. It installs the runner script that Finder needs.
3. It links rh into ~/.local/bin.
4. It installs the Quick Actions.
5. It registers the Finder extension.
6. It runs the checks of rh doctor.

rh setup                      # set everything up
rh setup --terminal ghostty --editor zed --agents claude,codex
rh setup --dry-run            # show what it would do, and change nothing
rh setup --json               # the report, for a script or an AI assistant

You can run setup again at any time. It makes what is missing and updates what is out of date.

Setup never rewrites a config file that exists. If the file does not say what you asked for, setup lists the line to change, and you make the edit. --force replaces the file, and saves the old one next to it first.

Setup opens no window and never changes System Settings. At the end, it lists what only you can do:

• Turn on Right Here in System Settings › General › Login Items & Extensions › Finder.
• Choose Allow when macOS asks whether Right Here may control your terminal. macOS asks this the first time that an agent starts there.
• Add ~/.local/bin to your PATH, if it is not there.

The setup window

If there is no config file, the setup window shows the terminals and editors on your Mac and the agents that Right Here knows. It selects the ones that it finds.

Press Set Up. The window runs the same steps as rh setup and lists what it did.

Then a card shows three steps. Its button opens System Settings for the Finder extension. The window checks every two seconds, so the card changes when you turn the extension on.

After the first setup, the app changes your config file only when you change a setting. Open Config opens the file. Install or Repair runs the other steps of setup again, and leaves the config as it is. Use it after you replace the app with a newer copy.

Tests cover the setup with temporary folders and fake runners. Not tried on a real Mac yet: the first run in a real window, and the card when you turn the extension on.

Set up with an AI assistant

In the app, open AI Assistants and press Copy Setup Prompt for AI. Paste the prompt into your assistant. An assistant that can run commands can also read the playbook with rh docs agent-setup.

The assistant follows these steps:

1. It asks you which terminal, editor and agents you use.
2. It runs rh setup --dry-run --json to see what setup would do.
3. If you have a config file, it makes the edits that setup lists.
4. It runs rh setup --json once.
5. It tells you what only you can do, with the exact clicks.
6. It checks the result with rh doctor.

The assistant does not change System Settings. It does not rewrite or delete your config file.

We tested the playbook with new Claude agents in five setups: no config, no agent, a config to keep, a config that does not parse, and a config that holds a sentence written to an AI agent. Each agent asked first and changed only what the person asked for. A sandbox cannot register the Finder extension, so the test did not cover that step.

Use it

In Finder, right-click a folder, a file or the empty part of a window. Then choose an action. In a terminal, use rh:

rh menu                       # the Finder menu for this folder
rh actions                    # the actions that you can run here
rh run agent.claude           # start Claude Code in this folder, in your terminal
rh run agent.claude --worktree   # the same, in a new git worktree of the repository
rh worktree list              # the worktrees (remove takes only the ones that Right Here made)
rh run copy-path.git-relative src/main.swift
rh run new-file.md --container ~/notes
rh pin ~/code/app             # pin a folder (rh pins and rh recents list them)
rh doctor                     # check the setup
rh doctor --probe-launch      # test a click: a terminal window opens and closes
rh config sync status         # compare this Mac's config with the sync folder

Finder shows no extension menu in iCloud Drive. This includes a Desktop or Documents folder that iCloud syncs. Use the Quick Actions there. You can give them keyboard shortcuts in System Settings › Keyboard › Keyboard Shortcuts › Services.

The Finder menu page of the setup window shows the menu for a folder. Press Edit Menu there to move lines, add them or take them out: Reveal in Finder, the repository links and more forms of Copy Path are not in the menu at first. rh menu --explain says what the menu leaves out, and why.

rh --generate-completion-script zsh prints a completion script for your shell. It also takes bash and fish.

Actions

Each action has an id. rh actions lists the actions for the current folder. rh actions --all also lists the others, and says why they are not available.

Add --dry-run --json to rh run to see what an action would do, without doing it:

rh run agent.claude --dry-run --json

Configure

Right Here keeps its settings in one TOML file, ~/.config/right-here/config.toml. rh setup makes it from what is installed. After that, Right Here changes only what you ask for, and keeps your comments. An example:

[general]
terminal = "ghostty"
terminal_placement = "tab"           # a new tab in the front Ghostty window
editor = "vscode"
agents = ["claude", "codex", "lazygit"]   # what the menu offers, in order

[menu]                               # this is the default
items = ["open-terminal", "open-editor", "open-with", "agents", "agents-more", "-", "new-file", "copy-path"]

[new_file]
then = "open"

[[new_file.template]]
id = "md"
title = "Markdown Document"
extension = "md"
open_with = "typora"

[agent.claude]
command = "claude --model opus"      # what is typed into the shell

[agent.lazygit]                      # any command works like an agent
name = "lazygit"
command = "lazygit"

You can change a setting in three ways:

• In the setup window. Each page changes the config file, and Undo takes a change back.
• With rh config, one setting at a time: rh config set general.terminal ghostty, rh config add menu.items open.app.zed --at 3, rh config move menu.items agents --to first. rh config undo takes the last change back.
• In a text editor. rh config path says where the file is.

rh config validate checks the file and suggests a fix for a typo. --strict also fails on a warning. rh docs config lists every setting with its default. rh config schema prints a JSON Schema for your editor.

Agents keep their permission prompts. If you set bypass_permissions = true under [general], or under [agent.<id>] for one agent, the agents start without them. The default is off. rh agents, rh doctor and rh menu --explain say when it is on. A preset always keeps the prompts.

Terminal command or desktop app

Claude Code and Codex are command-line tools and desktop apps. Claude Code Here and Codex Here type the command into a terminal. Claude Code in Desktop App and Codex in Desktop App open the desktop app on the folder. These two are in More Agent Options.

To make Claude Code Here or Codex Here open the desktop app, set launcher = "desktop" under [agent.claude] or [agent.codex]. The value can also be terminal (the default) or link (the agent's own link to a terminal).

[agent.claude]
launcher = "desktop"      # the agent's main menu entry opens the desktop app on the folder

[agent.codex]
launcher = "terminal"     # the default: the command is typed into a terminal

Agent presets

A preset is a prompt that Right Here sends to an agent with the files that you selected. Three presets are built in: Review, Explain and Write Tests. Write Tests proposes a plan for tests. The presets are in More Agent Options › Agent Presets.

A preset types the command of the agent and the prompt into a terminal. The agent starts to work on the prompt at once.

Add your own preset with [[preset]] in the config. A preset with the id of a built-in one replaces it.

[[preset]]
id = "lint"
title = "Check Style"
agent = "claude"          # optional: the first agent in general.agents when left out
prompt = "Check {files} for style problems. Do not modify any files."
max_files = 10            # optional: 1 to 50, default 20

[agent.mytool]            # another agent: how its command takes a first prompt
name = "My Tool"
command = "mytool"
prompt_arg = "--prompt"   # or "positional"

• {files} is the selected files, as @ mentions from the folder.
• {folder} is the name of the folder.
• {name} is the name of the first selected item.

The agent must take a first prompt as an argument. Claude Code, Codex, Antigravity, Gemini CLI, GitHub Copilot, Cursor CLI, Qwen Code, Factory Droid and Kiro CLI do. For another agent, set prompt_arg in its [agent.<id>] table to "positional", or to the flag that carries the prompt. Right Here offers no preset for an agent that cannot take a prompt.

A preset with {files} needs selected files, not folders, and at most max_files of them. If not, the menu leaves it out, or rh refuses it and says why. A prompt cannot contain a line break, another control character or a backslash, and it cannot start with a dash.

The built-in prompts ask the agent not to change files. The agent and its permission settings decide whether it obeys. The prompt contains the file names, and it goes to the agent before you read it. So use presets in folders that you trust.

Tests plan each preset and send unusual file names through real shells. Not tried on a real Mac yet: a preset in a real terminal.

Shortcuts and Spotlight

Four actions also run from the Shortcuts app, Siri and Spotlight, without the Finder extension: Open in Terminal, Start AI Agent, Create New File and Copy Path.

Each one starts the rh that is inside the app, with a list of arguments, and stops it after 60 seconds. You choose the folder or the item as a file, or pick one of your pinned or recent folders from a list. You choose the agent and the file template from lists. There is no field for a command of your own.

These are the English phrases for Siri and Spotlight. The app has them in 30 languages.

• Open in terminal with Right Here
• Start an agent with Right Here
• Create a new file with Right Here
• Copy a path with Right Here

The app contains the four actions and their phrases, and tests cover the command that they make. Not tried on a real Mac yet: the actions in Shortcuts and in Spotlight.

Use one config on several Macs

Keep the shared settings in config.toml, and what differs on each Mac in config.local.toml. Then copy config.toml through a folder. rh docs sync has the full guide.

Settings for this Mac only

config.local.toml is next to config.toml. rh and the Finder menu read both. Right Here never syncs config.local.toml.

• A setting in it replaces the shared setting.
• A list replaces the shared list as a whole.
• An entry with an id ([[app]], [[preset]], [[new_file.template]], [[agent.<id>.variant]]) replaces the shared entry with that id, or adds a new one.
• [agent.<id>] merges one key at a time.
• disabled = ["id", ...] removes apps, templates and agents on this Mac, also the built-in apps.

For example, a work laptop without Codex, with Terminal as its default terminal:

# config.local.toml: this Mac has no Codex and uses another default terminal
disabled = ["codex"]

[general]
terminal = "terminal"

Sync through a folder

Right Here copies the config, and does not link it. The Finder extension is sandboxed and can read only its own config folder. Also, iCloud can replace a file that it did not download with a placeholder. So each Mac keeps an ordinary file, and rh config sync copies it to and from a folder that you choose.

rh config sync enable                     # choose the folder (default: iCloud Drive, folder "Right Here")
rh config sync enable --folder ~/Sync/rh  # any folder works: Dropbox, a git checkout, a network share
rh config sync push                       # send this Mac's config to the folder
rh config sync pull                       # take the folder's config (refused, with a list, if it adds programs)
rh config sync pull --allow-commands      # take it although it adds or changes terminal templates or agent commands
rh config sync status                     # in-sync, local-ahead, remote-ahead, diverged, remote-missing or remote-evicted
rh config sync disable                    # forget the folder; both copies stay

On a second Mac, run rh config sync enable and then rh config sync pull.

• pull refuses if this Mac's config changed since the last sync. push refuses if the copy in the folder changed. --force replaces the file anyway, and saves the old one first.
• Both refuse a config that is not valid, is larger than 1 MiB, or has key names that look like secrets.
• pull waits while somebody else changes the config, in the window, with rh config or through an assistant.
• Right Here never overwrites a copy that iCloud did not download. Each write is atomic, and nothing is deleted.

Programs in a synced config

Other Macs, a sync service or a shared drive can write the folder. So a config from the folder cannot add a program by itself. pull stops and lists the change if the copy adds or changes one of these:

• a terminal template, or the role of a terminal app
• a terminal that starts through a template, where Right Here uses it
• the command, args, prompt_arg, start options, bypass_permissions or bypass_permission_arg of an agent
• an agent in the menu or in the Quick Actions that starts without its permission prompts
• the contents of a New File template

Read the list. If the changes are yours, run rh config sync pull --allow-commands. rh config sync status shows the same list before you pull. A first pull on a new Mac asks only about programs of your own, not about the built-in apps and agents.

A dotfiles manager can keep config.toml as a link. rh follows the link, but the Finder extension may not, so copy the file instead. A git repository can be the sync folder: commit there.

Tests use temporary folders and fake file systems. Not tried on a real Mac yet: real iCloud Drive.

Supported terminals

Right Here has built-in support for six terminals: Ghostty, Terminal, iTerm2, WezTerm, kitty and Alacritty. Each one opens a folder, and starts an agent or a preset in it. Ghostty and Terminal were tried on a real Mac. The others were not, and rh doctor --probe-launch checks yours.

You can add any terminal with an [[app]] entry that has role = "terminal":

• open_args says how to open a folder.
• run_args says how to start a typed command. It must contain {command}.
• Both are lists of arguments, and can use {dir}, {shell} and {app}.
• Start the terminal through /usr/bin/open -n -b <bundle id> --args, so that rh run does not wait for the window to close.

This entry for Alacritty is an example. It replaces the built-in entry, so rh config validate warns about it:

[[app]]
id = "alacritty"
name = "Alacritty"
bundle_id = "org.alacritty"
role = "terminal"
open_args = ["/usr/bin/open", "-n", "-b", "org.alacritty", "--args", "--working-directory", "{dir}"]
run_args = ["/usr/bin/open", "-n", "-b", "org.alacritty", "--args", "--working-directory", "{dir}", "-e", "{shell}", "-lic", "{command}; exec {shell} -l"]

Termius is not offered. It is an SSH client, and it cannot start a local shell in a folder.

AI assistants and MCP

MCP, the Model Context Protocol, is the way that AI apps use tools. rh mcp is an MCP server.

Add the MCP server to Claude Code:

claude mcp add right-here -- rh mcp

rh must be on the PATH of the client. An app that starts from the Dock does not get your PATH, so give it the full path of rh. Copy MCP Configuration, on the AI Assistants page of the app, writes it for you.

Or install the Claude Code plugin, and start a new session:

/plugin marketplace add boyugou/right-here
/plugin install right-here@right-here

The plugin adds three skills: set Right Here up, open a folder, and show in Finder the files that the agent changed.

An assistant cannot change by itself which program a click starts, or turn off the permission prompts of an agent. It proposes the change. You apply it on the Config page of the app, or with rh config pending.

The tools mark names and paths as data. A terminal only gets folders.

Troubleshooting

Start with rh doctor. Each check says what is wrong and what to do.

• rh doctor --json gives the same checks to scripts and AI assistants.
• rh doctor --probe-launch tests the whole path of a click. A terminal window opens and closes.
• To report a bug, send the output of rh doctor --report. Do not send --json, because it contains the names and paths of your config.
• The setup window shows the same checks in its own language. rh doctor and the MCP tool use English.

The Finder menu does not show

• If the extension is off, turn on Right Here in System Settings › General › Login Items & Extensions › Finder. Or run rh install --finder.
• In iCloud Drive, Finder shows no extension menus. Use right-click › Quick Actions there.
• After a macOS update or a new copy of the app, run rh setup. It registers the extension again.
• If two copies of Right Here.app are on the Mac, macOS registers neither. Move every copy except the one in Applications to the Trash. Then run rh setup again.
• If rh doctor says that the extension crashed, attach the crash report that it names to a bug report.

I click an item and nothing happens

• rh doctor shows the line "Last action started from Finder". If it says "none yet" after your click, the click did not reach rh.
• A failed action shows an alert, and writes a line to ~/Library/Logs/right-here/rh.log.
• Run the action from a terminal with --dry-run to see what it would do.

macOS asks whether Right Here may control the terminal

This is the Automation permission. macOS asks it once for each terminal. Choose Allow. If you chose Don't Allow, turn it on in System Settings › Privacy & Security › Automation.

An action says macOS did not let Right Here look at a folder

Desktop, Documents, Downloads and iCloud Drive are protected, and macOS asks once. Choose Allow, and run the action again. Right Here stops on purpose. It never starts a terminal in another folder instead.

An agent says “not found”, or starts without my aliases

• Right Here types the command of the agent into your login shell. So the agent sees what a new terminal window sees: nvm, your PATH and your aliases.
• rh agents shows which agent commands your login shell finds.
• If rh doctor says that your login shell "did not say whether it is installed", a startup file exits or is slow. exec tmux is a usual cause. Start tmux only when a terminal is attached, and look again.

The agent opens in a window and I want a tab

Set terminal_placement = "tab", "split-right" or "split-down" under [general]. This works in Ghostty and iTerm2.

Quick Actions are missing or out of date

rh install --services makes them again from the config. A change in the setup window updates them at once. After a change in the config file or with rh config, press Install or Repair, or run that command.

The config has a mistake

rh config validate --strict lists each problem. For a typo, it suggests the likely word.

rh config sync pull does not take the copy

The message says why, and nothing changed. The usual reasons:

• The copy adds or changes a program. Read the list. Then run rh config sync pull --allow-commands.
• This Mac's config changed since the last sync. Run rh config sync status. Then rh config sync push sends your file, or rh config sync pull --force replaces it. The old file is saved first.
• iCloud keeps the copy online only. Open the folder in Finder and let the file download.
• Another change of the config is in progress. Wait for it, and run pull again.

Remove Right Here

rh uninstall removes the runner script, the Quick Actions, the command link and the registration of the extension. It keeps your config. Then delete Right Here.app. With Homebrew, run rh uninstall first, then brew uninstall --cask right-here; adding --zap deletes your config too.