Claude Code plugin

The Rius plugin for Claude Code turns each Claude Code session into a trace in Rius. The trace holds your prompts, every model call with its tokens and cost, every tool call, and the subagents Claude Code started, laid out as a waterfall. The plugin also connects the Rius MCP server, so you can ask Claude about those sessions without leaving the terminal.

Setup takes four commands: two to install, one to sign in, and one to pick a folder to trace. Querying your sessions from Claude Code takes one more sign-in, in /mcp. The 5-minute walkthrough runs the whole loop. Rolling it out to a team? See Track Claude Code usage and cost across a team.

A folder you enable sends structure only: the span tree, models, tokens, cost, timing, tool names, and error types, with no prompts, replies, file contents, or command output. To send content too, enable the folder with /rius:enable-content-here. Everyone with access to the workspace can read what is sent; see what gets captured.

Try it in 5 minutes

The whole loop, end to end. Each step links to the section with the details.

1. Install. In a terminal, run claude plugin marketplace add glassflow/rius-coding-agents && claude plugin install rius@rius-coding-agents. See Install to install from inside Claude Code instead.
2. Sign in. Run /rius:login. In the browser, sign in (or sign up), pick a workspace or create one, and click Connect. See Sign in.
3. Turn tracing on. cd into a repo, then run /rius:enable-here and /rius:status. The first line should read Rius tracing: on. See Choose which folders are traced.
4. Work as usual. Ask Claude Code to do something real in that repo. Then open the trace list at console.rius-glassflow.com and find the session. See What you see in the console.
5. Ask about it. Run /mcp, pick rius, and sign in with your Rius account. Then ask Claude “list my recent Claude Code sessions in Rius”. See Query your sessions.
6. Turn it off for a folder. Run /rius:disable-here. Nothing more from that folder reaches Rius; a session already running just closes its trace when it ends. See Disabling a folder mid-session.
7. Sign out. Run /rius:logout. The key is revoked, and it stops working everywhere within about a minute. See Sign out.

Steps 2 and 3 in a real terminal, signing in, enabling a folder, and checking the state:

Requirements

• Claude Code with plugin support.
• Python 3.9 or later on your PATH. The plugin uses only the standard library and installs nothing from PyPI.
• macOS, Linux, or Windows. On Windows the hooks run through Git Bash, which Claude Code already uses for its Bash tool.

You don’t need a Rius account yet. You can sign up during /rius:login.

Install

Run this in a terminal:

claude plugin marketplace add glassflow/rius-coding-agents && claude plugin install rius@rius-coding-agents

Or install from inside Claude Code. Run the two commands one at a time: pasting both together fails, because Claude Code reads the whole paste as one command.

1. Add the marketplace:

   /plugin marketplace add glassflow/rius-coding-agents

2. Install the plugin:

   /plugin install rius@rius-coding-agents

3. Load it into the running session:

   /reload-plugins

Installing sends nothing. Tracing stays off for every folder until you enable one.

Sign in

/rius:login

Claude Code prints a link and a short code, and opens the Rius portal at console.rius-glassflow.com in your browser. Over SSH, or on a machine with no display, no browser opens: open the printed link on any device and check that it shows the same code.

1. Sign in, or sign up if you don’t have an account yet.
2. Check that the page shows the same code, and the name of the machine you ran the command on. The page reads Claude Code on <machine> wants to connect. Only continue if you just ran /rius:login yourself.
3. Choose the workspace this machine sends sessions to. It can be a workspace you own, or one you are only a member of.
4. Click Connect. If you are a member rather than an admin of the organization, the page reminds you that its admins can see these sessions.

Back in Claude Code, the plugin reports where it landed, one line for each sign-in:

Connected as you@example.com → eng-shared (Acme).
Tracing: signed in as workspace eng-shared (Acme)
Querying traces: run /mcp and sign in to rius
Trace this folder (/Users/you/code/app)? Run /rius:enable-here.

The sign-in link expires after 15 minutes. If it does, run /rius:login again.

The key the plugin stores

Signing in mints one API key for this machine and the workspace you chose:

• It only sends traces: it carries the ingest scope and nothing else. Querying your traces is a separate OAuth sign-in; see Query your sessions.
• It expires after 90 days. Run /rius:login again to get a new one.
• It is stored in ~/.claude/rius/credentials.json, readable only by you (mode 0600). It never goes into Claude Code’s settings files, which tend to get committed and shared.
• It is listed under Settings → API keys in the console as Claude Code: <your email> (<machine>). A workspace admin can revoke it there like any other key. Removing you from the organization, or taking away your access to the workspace, revokes it too.

Running /rius:login again replaces the key and revokes the old one. If you pick a different workspace the second time, every folder you have enabled sends to the new workspace from then on, and the plugin says so.

Traces sent with this key show you in the Sent by column of the trace list, so teammates sharing a workspace can tell whose sessions are whose. Every span also carries user.id, set to the email you signed in with, so your sessions appear under your name on the Users page. Nothing in the environment can change it.

Choose which folders are traced

Tracing is off everywhere until you turn it on for a folder. In the folder you want traced:

/rius:enable-here

That folder and everything under it is traced, structure only. To also send prompts, replies, file contents, and command output from the folder, with the secrets the plugin recognizes removed, run this instead:

/rius:enable-content-here

Only you can run either command: Claude can’t run them for you, and a repository’s settings can’t turn tracing on. A session that is already open when you enable its folder is traced from its start: everything said earlier in that session is sent too. To trace only from now on, start a new session after enabling.

To stop tracing a folder, including one inside an enabled parent:

/rius:disable-here

The rules live in ~/.claude/rius/config.json and apply to every Claude Code session on the machine. A disabled folder always wins, at any depth: you can enable ~/code and still keep ~/code/client-secrets out. The reverse doesn’t work. Enabling a folder inside a disabled one leaves it off, and the plugin tells you which folder to enable instead.

Disabling a folder mid-session

If you run /rius:disable-here while a traced session is open, nothing that happens after that point is sent. When the session ends, the plugin still closes its trace, sending only the structure of what was open (no prompts, replies, or tool content), so the trace is complete and counts on the Agents and Users pages. The stop is final for that session: enabling the folder again doesn’t resume it. The next session in the folder follows the folder rules as usual. /rius:status shows a Stopped: line for a session in this state.

For a one-off exception that doesn’t touch the folder rules, /rius:off stops tracing for the current session only. Like disabling the folder, it is final once the session’s trace has started: /rius:on only helps if you ran /rius:off before the first prompt. A new session starts without the override.

Check the state

/rius:status

/rius:status shows whether this folder is traced and which rule decided it, whether content is sent, the account and workspace the key belongs to, how to sign in for querying, and how many spans this session has sent so far. After /rius:login it reads:

Rius tracing: on
Reason: on: path rule '/Users/you/code/app' enables /Users/you/code/app
cwd: /Users/you/code/app
session: 0f1d9c2e-…
Endpoint: https://ingest.eu.console.rius-glassflow.com
Tracing: signed in as workspace eng-shared (Acme)
Querying traces: run /mcp and sign in to rius
API key: ri_…
Key from: /rius:login
Rule: `/Users/you/code/app` enables this folder
Content: none (structure only)
Signed in as: you@example.com
Workspace: eng-shared (Acme)
Key expires: 2027-01-11
Spans exported this session: 12

Content: reads none (structure only) for a folder enabled with /rius:enable-here, and prompts, replies, file contents and command output for one enabled with /rius:enable-content-here.

Each session also starts with one line from Rius, so you know whether it is traced without asking, for example Rius: tracing this session to workspace eng-shared (content: off).

If you disabled this folder earlier in the session, the first line reads Rius tracing: off and a Stopped: line follows Reason; see Disabling a folder mid-session.

Send a prompt or two, then open the trace list in the console. The session’s spans show up there while it is still running. The counts on other pages wait for the session to end; see What you see in the console.

What you see in the console

• Traces. Each session appears in the trace list while it runs, and its spans fill in as Claude Code works. The session itself shows as in progress until you exit Claude Code, which closes it. With content on, the trace is named after the session: the name you gave it with /rename or --name, or else the title Claude Code generates from your first prompt. Rename a session while it runs and the trace name follows. A session that sends structure only names the trace claude-code session.
• Agents. While a session is open, the Agents page shows it as a live instance of an agent named claude-code (or your RIUS_SERVICE_NAME), from the plugin’s heartbeat. The agent’s trace, error, and cost figures only count a session once it has ended. A session that never ends cleanly, because Claude Code crashed or was killed, never counts there. A session started before its folder was enabled sends no heartbeat, so it doesn’t appear under Instances. A session whose folder you disabled while it was running still counts once it ends: see disabling mid-session.
• Users. Each session lands on the Users page under the email you signed in with at /rius:login. Sessions sent with a key stored by use-key (see Use an existing API key) carry no user, and land in the anonymous row. The Sent by column in the trace list names the owner of the key either way.

What gets captured

One Claude Code session is one trace, with the same session id throughout. If you resume a session, it continues the same trace.

AGENT   the session
└─ CHAIN  a turn: one prompt and everything it caused
   └─ LLM   a model call: model, input and output tokens, cache reads
      ├─ TOOL  a tool call: Bash, Read, Edit, and so on
      └─ TOOL  Agent: the call that started a subagent
         └─ AGENT  the subagent, named by its type
            └─ LLM   the subagent's own model calls and tools

Subagents get their own spans with their own tokens. That matters on cost: in long sessions, subagents can account for more than half of all tokens. Turns that Claude Code injected itself, such as a slash command’s output or a background task’s report, are kept but marked as system turns, so you can tell them apart from what you typed.

With content on, the plugin replaces the secrets it recognizes with a marker such as [redacted:aws-key] before export: cloud, GitHub, Slack, Stripe, OpenAI, Anthropic, and Rius keys, JWTs, private keys, password= style values, and Authorization headers. The output of a read of .env*, key, and credential files is replaced whole. This is best effort: a secret in a format the plugin doesn’t know is sent. Each captured value is capped at 32 KB and marked where it was cut, so one large file read doesn’t break the export.

Content capture is decided on your machine, before anything is sent. The plugin contacts three hosts and nothing else: the ingest endpoint ingest.eu.console.rius-glassflow.com, the MCP server mcp.eu.console.rius-glassflow.com (only when you use the Rius MCP tools), and the sign-in host connect.console.rius-glassflow.com, which /rius:login and /rius:logout use.

Model-call durations are approximate. Claude Code’s transcript records when a reply finished but not when the request went out, so a model span’s duration can include time you spent reading or approving a permission prompt. Tool durations are exact.

Turn content capture off

To stop one folder sending content, run /rius:enable-here in it: the folder then sends structure only. To turn content off everywhere, whatever each folder chose, set RIUS_CAPTURE_CONTENT to false in the env block of a Claude Code settings file. The variable can only lower capture: true is ignored. For every project on the machine, use ~/.claude/settings.json:

{
  "env": {
    "RIUS_CAPTURE_CONTENT": "false"
  }
}

For one project only, put the same block in that project’s .claude/settings.local.json. Restart Claude Code after the change. You keep the full structure, models, tokens, cost, and timing, and lose the text of prompts, replies, and tool inputs and outputs.

Turning capture off applies to what is sent from then on. Traces already in the workspace keep their content.

Query your sessions from Claude Code

The plugin brings the Rius MCP server with it, registered as rius and fixed to https://mcp.eu.console.rius-glassflow.com/mcp. It signs in with Claude Code’s own MCP OAuth, separately from /rius:login, whose key only sends traces:

1. Run /mcp.
2. Pick rius.
3. Sign in with your Rius account in the browser.

Claude Code keeps the token. The sign-in reaches every workspace your account can, so name the workspace in your question when you have more than one.

Then ask in plain language:

• “Which of my Claude Code sessions in the last 24 hours cost the most, and what did the tokens go on?”
• “Show me my last failed session and which tool call went wrong.”
• “How much did subagents cost me this week compared with the main session?”

The tools reference lists everything the server can answer. If you already added the server by hand from the MCP page as glassflow, both entries work; remove one in /mcp if you only want one.

Sign out

/rius:logout

This revokes the key on the server and then deletes it from your machine. Rius services cache keys briefly, so a revoked key keeps working for up to about a minute. If Rius can’t be reached, the plugin still signs you out locally and tells you the key stays valid until it expires. Ask a workspace admin to revoke it under Settings → API keys.

Signing out doesn’t delete traces already sent, and doesn’t remove your folder rules. With no key, tracing is off everywhere.

Signing out while a session is running removes the key that session was using, so the plugin can’t close its trace when it ends. That session stays in the trace list as in progress, and never counts on the Agents or Users pages.

To remove the plugin:

/plugin uninstall rius

Folder rules, logs, and the stored key live in ~/.claude/rius/ and survive an uninstall. Delete that directory for a clean slate:

rm -rf ~/.claude/rius/

Use an existing API key

/rius:login is all most people need. To trace with a key you created yourself under Settings → API keys, with Send telemetry (ingest), store it with the plugin’s use-key command. It reads the key from stdin, so the key never lands in your shell history:

pbpaste | bash <plugin>/scripts/rius_ctl.sh use-key

<plugin> is the installed plugin’s folder, for example ~/.claude/plugins/cache/rius-coding-agents/rius/<version>. The key goes into ~/.claude/rius/credentials.json, the same file /rius:login writes, and replaces (and revokes) the key stored before. In /rius:status, Key from: /rius:login then reads Key from: rius_ctl.sh use-key, the Tracing: line reads Tracing: using the key from rius_ctl.sh use-key, and the Signed in as:, Workspace:, and Key expires: lines are gone. A key stored this way is often shared, so the plugin sends no user.id with it.

RIUS_API_KEY, RIUS_ENDPOINT, and RIUS_ENV in the environment are ignored, and /rius:status prints a line for each one that is set: honoring them would let a repository you clone send your sessions to its own workspace, or your key to its own server.

No key reaches the bundled rius MCP server: it signs in with OAuth. To query with a key instead, for example on a machine without a browser, add the MCP server yourself under its own name, glassflow, with a key that carries Query data (read), as on the MCP page:

claude mcp add --transport http glassflow https://mcp.eu.console.rius-glassflow.com/mcp \
  --header "Authorization: Bearer ri_..."

Environment variables

The environment can only turn things off: it cannot turn tracing on, turn content capture back on, or choose the key or the server. All of these are optional, set in the env block of a Claude Code settings file:

Troubleshooting

Start with /rius:status. A plugin that is installed but not enabled for this folder looks the same from the outside as a broken one, and the Reason line tells them apart:

When tracing is off for another reason and there is no key either, the line names both, for example off: no path rule matches <folder>, and the default is off; also no API key: run `/rius:login` . Fix both before expecting traces.

A Stopped: line under Reason means tracing was turned off for this session while it was running: a folder disable, /rius:off, or RIUS_CLAUDE_ENABLED=false. That session sends nothing more, even if the folder is enabled again, and Rius tracing reads off for it whatever the rules say. Its trace is still closed when it ends. Start a new session to trace again. The line reads:

Stopped: this session stopped tracing when its folder was disabled, and stays stopped even if the folder is enabled again. New sessions in this folder are traced as usual.

If tracing is on but Spans exported this session stays at 0, look for a Last export error line in the same output:

• HTTP 401 right after signing in. A new key can take up to about 30 seconds to reach the ingest endpoint. Send another prompt after a short wait.
• HTTP 401 or 403 later on. The key was revoked or has expired. Run /rius:login again.
• HTTP 402. The organization’s trial has ended, or the workspace or organization is paused or locked; see Plans and billing. The next session’s start line and /rius:status say so, and the notice clears after the next successful export.

If querying doesn’t work:

• /mcp shows rius as needing authentication, or the server answers 401. The bundled server signs in with OAuth, separately from /rius:login. Pick rius in /mcp and sign in with your Rius account.
• A server you added yourself with a key answers 403. The key has ingest but not read. Use a key with Query data (read). The key /rius:login stores never works here: it only sends traces.
• /rius:status says RIUS_API_KEY or RIUS_ENDPOINT is set but ignored. The plugin traces only with the key from /rius:login or use-key; see Use an existing API key.

If the plugin seems not to change after an update, Claude Code is still running its cached copy. Refresh it, one command at a time:

/plugin marketplace update rius-coding-agents

/reload-plugins

If the plugin can’t find a Python interpreter, /rius:status says so and names the ones it tried: Rius: no Python interpreter found on PATH. For the tracing hooks, ~/.claude/rius/log/bootstrap.log records the same.