Remy

Remy is the interactive terminal client for Coding Agent. Run remy for normal use. It signs you in when needed, shows your remote sessions, starts new work, and lets you follow up or finish it—without cloning repositories or running an agent on your computer.

Use the other commands only for automation, direct navigation, or configuration.

Quick start

Remy requires Bun 1.3.10 or later, access to a Coding Agent deployment, and a browser for first-time Tela device authorization.

Install the published package:

# mise
mise use --global [email protected]
mise use --global npm:@meistrari/remy-cli

# bun
bun i -g @meistrari/remy-cli

# pnpm
pnpm i -g @meistrari/remy-cli

Then open Remy:

remy

On first use, Remy opens browser-based device authorization, validates your Coding Agent identity, and opens the session dashboard. Later, the same command takes you straight to that dashboard.

Your everyday workflow

The dashboard is the starting point for all interactive work. It refreshes the visible session page every 10 seconds, so new sessions and status changes appear while you keep it open. If an update fails, Remy keeps showing the last successful list and retries on the next interval.

Start work

Press n in the dashboard. The new-session flow asks what you want done, selects a GitHub installation when needed, suggests repositories based on your request, and lets you review those suggestions. Before creating the session, choose the agent model and reasoning effort. Reasoning starts at high by default. Remy then opens the session and streams its activity.

Use Tab while writing the request to complete a local file path. Remy attaches selected paths when you confirm the request. On macOS, Ctrl+V adds a PNG from the system clipboard to the request; Remy attaches it on confirmation. Remy uploads files before creating the session.

Resume or follow up

Use Up/Down to select a session in the dashboard, Left/Right to load the adjacent page, and Enter to open it. After the dashboard list or repository-review list has focus, Vim keys work too: j/k move, h/l go to the previous/next dashboard page (or clear/mark a repository), G goes to the last row, and gg goes to the first row. Press Shift+L in the dashboard to start a logout confirmation. In a session, type a follow-up and press Enter to send it.

The Live reasoning preview shows the newest main-agent summary as it arrives. It is a short, best-effort preview—not private chain-of-thought. Long previews show Preview shortened. Opening or reconnecting partway through a summary may show no preview; the final summary still appears in activity history. Disconnecting or finishing the item clears the live preview.

Published files and Tela Pages appear in the timeline. A Tela Page row includes its title and canonical URL so you can open it directly from the terminal.

When Remy creates a plan, the session shows its checklist in the timeline and keeps Plan <done>/<total> with the current item pinned above the composer. Updates change the same checklist instead of producing repeated rows, and an unfinished plan remains visible after reconnecting or between turns. The collapsed timeline shows up to five plan items; press Ctrl+O for the complete checklist and activity detail.

Drag to select visible text in any Remy view; Remy copies it to the local clipboard and emits OSC 52 for terminal or remote-session clipboard support, then clears the selection highlight. When the conversation has focus, press Tab to return to the composer.

| Control | Result | | --- | --- | | Esc | Interrupt the active turn; the session stays open. | | /complete | Complete an open session after its active turn stops. | | /cancel | Cancel the current session, including an active turn. | | /sessions | Return to the dashboard. | | /new | Start another new-session flow. | | /logout | Sign out of Remy after confirmation. | | /help | Show session controls. | | /exit | Leave Remy. | | Ctrl+O | Expand or collapse full plan and activity details. |

After a session becomes terminal, press Esc to return to the dashboard or n to start new work. From the dashboard, press q to quit; in an open session, q is ordinary composer text. Shift+L in the dashboard and /logout in a session ask for confirmation; press y to sign out or Esc to cancel. Ctrl+C exits Remy from the dashboard, wizard, or session view.

Commands for direct or scripted use

The interactive dashboard is the recommended path. Use these commands when a script needs Remy, or when you already know exactly what to open or create.

Create a session directly

remy new --repository owner/repository "Add a health check endpoint"

Repeat --repository to select more repositories from the same GitHub installation. If you do not select a repository, supply --installation <github-installation-id>. Repeat --attach <path> to upload files. Direct creation uses high reasoning unless --reasoning-effort overrides it. remy new creates the session from the prompt and flags, then opens it when the terminal is interactive.

Open a known session

remy --session <session-id>

Automate a session

remy new and remy --session use JSON Lines output automatically when standard input or output is not a terminal. Pass --no-tui to choose that mode explicitly; --json also selects it.

Opaque session and message metadata returned by the API is accepted for compatibility but is not displayed in the terminal view or emitted in JSON Lines output.

remy new --no-tui --repository owner/repository "Add a health check endpoint"
remy --session <session-id> --json

For a newly created session, Remy writes a created record, event-name records as they arrive, then a terminal record when the submitted turn settles. A completed turn exits with status 0; another terminal outcome exits with status 1.

{"type":"created","session_id":"ses_123","state":{"aggregate_status":"open","connection_status":"connected","active_message_id":"smg_123"}}
{"type":"event","session_id":"ses_123","event":"agent.turn.started"}
{"type":"terminal","session_id":"ses_123","state":{"aggregate_status":"open","connection_status":"connected","active_message_id":"smg_123","outcome":"completed"}}

Sign in to a different deployment

You do not need remy login for a normal first run: bare remy handles sign-in. Use it to select a deployment profile or change connection settings:

remy login --env staging
# or: remy login --env production

REMY_ENVIRONMENT=staging remy login selects the same profile when --env is omitted. With neither a saved configuration nor an explicit profile, remy login uses the production profile.

For a custom deployment with no saved configuration, provide all four connection values:

remy login \
  --api-url <agent-api-url> \
  --auth-api-url <auth-api-url> \
  --requester-application-id <requester-application-uuid> \
  --target-application-id <target-application-uuid>

Remy stores endpoint configuration in ~/.config/remy/config.json and tokens in ~/.local/state/remy/tokens.json. Set XDG_CONFIG_HOME or XDG_STATE_HOME to use different base directories. Before each Coding Agent API request, it reloads the shared token file and refreshes an expired access token. When multiple Remy processes run at once, only one rotates and saves the refresh-token pair; the others wait and then use that newest saved pair. Long-running sessions and reconnects therefore stay authenticated after another process refreshes. remy logout removes tokens but retains endpoint configuration; pass --api-url to require that the supplied URL matches the active API host before logging out.

Complete command reference

remy
remy help | --help | -h
remy login [--env production|staging] [--api-url <url> --auth-api-url <url> --requester-application-id <uuid> --target-application-id <uuid>]
remy logout [--api-url <url>]
remy whoami
remy dashboard
remy new [--repository <owner/name> ... --installation <id> --model <name> --reasoning-effort <low|medium|high|xhigh> --attach <path> ... --no-tui --json] <prompt>
remy --session <session-id> [--no-tui] [--json]

Run remy <command> --help for flags and command-specific usage. remy whoami prints the saved signed-in identity and organization.

Development and releases

This README is copied into the published package. Repository contributors should use the Remy CLI guide for local development, release preparation, and package smoke checks.