How to connect Splitwise to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Splitwise from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Splitwise tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Splitwise call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

In Splitwise language, the two real causes are: the group or expense belongs to a different Splitwise account, and a write-versus-read scope gap. The first is the common one: an agent handed a group id from documentation, a screenshot, or another account calls a real tool with an id that is not yours, and Splitwise answers with a permission error because it hides what the account cannot see. The second is a grant made with read scope for a write call, which a disconnect and reconnect from the dashboard re-issues. Both look identical from the caller's side, so run the diagnosis in order: confirm which account the connection acts as, list the groups you can actually see, then reconnect only if the id checked out.

Ask the agent to diagnose it:

Call splitwise_get_current_user and splitwise_get_groups. Tell me which Splitwise account this connection acts as and list the group ids it can see, then quote the exact error from the failed call. Do not retry it yet.

Splitwise's limits are undocumented and dynamic, and 429 is the only signal they publish. An agent paging through every expense in a long history, or walking group by group and expense by expense in one burst, is the shape that meets them. The fix is shape, not retry: ask for one group's recent expenses rather than the full history, have the agent say what it intends to read before it starts, and treat a 429 as wait-out-the-window rather than a retry trigger.

Ask the agent to diagnose it:

Tell me how many Splitwise calls you have made recently and what you were reading. Quote any 429 text from the last response. Do not call Splitwise again until I reply.

The fixes search results teach for this symptom assume a local server: absolute paths in claude_desktop_config.json, SPLITWISE_API_KEY in a .env file, a Developer: Reload Window in Cursor. None of that exists here. If Hermes shows no Splitwise tools at all, confirm the plugin was installed with --enable, that both hermes clawlink begin and hermes clawlink finish ran, and that Splitwise shows as connected in the dashboard, then start a fresh chat. If most tools work and a single name fails, the name is wrong rather than missing, and the error lists the closest real ones. One timing case is unique to this setup: schemas load on demand, so the opening Splitwise call in a fresh session can arrive before the catalog and needs one retry.

Ask the agent to diagnose it:

List the Splitwise tools you actually have access to. If there are none, say so plainly. If there are, tell me which one lists groups and use that exact name.

Try reconnecting Splitwise and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Splitwise: link your Splitwise account once in the browser and Hermes Agent can call the Splitwise API through 27 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Splitwise in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Splitwise in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Splitwise working from chat.

No. The 7-step walkthrough search results teach, register an application at secure.splitwise.com/apps, click Create API key, copy the long token, is the self-hosted route's prerequisite, and even the community MCP servers that win "best" roundups still require a free personal token. This connection uses OAuth: you approve Splitwise's sign-in in the browser and any token lives server-side. The honest framing Google itself uses: an AI agent cannot run with no API access at all, but you can skip creating a developer API key entirely, which is exactly what this page's setup does.

The shared-expense surface: list and read groups, expenses, friends, comments, categories, currencies, and notifications, and create expenses, groups, friends, and comments, add users to groups, update expenses and users, and undelete expenses and groups. The reads answer most questions without writing anything. The writes are social and real: creating an expense or a comment lands in a group everyone sees, so those are the actions to say explicitly before the agent proceeds. An agent that reads the split history of a group can answer "who owes what" without touching anything.

Yes, with the right context. splitwise_create_expense creates an expense, and the creation tools for groups and friends exist alongside it. The practical rules: an expense belongs to a group, so the agent needs the group id (from splitwise_get_groups) and the split arrangement for the amount, and it needs to say how the cost divides before it creates anything. Creating an expense on a group posts it to everyone in that group, so a draft-and-approve step in the prompt is the habit that keeps shared records clean.

The mechanics: the OAuth token lives server-side, the tool table on this page is the complete set of operations the agent can invoke, and revoking from the dashboard cuts access immediately. Splitwise data is household-sensitive rather than corporate-sensitive, and the read surface dominates the toolkit, so most agent work never writes. The user-side levers are yours: connect the account that should see the groups the agent works on, keep expense creation draft-and-approve, and remember that a comment created on a group is visible to everyone in it.

Splitwise's API limits are undocumented and dynamic, and the market's read is that they are lenient enough that almost no integration has ever exceeded them. That cuts both ways: you are unlikely to be throttled, but there is no published number to plan around, and a 429 still means stop and wait rather than retry in a loop. An agent paging through a long expense history or walking every group in a sweep is the shape most likely to meet an undocumented limit, so keep enumerations scoped.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.