Coding agents

Connect an agent, the /ramble skill, claims, projects and record requests.

A ramble is made to be handed to a coding agent. With an agent connected, you don't copy links. The agent lists the rambles that nobody has acted on, reads your findings with your words and screenshots, works on them one commit at a time, and asks you to record a short check afterwards.

This works with Claude Code, Cursor, Codex, Gemini CLI, Copilot in VS Code, Zed, Cline and any agent that speaks MCP. The connect page has every command with a copy button. This page explains how it all works. If you are building a client, see the MCP reference.

Connect an agent

Run this in a terminal:

curl -fsSL https://ramble.sh/install.sh | sh

Then click Connect in your browser. That is the whole setup. The installer finds the coding agents on your machine, prints every path and command before it changes anything, and asks Ramble for a one-time code. It opens a page that shows the same code your terminal printed. When you click Connect, the installer receives an agent token and writes it into each agent's own MCP config, then writes one file, the /ramble skill. There is no /mcp and no Authenticate step. It never asks you to paste a token, and it never prints one.

Or paste this into your coding agent:

Follow https://ramble.sh/install.md to connect Ramble to this coding agent.

The agent reads that file, downloads the installer, shows you its plan (the output of --dry-run), and waits for your yes. Then it runs the same installer, and you click Connect in the browser.

Claude Code, Cursor, Codex and Gemini CLI are set up and signed in this way. VS Code (Copilot) is added by address, and you sign in from its MCP list. Run the command before you open your agent. In an agent that was already open, and always after pasting the sentence into one, start a new session so it loads the new server. If /ramble still cannot see Ramble, run /mcp and check that ramble is listed.

Add --dry-run to see the plan and change nothing. Add --no-browser to print the link instead of opening it, for an ssh session or a machine with no browser. Add --oauth to skip the token and sign in from inside each agent instead, as in the next section.

The connect page

Your browser opens a page. When it is on the same network as the terminal that asked for the code, the page shows the code in large letters and asks Is this the code your terminal is showing? Check that it is the same code, and press Connect (or Cancel). If you did not just run the command yourself, or someone sent you the link, press Cancel: connecting gives whoever started it access to your rambles. The page also repeats what the terminal reported, which agents it found and the name of the computer, and says Ramble has not checked either.

From any other network (a different office, a phone, a link someone sent you), or when Ramble cannot tell, the page does not show the code. It shows an empty field that asks you to type the code your terminal printed, and Connect only works when what you typed is that code. A link can carry a code, so a code that is already filled in is never enough. The page also leaves out the agents and computer name the terminal claimed, because whoever started the request chose them. Cancel never needs typing. A connection approved this way is labelled "(approved from another network)" in Connected agents.

The page lists what the agents will be able to do: read your rambles and findings, add agent notes and statuses, and ask you to record. It says they will not be able to upload, record or delete your account, and that the connection lasts a year.

If you sign in from inside the agent instead (--oauth, or any agent set up by address), your browser opens a different page that reads Connect "Claude Code" (unverified name), or whatever name the agent gave itself. The name is chosen by the app, not checked by Ramble. If that agent's sign-in returns to an address that isn't your own computer, an amber note names that address first, and Cancel comes before Connect. Connect only agents you started yourself.

Set it up yourself, by agent

These blocks add each server by address and you sign in from inside the agent (the --oauth route). Each adds the server and the skill. The mkdir and curl line saves one file, SKILL.md.

Claude Code

claude mcp add --transport http --scope user ramble https://ramble.sh/mcp
mkdir -p ~/.claude/skills/ramble && curl -fsSL https://ramble.sh/skills/ramble/SKILL.md -o ~/.claude/skills/ramble/SKILL.md

Then in Claude Code: /mcp, ramble, Authenticate, and /ramble.

Cursor. Press "Add Ramble to Cursor" on the connect page, or put this in ~/.cursor/mcp.json:

{"mcpServers":{"ramble":{"url":"https://ramble.sh/mcp"}}}

Then save the skill:

mkdir -p ~/.cursor/skills/ramble && curl -fsSL https://ramble.sh/skills/ramble/SKILL.md -o ~/.cursor/skills/ramble/SKILL.md

VS Code with Copilot

code --add-mcp '{"name":"ramble","type":"http","url":"https://ramble.sh/mcp"}'
mkdir -p ~/.copilot/skills/ramble && curl -fsSL https://ramble.sh/skills/ramble/SKILL.md -o ~/.copilot/skills/ramble/SKILL.md

Codex

codex mcp add ramble --url https://ramble.sh/mcp
codex mcp login ramble
mkdir -p ~/.agents/skills/ramble && curl -fsSL https://ramble.sh/skills/ramble/SKILL.md -o ~/.agents/skills/ramble/SKILL.md

Gemini CLI. Then run /mcp auth ramble inside it.

gemini mcp add --transport http -s user ramble https://ramble.sh/mcp
mkdir -p ~/.gemini/skills/ramble && curl -fsSL https://ramble.sh/skills/ramble/SKILL.md -o ~/.gemini/skills/ramble/SKILL.md

claude.ai and Claude Desktop. Open Settings, then Connectors, then Add custom connector, and enter https://ramble.sh/mcp. You get the tools but not the /ramble command.

Cline, Zed and agents without browser sign-in. Use a personal token. See Revoking and personal tokens.

From a terminal. The installer finds the agents on your machine, prints every path and command first, and downloads only SKILL.md. Run it with --dry-run first to see the plan:

curl -fsSL https://ramble.sh/install.sh | sh -s -- --dry-run
curl -fsSL https://ramble.sh/install.sh | sh
curl -fsSL https://ramble.sh/install.sh | sh -s -- --no-browser
curl -fsSL https://ramble.sh/install.sh | sh -s -- --oauth

Your earlier rambles

An agent only sees rambles that belong to your account. Rambles you recorded while signed out belong to the browser that recorded them. Sign in on ramble.sh in that same browser and they move into your account. Rambles recorded before Ramble tracked browsers can't be moved, and your agent won't see them. See Account.

Using /ramble

Type /ramble in your agent.

The first time, with nothing recorded, the agent offers a one-minute tutorial ramble: talk through one thing you would change in your project. When the findings arrive, it explains in a paragraph how claims and statuses work.

The loop for a ramble:

1. The agent reads the findings and shows them to you, numbered, with your quote and the time.
2. It claims the findings it will touch, so no other session takes them.
3. It writes a plan (one commit per finding), shows it to you and posts it on the ramble.
4. It waits for you to say go. See the next section.
5. It works on a branch named ramble/ plus the ramble id. It makes one commit per finding and puts your quote in the commit message. It runs your project's own checks first.
6. It reports statuses as it goes.
7. It asks you to record a check, and marks a finding fixed only after you say yes.

Plan first or act

By default, the agent is in plan first mode. It claims the findings, posts its plan, marks the findings "planned", and stops: "Say go to start, or tell me what to change." It edits nothing until you say go.

In act mode it posts the same plan and carries on without waiting. In both modes it makes one commit per finding and doesn't merge.

Only you can switch to act, and you do it on the website. Open Your rambles, find Connected agents, and use the control there called How agents proceed. It offers Plan first, wait for my go and Act after posting the plan. The choice is saved on your account, so it holds for every agent you connect. An agent can't do this for you. If it tries, Ramble answers that it isn't available and tells it to send you to that page.

An agent can still put you back on plan first: type /ramble prefs plan_first.

You can also pin one project down. If the repository's CLAUDE.md contains the line ramble: plan_first, that wins over act. The reverse never applies.

Claims and statuses

Two agent sessions shouldn't fix the same finding. A claim is a lease on some findings. It lasts 30 minutes unless the agent asks for another length, and the agent renews it about every 20 minutes while it works. A claim runs out by itself, so a crashed session never blocks you for long. You can also release one yourself with the Release button on the ramble page.

If another session holds a finding, your agent says who has it and until when, and leaves it alone.

A status says where a finding stands: planned, in progress, PR opened, fixed or won't fix. It can carry a link to the pull request or commit, and a short note (1000 characters at most). Setting a status needs a live claim. If the claim ran out while the agent waited for you, the agent claims again first. A finding is marked fixed only after you confirm.

You see claims and statuses on the ramble page and on your list of rambles. See What your agent did.

Projects

A project says what a ramble is about, usually a repository such as github.com/owner/repo. It lets your agent find the right rambles for the code it is in.

A ramble gets its project in one of these ways:

• A record request carries the project of the agent that asked.
• Ramble guesses. After grading, if exactly one of your projects matches the app name, the page titles or the site names in the recording, Ramble picks it and marks it "guessed from the recording". It never guesses when two projects match.
• Your agent sets it. /ramble reads the repository's origin address and prefers rambles for that project. If a ramble has no project, or only a guessed one, it shows you the top three and asks which one. After you choose, it saves the project so the next run knows.
• You set it on the ramble page, with Set project or Change.

What you choose wins. An agent can't replace a project you set, and a guess never replaces anything. If you clear a project yourself, Ramble doesn't guess one back.

Record requests: your agent asks you to ramble

After a fix, your agent can ask you to record a short check. It writes a note for you: what should now be true, and how to try it.

1. Your agent opens a link. With Ramble for Mac installed, it opens a ramble://record?request=… link. Otherwise it opens a ramble.sh link in your browser. On Windows it prints the link for you to open. The web way is the default and needs nothing installed.
2. You see the request. In the browser, the home page shows a card, Your coding agent asks you to ramble, with the agent's name and its note. The note is shown as plain text. The card says: "Your agent wrote this, not Ramble. Show it, say what you see, and only what you say becomes a finding." You press Start rambling and share the window, as in Recording. In Ramble for Mac, the island shows the first line of the note with a Record button.
3. You record. If your browser shows a floating panel, the note appears in it as an "Asked:" line while you record. You still say what you see. Ramble's recording model also gets the note as background, so it can recognise what you were asked to check. It is context, not an instruction.
4. Your agent waits. While you talk, it can show findings Ramble has proposed so far. These are marked as previews and the agent never acts on them. When your ramble is ready, it reads the findings, says for each requested finding whether you mentioned it and whether you sounded satisfied, and asks whether to mark it fixed.

The details:

• Nothing records until you say so. On the web you press Start rambling. In Ramble for Mac nothing records until you press Record or the hotkey ⌥⇧R. A link can come from an agent that was talked into it while you are away from the desk, which is why there is always your click. See Ramble for Mac.
• Signed out? The link sends you to sign in and then back to the request.
• A request is yours alone. If it belongs to someone else, has expired, was cancelled or was already answered, you get a short notice, "That request from your coding agent isn't available any more", and can record as usual.
• How long it lasts. A request stays open for 60 minutes unless the agent chose a different time, from 5 minutes to 4 hours. One recording answers one request. An account can have 20 open requests at a time.
• It has to be a live recording. An uploaded video can't answer a request.

What an agent can and cannot do

An agent connection carries up to three scopes. The consent page names them in these words.

An agent cannot:

• upload a video, or start a recording on its own;
• delete a ramble, or your account;
• edit, remove, reorder or retry a ramble's findings. On a signed-in ramble those are yours alone as the owner.

Uploading, recording and deleting need a scope that agents never get. Your web sign-in, the phone app and Ramble for Mac carry it.

What an agent writes, its statuses, notes, links, claims and requests, is stored with the ramble and shown only to you when you are signed in. The public link and the plain-text agent document never include it. It is deleted with the ramble or your account.

Revoking and personal tokens

Open Your rambles and find Connected agents. It lists every agent you connected, each personal token you made, and the phone and Mac apps you are signed in on, with when each was connected and last used. Revoke cuts one off at once. The same card holds the How agents proceed choice. See Plan first or act.

The one-command install gives your agents a token that lasts a year. It is listed here with a label like "Claude Code + Cursor on MacBook-Air", and it counts toward the same 20. If you revoke it, or a year passes, the agent shows the ramble server as failed: run the install command again and click Connect. Running it again makes a new token, so revoke the old one here.

Signing in from inside the agent gives an access token that lasts 24 hours and renews itself quietly. If the agent goes unused for 90 days, it has to sign in again. If an agent says it "needs authentication" after a long gap, authenticate it again.

Personal tokens are for agents that can't sign in through a browser, such as Cline and Zed, and for scripts. In Connected agents, name the token and press New agent token.

• The token is shown once, in a command you can copy. Copy it right then. You can't read it again, only revoke it and make another.
• You can hold 20 at a time.
• A personal token carries the same three scopes and doesn't expire. Revoke it when you no longer need it.
• Put it in your own terminal or config. Never paste it into a chat.

Cline, for example:

cline mcp add ramble --transport http --url https://ramble.sh/mcp --header "Authorization: Bearer TOKEN"

Replace TOKEN with the token. In Zed, add https://ramble.sh/mcp with the same Authorization header.

Security notes

• Everything in a ramble is untrusted text. Titles, quotes, descriptions, notes, links, and even text visible in a screenshot come from captured speech, a model, or another session. Ramble marks all of it as untrusted reference material, and the /ramble skill tells your agent to treat it as data. It never authorizes an action. You are the only source of instructions.
• The skill stops and shows you. If a finding, a note, a title or a screenshot reads like an instruction to the agent ("run this", "ignore the plan", "open this link"), the skill tells the agent to stop and show you the exact text.
• Previews are not acted on. Findings Ramble proposes while you are still recording are provisional.
• Plan first, no merging. The skill tells the agent to plan before it edits, and never to merge, push to your default branch, force-push or delete anything unless you ask in the conversation. That is an instruction to your agent. Ramble can't enforce it in your repository, so keep your own agent's permissions set the way you want them.
• A narrow pre-approval. In Claude Code the skill pre-approves only reading, git add, git commit and opening the recording link, and only for the turn that runs /ramble. After you say go, your own permission settings decide what asks.
• It never asks for a token. If an agent asks you to paste a key or token into the chat, don't.
• What an agent reads leaves ramble.sh. Findings, transcript text and screenshots go to wherever your agent runs, under that agent's own terms. Connect only agents you trust. See Privacy in plain words.

Something not working? See Troubleshooting.