Tell Your Agent Who You Are
USER.md is the context card your agent reads at the start of every session. Five minutes filling it in means your agent never asks "what timezone are you in?" again.
What is USER.md?
It's a plain Markdown file that lives in your workspace root. The agent loads it into every session so it always knows who it's working for.
Without USER.md: Every session starts cold with zero context about you. Your agent asks the same questions again and again — "What timezone are you in?", "What's your email?", "What language do you code in?"
With USER.md, those facts are always loaded. Your agent knows your name, timezone, communication style, current projects, and preferences from the moment the session begins.
What to Include in USER.md
Here are the key sections that make your agent genuinely useful:
Name & Timezone
Your name, timezone (e.g. Europe/London), role, and location. This prevents "what time is it for you?" from ever being asked.
Communication Style
Be direct or verbose? Prefer bullet points or prose? Use emojis? How much explanation do you want? Your agent adapts to match.
Work Context
Your role, company, industry, and what you do. Helps the agent understand your domain and provide relevant guidance.
Current Projects
2-3 active projects with brief descriptions. So your agent knows what you're actively working on.
Tools & Preferences
Preferred languages (Python, TypeScript, etc), code editor, hosting platform, how you like answers formatted.
Trusted Contacts
People you work with often. So your agent knows who to trust with sensitive information or who to send messages to.
Boundaries
What the agent should never do without asking you first. Sending emails, deleting files, posting publicly, etc.
Complete USER.md Template
Here's a full template you can copy into your workspace and customize:
# About Me
- **Name:** [Your name]
- **Timezone:** [e.g. Europe/London UTC+0]
- **Role:** [e.g. Freelance designer, Software engineer at Acme]
- **Location:** [City, Country]
# Communication Style
- [e.g. Be direct. Skip pleasantries. Use bullet points.]
- [e.g. I prefer code examples over explanations.]
- [e.g. Use British English spelling.]
- [e.g. Include emojis to keep things light.]
# Current Projects
- **[Project name]:** [1 line description + current status]
- **[Project name]:** [1 line description + current status]
- **[Project name]:** [1 line description + current status]
# Tools & Stack
- **Code:** [e.g. Python, TypeScript, Go]
- **Editor:** [e.g. VS Code, Cursor, Neovim]
- **Hosting:** [e.g. Vercel, AWS, Fly.io]
- **Package Manager:** [e.g. npm, uv, cargo]
# Key Contacts
- **[Name]** ([relationship]) — [email or handle]
- **[Name]** ([relationship]) — [email or handle]
# Preferences
- [e.g. Always confirm before sending emails]
- [e.g. Save research to ~/Documents/research/]
- [e.g. I use 24-hour time]
- [e.g. I work in sprints, not continuous mode]
- [e.g. Prefer working on a single task until done, not context switching]
# Off-Limits (Always Ask First)
- Deleting files
- Sending messages to anyone outside my contact list
- Committing to git without showing me the diff first
- Making any public posts or submissions
- Opening sensitive files or credentials
Empty vs. Well-Filled USER.md
Here's what happens with and without a good USER.md file:
❌ Empty USER.md
- Agent: "What timezone are you in?"
- Agent: "What's your preferred language?"
- Agent: "Do you want verbose explanations?"
- Agent: "What are you working on?"
- Every. Single. Session.
✅ Well-Filled USER.md
- Agent: Loads USER.md. Knows you're in London.
- Knows you code in TypeScript.
- Prefers direct, concise answers.
- Knows you're working on project X.
- Agent just gets to work.
When to Update USER.md
USER.md is not a "set it and forget it" file. Review and update it when:
Starting a New Project
Add the project to your Current Projects section so the agent knows about it immediately.
Changing Jobs
Update your role and company. This context shapes how the agent helps you.
Getting the Same Answer Wrong
If the agent keeps doing something you don't like, add a note to Preferences or Boundaries.
Preferences Change
You started wanting more explanation, or switched languages, or changed your schedule. Update it.
Tip: Review USER.md once a month. Delete outdated projects, add new ones, refine your communication preferences. The agent learns from every session, but USER.md is where you codify permanent truths about yourself.
Related Workspace Files
USER.md is one of four key workspace files. Learn about the others: