In 2026, most developers we know use more than one AI coding agent. Claude Code for refactors. Codex CLI for repo-wide migrations. Grok or OpenCode for a side project. Maybe Droid for something a teammate set up.

Each of those agents wants to own a HOME directory. Each one has its own config file format, its own conversation history, its own usage log, and its own way of picking a provider. Run them all on the same laptop and the seams show up fast: keys leak between projects, you can’t run two instances on different accounts, and nobody can tell you how much last month actually cost.

Ringlet is the layer that sits above those agent CLIs and gives you a single unit — a profile — that captures everything they each want to manage independently.

The five-minute version

# Install
curl -fsSL https://raw.githubusercontent.com/neul-labs/ringlet/main/install.sh | sh
ringlet init

# Create a couple of profiles
ringlet profiles create claude work     --provider anthropic
ringlet profiles create claude personal --provider minimax
ringlet profiles create codex  staging  --provider openai

# Use them
ringlet profiles run work        # → claude with HOME=~/.ringlet/profiles/work
ringlet profiles run personal    # → claude with HOME=~/.ringlet/profiles/personal
ringlet profiles run staging     # → codex with HOME=~/.ringlet/profiles/staging

# Cost across all of them
ringlet usage

That’s the whole product surface from a user’s point of view. Everything else — sandboxing, hooks, the web dashboard, remote sessions — comes for free once you have the profile abstraction.

What a profile actually does

A Ringlet profile is a (agent, provider, credentials, HOME) tuple. When you run a profile:

  1. Ringlet exports HOME=~/.ringlet/profiles/<name> (the profile’s own HOME directory)
  2. Ringlet exports the right base URL and API key environment variables for the agent’s wire format
  3. Ringlet execs the agent binary

The agent then reads what looks to it like a perfectly normal ~/.claude (or ~/.codex) directory — except it’s a per-profile one. Two profiles never touch each other’s files. Two profiles never share an MCP server registration. Two profiles never share a conversation history. The boundary is the same one the OS already uses for users.

That’s the whole core idea. The rest is leverage built on top.

Why the HOME boundary matters

You could try to isolate agents with environment variables alone: a wrapper script that re-exports ANTHROPIC_API_KEY per project. It works until the agent caches something. And modern coding agents cache a lot:

  • Project-level memory (e.g. CLAUDE.md and per-project context)
  • Tool approvals (“yes, you can run git push in this repo”)
  • MCP server registrations
  • Cost ledgers
  • Conversation indexes

All of these live in the HOME directory. The only durable way to isolate them is to give each profile its own. Ringlet does that automatically, populated with whatever the agent expects to find, and you stop fighting the agent’s own caching layer.

Provider switching, without the agent knowing

Most coding agents have a default provider — Claude Code talks to Anthropic, Codex talks to OpenAI. But all of them respect a *_BASE_URL environment variable to point at a different gateway. Ringlet uses that.

Want Claude Code to talk to MiniMax for cost-sensitive work? --provider minimax. The agent never knows. It thinks it’s still talking to Anthropic — just at a URL Ringlet picked. Want Codex to go through Groq for speed? Same. Want all your tool-heavy traffic to land at Anthropic but small completions at OpenRouter? That’s the routing layer, but it sits behind the same profile abstraction.

The flip side: if you don’t use a custom provider, Ringlet does nothing surprising. Defaults are the agent’s own defaults. The orchestration layer is opt-in by feature.

Cost tracking is the killer subfeature

Every modern provider — Anthropic, OpenAI, MiniMax — streams token usage back inline with the response. The token count is a wire-protocol field, not a separate API call. Ringlet parses those events and writes them to a per-profile SQLite database. ringlet usage aggregates across profiles.

$ ringlet usage --since 2026-05-01

PROFILE     AGENT       PROVIDER    TOKENS         COST
work        claude      anthropic   1.21M / 340K   $8.41
personal    claude      minimax     2.83M / 820K   $0.92
staging    codex       openai      0.45M / 90K    $1.40
─────────────────────────────────────────────────────────
TOTAL                                                $10.73

This is the feature that pays for the install in a week. Engineering managers ask “what does our team’s Claude spend look like” and get an answer that isn’t “wait for the invoice.”

What Ringlet doesn’t do

Honesty section. Ringlet is not:

  • An agent. It doesn’t generate code, doesn’t have its own LLM, doesn’t make tool calls. Your agent does that — Ringlet just lets you run a few of them cleanly.
  • A model gateway. LiteLLM and OpenRouter sit between an application and a model API. Ringlet sits between a developer and an agent CLI. Different layer. Use them together if you want.
  • A parallel task runner. If you want five Claude Code agents working on five git worktrees, you want Claude Squad or Conductor. You can run Claude Squad inside a Ringlet profile if you want both.
  • A SaaS. No hosted dashboard, no required cloud. Everything runs on your laptop or your own server.

Who Ringlet is for

Three concentric circles:

  1. Solo developers with more than one project on more than one account. The shell-alias mess we described in detail goes away on day one.
  2. Engineering teams that have standardised on an AI coding agent and want every developer’s workflow to look the same. The team page walks through that setup.
  3. Cost-sensitive operators routing agents between Anthropic, MiniMax, OpenRouter, or their own gateway. The provider-switching feature is the entry point.

If you only use one agent, on one account, with one provider, Ringlet adds little. Honest answer: stick with what you have.

What ships at 0.1.0

The 0.1.0 release ships:

  • Profile isolation (separate HOME, credentials, history, config)
  • Multi-agent support (Claude Code, Codex CLI, Grok CLI, Droid CLI, OpenCode)
  • Provider switching (Anthropic, OpenAI, MiniMax, OpenRouter, OpenAI-compatible)
  • Cost tracking with SQLite ledger and CSV export
  • Event hooks (pre-tool-use, tool-use, stop, notify, cost-threshold)
  • Sandboxed remote terminal sessions (bwrap, sandbox-exec)
  • Web dashboard (Vue 3 + xterm.js)
  • Native desktop app (Tauri)
  • Keychain-backed credential storage
  • Rhai scripting for hook logic

It’s MIT-licensed. There is no paid tier yet. The team and enterprise tiers are on the roadmap; today you self-host everything.

If you’ve already nodded at “yes, this is the problem I have” three times reading this, the install is one curl. Start with two profiles on the same agent, see if the friction you didn’t realise was friction disappears, and decide from there.