Identity

Your agents work better when they know who they are working for. Identity is a short description of you that you write once. Every agent you run in crystl can read it, in any gem, with no hero or quest set up. You stop explaining yourself at the start of every session.

Say you write: “I build products and can read code, but I want architecture decisions explained in terms of user impact. Keep routine updates brief.” Your agent can use that on its very first task.

Identity is free on every tier. It needs no account, no email address, and no real name.

Where it lives

Your identity is one Markdown file at ~/.crystl/identity.md. It sits outside every project, so it is the same in every gem, and it is not committed to any repository.

Your identity is stored on this Mac. crystl does not upload it. Agents you run here can read it, and an agent may send it to its model provider.

Everything you write in it is readable by your agents. There is no private part and no per-field switch. If you do not want an agent to know something, leave it out.

Identity stays out of crystl’s telemetry, diagnostic uploads, and licence requests.

Identity is separate from project instructions. A preference for short updates belongs in your identity, because it applies everywhere. A project’s build command belongs in that project’s instruction file. An instruction you give in the current task still comes first.

The fields

Open Settings → identity, under General. Only the name is required. Every other field is optional free text, with no ratings and no checkboxes.

Field	What it asks
Name	What should your agents call you? A handle is fine.
Role	What do you do, in a line?
About you	What would help an agent understand your background?
Working toward	What would you like your agents to help you achieve?
What you know well	Where can an agent assume familiarity?
Where you want support	What would you like explained, checked, or helped along?
How you like to work	How should agents communicate and collaborate with you?

The page shows a preview of the exact file your agents read. What you see there is what they get.

crystl never asks for your age, location, or email. If some of that context helps, you can mention it in About you.

Portrait

You can add a picture, picked or dropped onto the page the same way you add a custom hero’s portrait. With no picture, the page shows your initials. The portrait is for you: it appears on the identity page and panel. It is never in what crystl identity show prints or in prompts; the file itself holds only a random file name for it.

Stats

A collapsed stats section holds STR, INT, WIS, and DEX. Only quests use them, the same way they used your old character card. Ordinary agent sessions never see your stats.

First run

On a new install, crystl asks What should your agents know about you? before agent and model setup. A name or handle is enough to continue. The other fields sit under add more about you, and you can fill them in later or never.

If you used crystl before identity existed, your character card from the Heroes page moves here with every field kept as you wrote it. crystl shows a one-time panel that explains the move, with a button that opens your identity. The Heroes page now links to identity instead of holding its own copy, and quests read the same identity as every other agent.

How your agents find it

crystl writes one line into each agent’s global instruction file, such as ~/.claude/CLAUDE.md for Claude Code and ~/.codex/AGENTS.md for Codex:

~/.crystl/identity.md describes the person you work for, written by that person; `crystl identity show` prints it.

The line points at the file. Your identity text itself never goes into an instruction file, and never into the project files crystl commits to your repositories. The line comes out with the rest of crystl’s section when you turn off tell agents about the crystl CLI.

An agent without a global instruction file can read your identity with the CLI:

crystl identity show

Your agent reads the identity as context you wrote. It does not grant permissions or approve tool calls.

Changing it

Edit it on the identity page, or ask your agent to. Agents like Claude Code or Codex can use crystl identity update to change a field when you ask, and crystl identity edit to open the identity panel in front of you. Opening the panel never switches the gem you are looking at. An agent should not change your identity on its own, or guess things about you from a conversation.

You can also edit ~/.crystl/identity.md by hand. crystl notices the change the next time it reads the file, so a settings window that was open beforehand cannot overwrite your edit.