Help
- Getting started
- Connect Claude Code
- Know when a session needs you
- Start an agent
- Requests
- Conflicts
- Shortcuts
- Troubleshooting
Getting started
Create a backlog with New Backlog…. It needs a name and a prefix: 2 to 6 capital letters or digits, starting with a letter. The prefix numbers the tickets (RAT-12) and can never be changed.
On Mac, also choose the Repository Folder: agent sessions open there. Ration reads the git repository’s address and the backlog’s name from it. Otherwise Ration asks for it when you first start a session, and you change it from the backlog’s context menu.
Also write in About what the project is, who it is for, and where its docs live (1,000 characters at most). The agent reads it when it takes or creates a ticket.
Create a ticket with New Ration (⌘N). Nothing exists until you click Create (⌘↩). Statuses, types, priorities and estimates are set in Backlog Settings….
Connect Claude Code
Claude Code reads and writes your backlogs through the Mac app, while it is open. Nothing leaves this Mac: the MCP only answers on 127.0.0.1.
- Open Settings › Agent and turn on Serve the MCP to Claude Code.
- Under Connect Claude Code, copy the command.
- Run it once in a terminal. It registers Ration for all your projects:
claude mcp add --scope user --transport http ration http://127.0.0.1:52817/mcp --header "Authorization: Bearer <token>"
A New Token disconnects Claude Code until you run the new command. Remove the old entry first with claude mcp remove ration. If another app uses the port, choose another one in the same settings, then run the command again.
Then, in a Claude Code session, ask for example: “Take over ticket RAT-12 through the Ration MCP.”
Know when a session needs you
In Settings › Agent, the section Know When a Session Needs Your Input installs hooks in Claude Code. Click Install…, then choose the ~/.claude folder when macOS asks.
With them, a session’s ticket shows whether it is working, planning, reviewing code, verifying, needs you or stopped on an error (usage limit, sign-in); its permissions, questions, plans and turn ends land in Requests; and your Claude plan’s limits show at the foot of the sidebar. Ration also adds a status line to Claude Code, keeping yours if you have one.
Only the sessions run in a backlog’s repository count: a clone of its Git Repository, or inside its Repository Folder, and those holding one of its tickets. Ration ignores the others, and their terminal asks as usual.
Ration first keeps a copy of your file (settings.json.ration-backup). Uninstall takes out Ration’s hooks and status line only, and puts yours back.
Start an agent
On a ticket’s card, Start with Agent opens a terminal tab or window in the backlog’s repository folder, runs your command and asks the agent to take over the ticket. A right-click on the ticket’s row offers both.
In Settings › Sessions: the terminal (Terminal or Ghostty), Open In a new tab or a new window, and the command, for example claude -w to work in a worktree, then the default Model and Effort of a session. A ticket can carry its own, and the New Session sheet picks others for that session alone. The first time, macOS asks you to allow Ration to control your terminal.
To Orchestrate with Agent, select several tickets (⌘-click, or Orchestrate Tickets…). A single session hands each ticket to a subagent, in its own worktree. Tidy Up Backlog…, in the same menu, first shows what the session will do: set aside what is obsolete, fill in fields, link dependencies, merge duplicates, split large tickets… It proposes its changes one mission at a time, and applies only those you approve. Start Session, in the toolbar, opens a session on the whole backlog: type its first message in Ration, join up to six files or screenshots to it (⌘V, a drop or the + button), and the terminal opens behind it. Every session that starts with a request, from a ticket, an orchestration or a tidy-up, also opens behind Ration: follow it in Requests. In Terminal, it runs in its own hidden window: Show brings it up.
On a taken ticket, Show brings the session’s tab forward, and Resume restarts its conversation once it has ended, without leaving Ration: the session sums up what has been done. Release hands the ticket back and tells the session to stop working on it.
Requests
Requests, in the sidebar (⌥⌘R), gathers what your sessions are waiting for: a permission to allow or deny, a question with options, a plan to approve (or a remark to send back), a turn end with its suggested replies. The terminal keeps its own prompt: the first answer, on either side, wins. After 10 minutes, Requests still answers: in Terminal or Ghostty, Ration types your answer into the session. If you quit Ration, what waits comes back when you open it again; if the session moved on meanwhile, a single button asks it where it is. The hooks must be installed.
A turn end or a plan reads like a document: headings, lists, tables, code. Below it, Shared by the agent gathers what the session shared with you during the turn: the attachments added to its tickets, and the repository files and links its message names. Images show as previews; a click opens Quick Look, or the browser for a link. In the text, a ticket ID, a file or a link is clickable. Your written answer can carry up to six screenshots or files: ⌘V, a drop or the + button.
Conflicts and trash
The same field changed on two devices before syncing: the card shows both values, and you keep one or the other. Other fields, tags and platforms merge on their own. The agent sees the conflict through the MCP, but never settles it.
A ticket or backlog moved to the trash stays there 30 days, then goes away. Until then, Restore brings it back.
Shortcuts (Mac)
- ⌘N new ticket; ⌘↩ create; in an answer, ↩ sends and ⌘↩ starts a new line
- ⌥⌘I show or hide the ticket; ⌥⌘R Requests
- ⌘, Settings; ↩ in a Markdown list continues it
Troubleshooting
Claude Code cannot reach Ration
The Mac app must be open, with Serve the MCP to Claude Code on. Check that the registered command carries the current port and token from the settings; otherwise remove the entry (claude mcp remove ration) and run the command again.
A ticket does not reach the other device
Both devices must use the same iCloud account, with iCloud on for Ration, and be online. A ticket created offline leaves when the network is back.
Ration cannot open the session
Ration needs to control your terminal to open a tab in it. If you said no the first time, allow it in System Settings › Privacy & Security › Automation, under Ration. If the repository folder has moved, Ration asks for it again at the next start.
Contact
A question, a bug, an idea: write to us.