Docs

Glyph is one zsh file. It names your terminal session at launch, then gets out of the way. Everything it can do is on this page.

Getting started

zsh, and at least one agent CLI on your PATH. Nothing else.

The installer copies one file to ~/.config/glyph/glyph.zsh and adds one source line to ~/.zshrc. Re-running it is safe.

Check it without launching anything

GLYPH_DRYRUN=1 prints the exact argv Glyph would run and stops there. Nothing starts, nothing is recorded.

Then launch for real

That string is the session name. On Claude Code it is the real session name and rides Remote Control to the web app and your phone. On every other agent it lands on the terminal title, the tmux window, and glyph ls.

How a name is built

Six tokens joined by ·, all lowercase, hyphens inside words.

The rule for arguments

One bare word is a label. Anything with a space is a prompt.

Flags like -p and subcommands like claude mcp or codex resume pass through untouched, so scripts and CI behave exactly as before.

Machine tags

Normalised to lowercase hyphenated form. Rivers MacBook Pro becomes rivers-macbook-pro, DESKTOP-8KQ2LM1 becomes desktop-8kq2lm1. Glyph never guesses a model or an OS release. If yours reads badly, set it:

Project overrides

One tab-separated line per directory in ~/.config/glyph/names.tsv. Overrides are normalised the same way.

Preview any name

Launching agents

Keep typing the command you already type. Glyph only adds the name.

Claude Code

The one agent that can name its own session, so the name becomes the real session name and reaches Remote Control.

Turn Remote Control off with GLYPH_RC=0.

Everyone else

No agent but Claude has a session-name flag, so the name goes on the terminal title, the tmux window and the registry instead.

Agents may overwrite the terminal title after launch. Fleet keeps its own pane-border labels, which they cannot touch.

See what you have running

Sessions already open

Glyph names a session from argv, so a session you started without it never got a name. glyph mark applies everything Glyph can still reach from outside the agent, and prints the one line only the agent itself can run.

It reports only the surfaces it actually reached. No terminal, no tmux, no Herdr, or GLYPH_TITLE=0 and the matching line is simply absent.

Let it type the commands for you

Add --send and Glyph types the /rename into the pane itself, over herdr pane send-text or tmux send-keys, following it with /remote-control when the bridge is off.

It refuses outside an agent session, where the keystrokes would land in your shell instead. If the agent is mid-answer the text queues until it is ready.

Inside Herdr

Herdr sets no TMUX, so the tmux path never applies there. Glyph renames the Herdr pane instead, through herdr pane rename. That label belongs to Herdr, which is the point: an agent cannot overwrite it with its own terminal title, and Codex and AGY both do exactly that a second after they start.

This applies to normal launches too, not just glyph mark. In plain tmux Glyph now also turns off allow-rename and automatic-rename on the window, for the same reason.

What it cannot do

Inside Claude Code it detects the agent from CLAUDECODE and reads the live session name out of ~/.claude/sessions/<pid>.json, so you can see what the session is called before you change it. For any other agent, name it yourself:

What is running

glyph ls is a log of launches Glyph performed. glyph ps is the other question: what is alive right now, including sessions Glyph never started.

NAMED is glyph when the name has Glyph's shape, user when someone set it by hand, auto when the agent derived it. RC is whether Remote Control is on, so you can see at a glance which sessions your phone cannot reach.

Reads the live session files and checks each pid, so it lists only what is actually running. Claude Code today: the other agents do not publish a session registry.

Usage and quota

How much is left, and when it comes back, across agents.

Each agent is a different story, and Glyph says which is which rather than blending them:

Detail for one agent

Reading a large transcript history takes a few seconds, so the result is cached for ten minutes. --refresh rescans now, GLYPH_USAGE_TTL changes the window. --live is the only part of Glyph that makes a network request; the token is passed to curl over stdin so it never appears in ps.

Auto-approve

Every agent has a flag meaning "stop asking me to approve each tool call", and they all spell it differently. GLYPH_YOLO=1 sends whichever one is right for the agent you are launching.

Make it the default

Setting it per command gets old. Export it once and every agent you launch through Glyph gets its own auto-approve flag, with nothing to remember:

Be clear about what that means: every agent will run every tool call without asking you first, in every project, until you unset it. That is the point of the flag, and it is why Glyph will not turn it on for you.

Check what any agent would actually get, without launching it:

Agents

A wrapper is defined only for agents actually on your PATH. Run glyph agents to see yours.

Agent	Command	Carries the name as	GLYPH_YOLO=1 sends
Claude Code	claude	real session name	--dangerously-skip-permissions
Codex	codex	title	--dangerously-bypass-approvals-and-sandbox
AGY	agy	title	--dangerously-skip-permissions
Cursor	cursor-agent	title	--force
Crush	crush	title	--yolo
Snowflake Cortex	cortex	title	--dangerously-allow-all-tool-calls
Hermes	hermes	title	--yolo
omni	omni	title	none
OpenCode	opencode	title	--dangerously-skip-permissions
pi	pi	real session name	none

Add your own

Any CLI, without waiting for a release. One tab-separated line per agent in ~/.config/glyph/agents.tsv: command, auto-approve flag, label. Leave the flag empty if it has none.

These merge over the built-ins, so you can also correct a flag Glyph gets wrong.

Fleet

One preset launches several agents at once, each in its own marked pane. Fleet is the only part of Glyph that opens anything.

The presets fleet init writes

It only adds what is missing, so it never touches presets you already wrote. Replace studio with one of your own machines.

Without a preset

Name the agents directly and Fleet runs them as an ad-hoc group.

Preview before opening panes

Prints the backend, the session, and one line per pane. Opens nothing.

Presets live in ~/.config/glyph/fleet.conf as name = slot slot slot. Edit it by hand any time.

Moving between panes

On the tmux backend a Fleet is one session, one window, and one tiled pane per slot. Glyph leaves you in the first pane and turns the mouse on for that session, so a click moves between them. Each pane border carries its index and its label.

Set GLYPH_FLEET_MOUSE=0 to leave the mouse alone. Glyph only ever sets it on the Fleet session, never on your global tmux config.

Remote agents

A slot is <agent> or <agent>:<machine>. For a remote slot Glyph opens SSH in that pane, changes to the same working directory, and launches the agent through the remote Glyph wrapper, so it gets that agent's own flags and its own name.

How a machine name resolves

First hit wins.

Tailscale is optional and detected automatically; nothing changes if you do not use it. Remote slots work on every backend, because they all build the same SSH command.

Workspace backends

Backends decide where Fleet opens panes. They change nothing about launching a single agent.

Glyph is not tied to any one workspace tool. With none running, Fleet falls back to tmux.

Command reference

Configuration

Behaviour

Paths

Files on disk

Updating

• Loads the new file into the shell you ran it in, so there is nothing to reload.
• Refuses to install a file that does not parse.
• Keeps the previous copy at ~/.config/glyph/glyph.zsh.bak.
• Follows a symlink and writes the file it points at, so an install linked into a synced folder keeps its link.
• Never touches fleet.conf, names.tsv or agents.tsv.
• Point GLYPH_UPDATE_URL somewhere else to track a fork.

Other shells you already had open keep the old wrapper until you run exec zsh in them.

Doctor

Before troubleshooting by hand, ask Glyph what it thinks is wrong.

It checks the wrapper path and whether it is a symlink, version drift between the file on disk and the copy loaded in this shell, the ~/.zshrc line, which agents are on your PATH but not actually wrapped, the Fleet backend it would use, the registry, and your config files. It exits non-zero when something needs attention, so it works in a script.

The check that catches most confusion is version drift: an updated file on disk and an older copy still loaded in the shell you are typing in.

Troubleshooting

Two things that cost real debugging time

• Claude's --remote-control <name> does not name the session. It opens the bridge, and the session still comes back as nameSource: "derived". Only -n sets the name, so Glyph passes both.
• In zsh, argv is $@. Declaring local -a argv in a function silently empties the positional parameters. Worth knowing if you fork this.

Uninstall

Nothing else was installed and no agent config was modified, so that is the whole of it.