✦ docs

Everything you need, in one place.

ruggly is a terminal editor for AI prompts. You write in Markdown, send the note to your coding agent, and say what you want in plain words. These docs cover the first ten minutes, fixing Claude Code's plans (agents), and what to do when something goes wrong.

✦ 01 / install

One line.

curl -fsSL https://dl.ruggly.dev/install.sh | sh

It runs on macOS and Linux. The installer signs you in (next section). It checks the download against signed checksums, then puts ruggly in ~/.local/bin. If that folder isn't on your PATH, it prints the line to add for zsh, bash or fish.

Then run ruggly to open your notes.

  • Update: ruggly update downloads the newest version and checks its signature before it replaces the old one. Once a day, the app tells you when a new version is out.
  • Version: ruggly --version.
  • Uninstall: ruggly logout, then rm ~/.local/bin/ruggly ~/.local/bin/rugly. Your notes stay where they are. Their backup stays in your account until you delete it: write to hello@ruggly.dev.

✦ 02 / sign in

Google, in your browser.

The installer, and later ruggly login, print a link and a short code. On a desktop your browser opens on that page. Sign in with Google there, and the terminal goes on by itself.

Over SSH (or with RUGLY_NO_BROWSER set) nothing opens. It says open that link on any device. Open it on your laptop or your phone, type the code, and sign in.

An invite code works too. Run the installer as … | RUGLY_INVITE=<code> sh, or use ruggly login --invite <code>.

  • ruggly whoami shows the account this device is signed in as.
  • ruggly logout signs this device out.
  • ruggly upgrade opens checkout for Pro in your browser, and ruggly billing manages your plan.

✦ 03 / the keys

Ten keys that matter.

ruggly opens in NORMAL mode, where letters are commands. You type text in INSERT mode.

normal mode
  • iStart typing at the caret. a types after it.
  • EscBack to NORMAL. In NORMAL it cancels a selection, a search or a half-typed key.
  • eOpen the format bar. Type plain words in its ✦ field and press Enter (see AI).
  • uUndo the last change, AI edits too. ctrl+r redoes it.
  • KFind anything: a note, a heading, a tab, a bookmark or a command. So does ctrl+k.
  • TA new tab, on the new-tab page. There i or Enter starts a blank note.
  • XClose the tab, and its note is saved. U reopens it. H and L go to the previous and next tab.
  • MBookmark the selection. B opens every bookmark, by folder.
  • ?Show the keyboard shortcuts. space opens the command palette.
  • qQuit. What you typed is kept. Notes autosave, and s saves a draft now.

\ is the leader key. After \, g, z, d, c or y, a popup shows the keys that can follow.

Coming from vim? Put keys = vim in your settings. vim's letters then do what vim does, and ruggly's commands on them move behind \: \ e is the format bar and \ K the launcher.

✦ 04 / settings

One plain text file.

Settings live in ~/.ruggly/settings.txt (or $RUGLY_HOME/settings.txt), one file for every folder you work in. Write one name = value per line. # starts a comment, and on/off, yes/no and 1/0 all work.

# ~/.ruggly/settings.txt
keys = vim
update = off
settings.txt
  • keysruggly (the default) or vim.
  • autosaveKeep a draft of the note as you type. On by default.
  • startpage opens on the new-tab page, last on last session's note.
  • ai_previewon: an AI reply first opens a word diff. Off by default, so AI edits land straight in the note.
  • quietNo travel, glow, ghost or wall motion. On by default.
  • footer_hintsKeys along the bottom row. On by default.
  • updateoff stops the once-a-day check for a new version.
  • backupoff stops backing your notes up to your account from this computer, and bringing them back. On by default.

g s opens the settings screen, which changes the same file.

✦ 05 / deleting notes

Plain files. A day in the trash.

Your notes are .md files on your computer. ruggly doctor prints the folder they're in, so you can copy them or keep them in git.

Backup. While you're signed in, your notes also back up to your account a few seconds after you stop typing. Files you open from a project are never uploaded. Sign in on a new computer and your notes come back the first time ruggly starts. It isn't sync: two computers don't follow each other's edits. The privacy page says what is kept, and backup = off turns it off.

g X deletes the note you're in. It asks first: enter deletes this note, esc keeps it.

The trash keeps it for 24 hours. g u opens the trash and restores a note. After a day it's gone from this computer. A deleted note leaves your backup too: its text is off our server within 30 days. Another computer that already has the note keeps its copy.

✦ 06 / AI

Say it. One u takes it back.

Press e, type what you want in the ✦ field, and press Enter: make it red, h2, shorter and bold.

  • On your machine first. Words ruggly knows run right there, offline, and nothing is sent. That covers commands, colours, h1 to h3, links and go to a heading.
  • Everything else goes to our server and from there to the AI.
  • Straight into the note. An AI edit lands as one undo step, and the status line says Applied · u undoes it. To see a word diff first, set ai_preview = on.
  • Ask commands. Some commands can't be undone with u, or act outside the note. For those, your words fill in one line: Enter runs it, Esc drops it.
  • \ ? asks AI about the line the caret is on.

AI needs you signed in. If you're not, it says ✦ sign in first: ruggly login. The local commands work either way.

What the AI sees and keeps is on the privacy page.

✦ 07 / agents

Fix an agent's plan, then hand it back.

Claude Code shows its plan before it starts, and ctrl+g opens the plan in your editor. Make ruggly that editor, and the plan opens rendered, in the same terminal:

EDITOR='ruggly edit' claude

Fix it with the keys, or press e and say what to change: move the tests before step 2. u undoes it. Then close, and Claude goes on with your version. To have it every time, without changing the editor other tools open, put alias claude="EDITOR='ruggly edit' claude" in your shell's startup file.

in ruggly edit
  • qClose and hand the plan back. Nothing changed: the file is left exactly as it was.
  • sSave it now and keep editing.
  • \ ↵Hand back just the lines you selected. With nothing selected, a short version that fits the budget.
  • ↵On its own, does nothing here, so a plan is never cut short by accident.

Nothing is copied into your notes and nothing is backed up: the file is the agent's. If ruggly is closed any other way, the plan is left as it was. Codex and Pi open $EDITOR on ctrl+g too; we've tried it with Claude Code so far.

Plans in your notes, not stray files.

A coding agent can save its plans and notes in ruggly instead of writing .md files into your project. ruggly mcp is an MCP server the agent starts by itself, and it stops when the agent does. No ruggly window needs to be open. One line sets it up in Claude Code:

claude mcp add ruggly -- "$(command -v ruggly)" mcp --agent claude-code

For any other MCP client, the command is ruggly with the arguments mcp --agent <name>, where the name is the agent's.

  • Where they land. In agents/<name>/ in your notes, as ordinary notes you can open and edit. Inside a git repo that's the repo's own notes, so open ruggly in that repo to see them.
  • What an agent can do. Save a new note, add to one it saved, and list and read what's under agents/. It can't read your own notes, and it can't delete or overwrite anything.
  • Backup. Agent notes back up to your account like your own.

✦ 08 / troubleshooting

When something goes wrong.

Start with ruggly doctor. It checks the version, the server, the sign-in and the state folder, and prints where your notes and settings are.

what you see
  • ruggly is lockedThere's no pass on this machine, or it ran out. The screen gives the reason, and ↵ gets Pro, l signs in, q quits. Nothing is deleted. On the command line the same check exits with code 4 and names the command to run.
  • sign in firstRun ruggly login. ruggly whoami shows who you're signed in as.
  • no browser opensOver SSH that's on purpose. Open the printed link on any device and type the code.
  • copy over SSHruggly copies through your terminal (OSC 52). Inside tmux, turn on set-clipboard on and allow-passthrough on.
  • a new versionThe app says ruggly X is out: run ruggly update. Run it.
  • it closed after a bugYour note is stored. Details are in crash.log, in the state folder. Send it to us.

Where things live:

  • ~/.ruggly (or $RUGLY_HOME): your sign-in, your pass and settings.txt.
  • The state folder: inside a git repo it's the repo's .ctx, ignored by git. Elsewhere it's ~/.local/state/ruggly (or $XDG_STATE_HOME/ruggly). RUGLY_STATE_DIR picks another. Your notes are in its notes folder unless RUGLY_NOTES says otherwise.

Still stuck? Write to hello@ruggly.dev with what ruggly doctor printed.