getriff

Collaboration in the place where work actually happens. Message your team, write specs, make decisions — all without leaving your AI agent.

How It Works

Riff is an MCP server that connects AI agents — Claude Code, Claude Desktop, Gemini CLI, Codex CLI. You speak intent, your agent handles the message. Every message carries context — what you meant, not just what you typed. When someone reads it next month, the reasoning is still there.

You: "riff @alice — the auth migration is done, she can start on the frontend"

Your agent → composes message with relevant context
         → sends via riff server
         → Alice's agent picks it up in her next session

You: "check my riffs"

Your agent → fetches new messages
         → summarizes what needs your attention
         → drafts replies for your approval

No tab-switching. No composing. No losing your place in the code.

Use with Claude Cowork

Cowork users don't need the CLI at all — Riff connects as a custom MCP connector.

1. In Cowork, open Settings → Connectors → Add custom connector.
2. Paste this URL (exact, no trailing slash): https://app.getriff.org/mcp
3. Click Add. Cowork opens a Riff sign-in window.
4. Sign in with Google or GitHub, then click Allow on the consent screen.

That's it. All Riff tools (DMs, groups, specs) are now available to your Cowork agent. To disconnect: revoke the device at app.getriff.org → Devices, or remove the connector in Cowork.

Quick Start (CLI — Claude Code, Claude Desktop, Gemini CLI, Codex CLI)

npx getriff login

That opens your browser, signs you in, and auto-configures every AI agent it finds on your machine (Claude Code, Claude Desktop, Gemini CLI, Codex CLI). Credentials land in ~/.riff/keys/{host}/credentials.json at mode 0600.

Headless box with no browser?

npx getriff login --device-flow

Self-hosted server?

npx getriff login your-server.com

Then in a new agent session:

"check my riffs"
"riff [email protected] — the API changes landed, ready for review"

Groups

DMs are one-to-one; groups are many-to-many. Same primitives, same agent-mediated flow.

You: "make a group called 'backend' with alice, bob, me"
You: "riff @backend — staging deploy is green, I'm cutting the release"
You: "check my group inbox"

Web UI

app.getriff.org is the same backend with a browser front-end — DM inbox, threads, spec editor, attachments. Useful for teammates without an AI agent, for formatted reading of long spec threads, and as the destination getriff login opens when it redirects for OAuth.

The agent-mediated flow is the primary workflow; the web UI is the fallback.

Specs

When a conversation needs more structure than a message thread, escalate to a spec — a collaborative document where agents propose changes, open discussions, and resolve disagreements. Think pull requests for planning.

You: "create a spec for the auth migration plan"
You: "enter spec mode for auth-migration-a7f3"
You: "open a discussion — I think we should use JWT instead of sessions"

• Discussions as PRs — propose changes, debate, resolve
• Full version history — every edit snapshots, rollback to any version
• Optimistic concurrency — no silent overwrites, conflicts return diffs
• Finalization — lock the spec, export with resolved decisions and open items

Troubleshooting

My agent doesn't see new messages. MCP config loads once per session. Start a new agent session after login — or after new messages arrive, if you've been idle a while.

Browser didn't open / I'm on a headless box. Use npx getriff login --device-flow — prints a code you enter on another device.

I want to point at a different server. npx getriff login your-server.com — credentials are stored per-host, so you can have multiple logged in at once.

I want to start over. Delete ~/.riff/keys/{host}/ and re-run npx getriff login.

Cowork: "Add custom connector" rejects the URL. Make sure it's exactly https://app.getriff.org/mcp — no trailing slash, https:// scheme.

Cowork: sign-in popup doesn't appear. Your browser is blocking popups for claude.ai. Allow popups, then retry.

Cowork: tools don't show up after connecting. Check Devices — if the device exists but Cowork isn't seeing tools, revoke it and add the connector again in Cowork.

Cowork: lost access unexpectedly. Someone revoked the device on the Riff side, or Anthropic re-registered the connector. Remove and re-add the connector in Cowork → Settings → Connectors.

Support

Questions or issues: email [email protected]. Developers can also file issues at github.com/getriff/riff (if that's where this repo lives).

License

MIT