Agent Identity

What is AGENT.md?

AGENT.md is a file in your workspace root (/home/user/AGENT.md) that defines who your agent is and how it works. It’s included in every conversation, across all channels — the foundation that channel-specific instructions build on.

This is where you configure things that apply everywhere:

• Personality — casual or formal, terse or verbose, opinionated or neutral
• About you — who you are, what you do, preferences that matter across contexts
• Working style — how you want the agent to approach tasks, make decisions, communicate

How it works

The agent reads AGENT.md on every message. It’s essentially a persistent system prompt that you control. Combined with channel instructions, it creates a layered identity:

AGENT.md (global) → applies everywhere
  └── Channel instructions → applies in that channel
        └── Conversation context → the current thread

AGENT.md sets the baseline. Channel instructions add specifics. The conversation adds immediate context.

What to put in AGENT.md

Here’s a rough structure that works well:

Agent identity — how should the agent sound? “Casual, direct, opinionated” or “professional, thorough, measured.” Be specific. “Be helpful” is useless. “Push back when something seems wrong, prefer action over deliberation” is useful.

About you — give the agent enough context to make good judgment calls. Your role, your projects, your preferences. The more it knows about you, the less you have to re-explain.

How you work together — rules of engagement. “Don’t ask permission to start, just do it.” “Always show your reasoning.” “When there’s a choice between options, recommend one and explain why.”

Editing AGENT.md

You can edit AGENT.md directly in the file explorer (it’s just a markdown file), or ask the agent to update it. Since the agent can read and write files, you can say things like:

• “Update AGENT.md to note that I prefer TypeScript over JavaScript”
• “Add to AGENT.md that when I ask you to build something, always create tests”

The change takes effect on the next message — no restart needed.

AGENT.md vs. channel instructions

Use AGENT.md for things that are true everywhere. Use channel instructions for context-specific behavior.