The Agent Under the Monorepo

River is Shopify's AI agent that works in the company Slack. Launched a few months ago, it now coauthors one in eight merged pull requests across the company. The agent surface is only part of the story. Underneath sits a platform bet placed in early 2024, and a set of infrastructure decisions that made it possible.

The substrate bet

In early 2024, Shopify made two related moves: consolidate into a single monorepo called World, and build everything with Nix—development environments, CI, and production images all on one reproducible substrate. Neither was popular at the time. Both were driven by a single conviction: code would increasingly be written with AI, and infrastructure needed to become the substrate for that shift.

The migration was painful. CI scaled by an order of magnitude almost overnight. Merge queues became load-bearing infrastructure. The build cache turned into a product. Test infrastructure got rebuilt around the assumption that any change might recompile a large share of the dependency graph. Team-level assumptions had to be undone one by one.

The payoff came in several forms:

  • An AI coding agent rooted in a repo navigable across every part of the company
  • Skills: written-down knowledge stored as files, loaded into agent sessions on demand
  • "Ask the repo a question" as a practical interface
  • Cross-Shopify navigation from a production log line back to the originating commit
  • Reproducible environments across development, CI, and production

Two insights that shaped the work

Agent-friendly work is human-friendly work. Every change made for agents was also right for humans: the monorepo, reproducible environments, documented skills, clean CI signal. These were already on the wishlist—they just were not urgent enough to fund before agents required them. A non-reproducible dev environment means agents cannot reproduce anything either. A fragmented repo means agents cannot see across it. Unwritten knowledge means nobody can learn it: not new human hires, not agents in their first session.

Local agents have a hard ceiling. A personal agent running in a terminal or editor keeps its discoveries private. The clever way one engineer investigated a flaky test dies with the session, and no agent learns from another. If every agent interaction happens in a private window, the only person who learns is the person at the keyboard.

River works in the open

River lives in Slack. Engineers talk to it by typing @river in a public channel. It reads code, runs tests, opens pull requests, queries the data warehouse, examines production traces, and occasionally pushes back on a plan. Median session length is 19 minutes; median tool calls per session is 50.

One rule governs River: no direct messages. Every conversation becomes a public Slack transcript, open to other Shopify employees. That corpus gets mined continually. A successful fix by one person becomes the starting point for the next because the patterns feed back into River's skills, prompts, and defaults. The agent improves without model retraining; the codebase teaches the agent and the agent teaches the codebase.

A typical productive thread follows a pattern: one person mentions River with a question; River reads files, runs queries, posts partial findings; a second human drops in with a constraint or redirect; River incorporates the context and continues; the thread stays searchable for anyone hitting a similar problem later.

Scale and compounding knowledge

In a recent 30-day window, River ran 59,918 sessions across 5,170 Slack channels, touching the work of more than 7,000 people. Some 3,536 River-coauthored pull requests merged in that period. The numbers come from the river_sessions domain table River writes itself after every session.

World has become more than a code repository. It contains skills, conventions, intent documents, runbooks, AGENTS.md files, and written zone knowledge. When someone solves a problem with River, the solution leaves a trace: a skill update, an AGENTS.md diff, or a new shared skill. The next session uses it, and the next observer learns from both.

As River shipped, other teams wanted versions of their own: PR review agents, research agents, migration agents, compliance scans, performance investigations. All were the same basic idea—an agentic workflow against the monorepo, in Slack, durable and multiplayer. River itself was running fine, but there was no platform yet that could support a hundred agents like it.

Separating the brain from the hands

The architecture needed to decouple the agent's planning from its execution environment. The direction aligned with external thinking on managing long-running agents: keep the conversation safely stored apart from the sandbox where code runs. Shopify's internal platform for this is called Aquifer. River is a profile on it. The design constraint is simple: cells die, sandboxes die, machines die—the conversation does not.

The decomposition has three pieces:

  • Session: durable identity backed by an append-only Postgres event log. This is the canonical truth about what has happened.
  • Harness: the agent loop that reads history, calls the model, and emits tool intents. Cheap to recreate and disposable.
  • Sandbox: where code runs—filesystem, shell, repo. Disposable, sometimes warm, often fresh.

The harness lives outside the sandbox; the agent does not share a process with the code it manipulates. Three properties follow. Safety: the agent loop is not in the blast radius of an accidental destructive command. Replaceability: models, runtimes, even languages can be swapped without disturbing the sandbox. Observability: the decision stream stays visible from a single place.

Session cells and profiles

When a session starts, Aquifer materializes a session cell: an ephemeral process hosting the Go runtime and agent harness in one process group. If idle, it exits. The next interaction spawns a fresh cell, possibly on another host, but the session identity and complete history live in Postgres. Work picks up where it left off because the state is in the database, not in memory. The substrate treats sessions as cattle, not pets: provision, run, suspend, destroy, and re-provision without nursing individual processes.

River is one profile on Aquifer. PR review is another. Vanilla, the headless "pi" agent, is a third. A profile is data: system prompt, skills, extensions, sandbox policy, model defaults—all built with Nix and shipped as bundles. Adding a new agent product means adding a bundle, not building new platform code.

The same object model supports three distinct consumers:

  • Interactive: River. Durable session with a live human, long-lived.
  • Automation: PR review. Durable session triggered by an external system, often with no human present.
  • Job: CI and batch workloads. Ephemeral: provision, run, stream results, destroy. The session log stays optional.

Each of these reuses the same session model, sandbox plane, and gateway. Any alternative architecture the team tried ended up reinventing one of these three modes. The platform now provides durable, threaded, multiplayer conversation against the real codebase, data warehouse, and production signals—with the agent as a first-class participant. River is the visible result; Aquifer is the platform built to ship more agents like it.

Early Numbers, Moving Up

River has been live for roughly two months, and Aquifer is now rolling out profile by profile beneath it. The usage figures shared at launch are already outdated — in the upward direction.

The recurring question internally echoes Robert Macfarlane's 2025 book title: Is a River Alive? The honest answer is that no one at Shopify knows exactly how this system will evolve. What is known is what the system does; the language for what it is still being written.

To "river" is not a verb in English. But what could be more of a verb than a river? — Robert Macfarlane, Is a River Alive?

The framing fits: River is what happens when the substrate underneath learns to flow. Aquifer holds the memory. The Slack thread is where work surfaces. The shop floor talks back publicly every day — and gets incrementally smarter overnight. River is the verb in that sentence.

Future agent products at Shopify are no longer new platforms; they are new bundles. Everything ships with a durable session, the gateway, a sandbox, and the multiplayer corpus. The cost of the next River-shaped thing has dropped from building a new platform to merely defining a new profile.

That is the unlock — the assumption that, two years out, will be the boring foundation under every interesting product.

Lessons for Agent Infrastructure

You cannot tag River in a Shopify Slack thread, but the takeaway is not the surface agent. It is the substrate underneath, and the bet that produced it: the session is the thing that must survive.

Three priorities follow for anyone building agent infrastructure:

  1. Decouple the brain from the hands. The harness does not live in the sandbox. Committing to that boundary turns safety, replaceability, and observability into non-trade-offs. Retrofitting it later is not an option.
  2. Make the agent multiplayer by construction. A private agent is capped by the person at the keyboard. A public agent teaches every session that follows it. The corpus is the compounding asset; a private thread is a disadvantage.
  3. Treat the next agent as a profile, not a platform. The cost of a new agent product should be a new bundle on the same substrate. If your second agent forces a second platform, you have not yet built the substrate.

What Comes Next

All of this is in motion inside Shopify, and none of it is finished. The architecture is stable enough for teams to build on, yet unfinished enough to remain some of the most interesting work available.

Two years from now, the agent itself will not be the interesting part. What sits underneath it will be. That was the bet made in 2024, and the current data says it paid off.