Skip to Content

DocsConcepts

Profiles

A profile is one account of one agent, as a folder and a launcher.

View source

This page explains what a profile is, what its launcher does, and where an account does and does not follow you.

A folder and a variable

A turno profile is a folder (~/.claude-work) plus an environment variable that points the agent at it: CLAUDE_CONFIG_DIR for Claude Code, CODEX_HOME, COPILOT_HOME and CURSOR_CONFIG_DIR for the others. The launcher (claude-work, turno work, turno auto) exports that variable and then replaces itself with the agent.

The agent is the vendor's own, unmodified command-line tool. It logs in by itself, inside that folder; turno never reads, copies or forwards login tokens.

turno profile add work --color violet     # ~/.claude-work and the claude-work command
turno profile list
Profiles ───────────────────────────────────────────────────────────────────────
              agent        account                     folders     role
   personal   Claude Code  you@personal.example · pro  no folders  default
   work       Claude Code  you@work.example · max      1 folder

turno <name> opens one; turno profile assign <dir> gives a folder its profile.

What profiles share

Profiles of one agent share what is not the account, through links to the agent's own folder (turno calls it the hub: ~/.claude, ~/.codex):

AgentShared between its profiles
Claude Codeprojects, sessions, skills, plugins, settings
Codex CLIsessions, prompts, skills, AGENTS.md
GitHub Copilot CLIsession-state
Cursor CLInothing

That is why turno work --resume <id> continues a Claude Code session that another account started. turno profile repair relinks shared items and rewrites launchers when turno doctor finds one out of place.

Three roles in config.toml

~/.config/turno/config.toml
system = "personal"     # account the plain `claude` command uses ("" for none)
default = "personal"    # profile for folders without a rule
# fallback = "work"     # optional, off unless set; read "Vendor terms" first
  • system names the account signed in at the hub, the one a plain claude uses.
  • default is the profile for folders without a rule.
  • fallback is off by default. It chooses which of your own accounts opens a folder while another is marked exhausted. Vendors' usage policies forbid creating or using accounts to get around usage limits or safeguards, so read your plan's terms before you set it, and do not use it for that. See Vendor terms.

Where the account goes, and where it does not

The account follows the environment. Everything the agent starts inherits it, so it runs with the same account:

  • Claude Code subagents, which run inside the same process.
  • Commands of the Bash tool, hooks, and stdio MCP servers that the agent starts itself.
  • A claude -p ... or codex exec ... that the session runs.
  • turno open and the BROWSER the launcher sets, so claude.ai links open with that account.

MCP servers behind the gateway are the exception: mcpd starts them, not the session. turno tells mcpd which profile and session a request comes from, and a server can have a variant per profile.

Anything started without the variable uses the hub's account: a plain claude in a new terminal, scripts that clear the environment (env -i, sudo), cron jobs and LaunchAgents, and apps opened from the Dock. The guide lists three ways to close that gap.

turno auto never switches in silence

When a rule names a profile that does not exist (or there is no rule and system = ""), turno auto exits 3. When the folder's profile has no launcher, or config.toml does not parse, it exits 1. Either way it prints the reason and the command that fixes it. turno profile which --check tells a script the same before it runs anything: 0 ready, 3 no profile, 4 not signed in (exit codes).

The status line

For Claude Code, turno draws a status line under the prompt with the profile and what its account has used:

◉ work · Max1 │ ⧗ ▰▰▰▱▱▱▱▱ 41% ↺ 2h01m2 │ ▦ ▰▰▰▰▰▱▱▱ 67% ↺ 2d7h3 │ ◔ [##--------] 23% 230k/1M4 │ ▮ ~38 turns5
▣ acme │ ⎇ main6 │ ± +128 −147 │ ◈ Opus 5.5 ✦ high8 │ $4.82 (sub $1)9
  1. 1Profile and plan. The pill. Its color comes from the profile's color in config.toml.
  2. 25 h usage. The account's 5 hour window and the time until it resets.
  3. 3Weekly usage. The account's weekly window and the time until it resets.
  4. 4Context. Context used, as a bar and as tokens.
  5. 5Turns left. Turns left in the 5 h window, estimated from recent turns.
  6. 6Project and branch. The project (and worktree) and its git branch, read without running git.
  7. 7Lines changed. Lines added and removed.
  8. 8Model and effort. The model of the conversation and its effort.
  9. 9Cost. The API-equivalent cost of the conversation, subagents included.
turno ui install                     # font + statusLine in the shared settings.json
turno ui install --terminal current  # also set the font in this terminal

It uses Nerd Font icons where the terminal has them and Unicode icons everywhere else. This is the real thing, in both looks:

The turno status line with Nerd Font icons and with Unicode icons

When the folder belongs to another profile than the one the session runs with, row 1 ends with a warning.

Service accounts and the accounts bridge

A service account is a Linear workspace, a mail connector or any other MCP server that one profile reaches. A builtin MCP server (builtin = "accounts" in mcp.toml) lets a session in one profile delegate a task to a service account that only another profile is signed into:

turno identity add linear:work --profile work --tools 'mcp__linear__*' \
  --read-tools 'mcp__linear__get_*,mcp__linear__list_*' --confirm writes

Reads run with only the account's read tools. Writes, and by default every call to a mail or messaging account, need your confirmation. Every call and its decision go to a hash-chained audit log (turno identity log, and --verify checks the chain). See Security and privacy.

On this page