DEV Community

Cover image for AGENTS.md, CLAUDE.md, .gitignore: The Setup Nobody Explains to Beginners
Gabriel Anhaia
Gabriel Anhaia

Posted on

AGENTS.md, CLAUDE.md, .gitignore: The Setup Nobody Explains to Beginners

#beginners #tutorial #ai #productivity

The hardest part of using a coding agent is the five minutes before
the first prompt.

You've heard "just use Claude Code" a dozen times. So you open a
terminal and make a folder. Someone told you to run git init. A
tutorial mentioned a .gitignore, and you're not sure what goes in
it. The Claude Code docs talk about CLAUDE.md, a Codex thread talks
about AGENTS.md, and now you have an empty folder, two file names
you half understand, and a blinking cursor. What do you even type?

This is where a lot of people close the terminal to "learn the setup
first". You don't have to. The setup is a git repository and three
small files, and each one has a plain reason to exist.

An empty cardboard folder with a small robot climbing out of it, holding a wrench

I build Hermes IDE, a free desktop app that
runs coding agents like Claude Code and Codex in their own real
terminals. Version 2.2.9 added a New folder… button that does the
whole setup in one form.

Step 0: the one-time setup

You will touch a terminal once, to install git and an agent and sign
in to the agent. Hermes runs the agent's own command-line tool, so
that tool has to exist on your machine.

  1. Install Hermes. It's free, from hermes-ide.com/download, for macOS (Apple Silicon and Intel), Windows, and Linux (.deb and AppImage).
  2. Install git. On macOS, run git --version in Terminal. If git is missing, macOS offers to install its Command Line Tools. On Windows, install Git for Windows. On Linux, use your package manager, for example sudo apt install git.
  3. Install one agent and sign in. Pick one to start:

These are the install lines Hermes itself suggests:

# Claude Code, macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash
# Claude Code, Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

# Codex, any system with Node.js
npm install -g @openai/codex

# Antigravity CLI, macOS and Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash
# Antigravity CLI, Windows (PowerShell)
irm https://antigravity.google/cli/install.ps1 | iex
Enter fullscreen mode Exit fullscreen mode

Then run the agent once and sign in: claude and follow the browser
login, codex and sign in with your ChatGPT account, or agy and
open the sign-in link it prints. Gemini CLI is still in Hermes's list,
marked legacy. For a Google agent, start with Antigravity CLI.

When you open Hermes the first time, a three-step setup shows which
agent tools it found, whether each one is signed in, and the install
command for any it didn't find. The agent uses its own login. Hermes
never asks you for an API key or token.

Step 1: ⌘N, then New folder…

Press ⌘N (Ctrl+Shift+N on Windows and Linux) to open the New
task launcher. The project list has two buttons under it:
Browse… for a folder you already have, and New folder… for
one you don't.

The New project folder form inside the New task launcher, with Name, Create in and four checkboxes

Real Hermes window, test build with stand-in agents. The New project
folder form inside the New task launcher. The long temp path comes
from the test rig, and the chips above still show the previously
selected repo. After Create folder they switch to the new folder.

Give it a Name, say todo-page. Create in defaults to where
you last made a folder, or next to your newest project, and Browse
lets you pick somewhere else. Then four checkboxes.

Start a git repository (on). Git records every version of your
files. With an agent, that matters more than usual. It's how you see
exactly what the agent changed and how you take it back.

Add a .gitignore (on, only offered with git). This is a list of
files git should not track: system clutter, logs, installed
packages, build output, and your secrets. Hermes writes this one:

.DS_Store
Thumbs.db
.env
.env.*
!.env.example
*.log
node_modules/
dist/
build/
target/
.venv/
__pycache__/
Enter fullscreen mode Exit fullscreen mode

The .env lines keep API keys and passwords out of git. The ! line
is an exception: .env.example, a template with no real secrets in
it, stays tracked so the next person knows which settings exist.

Add AGENTS.md for agent instructions (on).
AGENTS.md is a plain markdown file of
instructions that coding agents read before they work. Codex, Cursor,
GitHub Copilot's coding agent and
many others look for it. Claude Code can read
AGENTS.md too, but once a CLAUDE.md exists it reads that file
instead. So Hermes also creates a CLAUDE.md containing one line,
@AGENTS.md. That's
Claude Code's import syntax:
"read that file too". Agents read these rules. They treat them as
context, so they don't always obey them.

The starter AGENTS.md has your folder name as its title, two lines
saying which agents read it, and three empty headings: What this
project is, How to build, run and test, and Conventions.

Add a README (off). A README.md with your folder name as the
heading.

Click Create folder. The folder is made right away and selected
in the launcher. With the defaults, this is what lands on your disk:

todo-page/
├── .git/
├── .gitignore
├── AGENTS.md
└── CLAUDE.md     ← one line: @AGENTS.md
Enter fullscreen mode Exit fullscreen mode

If a folder with that name already exists, Hermes refuses and tells
you why. It doesn't touch the existing folder. Esc closes the form.

For comparison, this is roughly what the form saves you from typing:

mkdir -p ~/projects/todo-page && cd ~/projects/todo-page
git init
# then write .gitignore and AGENTS.md by hand
printf '@AGENTS.md\n' > CLAUDE.md
Enter fullscreen mode Exit fullscreen mode

Everything the form makes is plain files and plain git. If you never
open Hermes again, the folder works the same with the agent's own CLI
and any editor.

Hermes isn't the only tool that helps here. Warp has
/create-new-project and /init,
which walk you through a new project with its agent and generate an
AGENTS.md from an existing codebase.

Want to follow along? Download Hermes
(free, 2.2.9 or later), press ⌘N (Ctrl+Shift+N), and keep this tab
open.

Step 2: write a few lines of rules

Open AGENTS.md in any text editor (Notepad, TextEdit in plain-text
mode, VS Code), fill in the headings, save, and come back to the New
task launcher. If you're uneasy about an AI writing code you don't
understand, this is where you set the terms. A first version can be
this short:

## What this project is
A to-do list web page. Plain HTML, CSS and JavaScript.

## How to build, run and test
Open index.html in a browser. No build step.

## Conventions
- No frameworks and no npm packages.
- Explain each new file in a comment at its top.
- Ask before deleting anything.
Enter fullscreen mode Exit fullscreen mode

Change it to fit your project. Write whatever you'd tell a new
teammate on their first morning.

Step 3: write your first prompt

The big box at the top of the New task launcher is the task box.
Whatever you type there becomes the agent's first message. For the
to-do page, this is enough:

Build the to-do page described in AGENTS.md: one
index.html with a text input, an Add button and a list.
Clicking an item marks it done. Save the list in
localStorage so it survives a reload. The attached
screenshot shows the look I want.
Enter fullscreen mode Exit fullscreen mode

If you don't know what to ask, don't start from a blank box. With the
launcher open, press ⌘J (Ctrl+Shift+M on Windows and Linux) to
open Prompts. It reads Hodios,
a free, open prompt library: 10,000+ prompts in the live catalog, plus
personas, workflows, rules and styles. The copy bundled for offline
use is smaller.

The prompt library's For you tab, with picks for a React and TypeScript project and the reason each one fits

Real Hermes window, test build with stand-in agents. The For you tab
of Prompts: each card says why it fits, like "Your project uses
TypeScript". The "What do you work on?" picker in the middle is what
ranks picks when the folder has no code yet.

The For you tab ranks prompts for you, and the personalisation
stays on your computer. The screenshot shows picks for a React and
TypeScript project because that test folder already had code in it.
A brand-new folder has no code yet, so the role and interests you
choose under What do you work on? do more of the work. Search works
too.

Pick a prompt and fill in its blanks. Then click Use as task, and
the text lands in the task box, ready to edit.

Step 4: attach a screenshot and launch

Since 2.2.0, the task box takes attachments. Paste a screenshot, drop
files onto it, or click Attach…. Each one shows up as a chip with
a preview. The agent gets the file locations, so it can open them. In
the optional Agent view (a chat-style view Hermes offers for Claude),
Claude also receives the images themselves. A photo of a paper sketch
works, and so does a screenshot of a page you like.

The New task launcher with Attach, Prompts and the approval modes Ask, Accept edits, Plan first, Auto, Don't ask and Skip all

Real Hermes window, test build with stand-in agents. The New task
launcher opened on a repository that has commits, so it offers a new
worktree. In a brand-new folder the agent starts in the folder
itself.

Before you press Launch, look at the Approval row. These are the
agent's own permission modes, and the agent enforces them. Check the
default before you launch, because it lets some work through. The
launcher starts Claude
Code on Accept edits: edits inside the folder go through without a
prompt, while commands, web access and other folders still ask. Codex
starts on Auto: it writes inside the folder without asking, the
network is off, and anything outside the folder asks.

If you want to approve every edit while you learn, pick Ask.
Plan first is Claude Code's plan mode: it writes a plan and
changes nothing until you approve. Skip all, marked ⚠ in the
launcher, lets the agent edit and run anything without asking. Leave
it alone while you learn.

The bottom of the launcher shows the exact command Hermes will run.
With the default it reads something like
claude --permission-mode acceptEdits '...'. Pick Ask and the flag
disappears, because Ask is Claude Code's normal mode.

The Where row is the other thing that looks different in a fresh
folder. Normally Hermes starts each task on its own branch (a
named line of work in git) in its own worktree: a separate copy of
the project folder, so two agents don't step on each other. A branch
has to start from a commit, and a brand-new repository has no commits
yet. So in a fresh folder the agent starts directly in the folder
itself. That's expected, and it's fine for a first project with one
agent.

Press Launch. The agent opens in its own terminal with your prompt as
its first message, and the session's status changes to working.

Step 5: when it asks you something

Every session shows one status: working, needs approval, asked you,
done, error or idle. It's dimmed when Hermes is guessing it from the
screen. When the agent stops to ask permission or a question, a badge
in the title bar counts it. The inbox lists every agent waiting on
you, oldest first, and ⌘I (Ctrl+Shift+I on Windows and Linux)
jumps to the one that has waited longest.

You answer in the agent's own terminal. Hermes never answers a
permission prompt for you and never types into the terminal on its
own. What runs without asking depends on the approval mode from Step
4, and with the defaults that includes file edits.

Step 6: look at what it did, turn by turn

Each time the agent finishes a turn, Hermes saves it. A bar under the
terminal has Diff to see what that turn changed and Restore to
put the files back the way they were, with Undo if you change your
mind. ⌘G (Ctrl+Shift+G on Windows and Linux) opens the Review
Desk, where changes are grouped by turn or by file and risky edits get
flagged.

When you're happy with the result, make your first commit. Type the
commands in a terminal opened in the project folder, not in the
agent's terminal, which is busy running the agent. Your system's
terminal works (Terminal on macOS, Git Bash or PowerShell on
Windows). Inside Hermes, open the New Session window with ⌘⇧N
(Ctrl+Shift+H on Windows and Linux), pick the folder and choose
Plain shell as the agent.

If this is your first commit on this computer, tell git who you are.
You do this once per machine:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
Enter fullscreen mode Exit fullscreen mode

Then commit:

git add -A
git commit -m "First version of the to-do page"
Enter fullscreen mode Exit fullscreen mode

From now on the repository has a commit to branch from. Your next ⌘N
task starts on its own hermes/<task> branch, in its own worktree.

Building blocks stacking into a small house, marked with a branch, a shield and a scroll

Glossary

Term What it is Why an agent project needs it
Git repository A folder git tracks, with every saved version You can see and undo what the agent changed
.gitignore A list of files git should skip Keeps secrets, logs and installed packages out
AGENTS.md Plain-text instructions for coding agents Codex, Cursor and many others read it
CLAUDE.md Claude Code's own instructions file @AGENTS.md inside makes Claude read the shared rules
Commit One saved snapshot of the project Branches and worktrees start from one
Branch A named line of work in git Each task's changes stay apart until you merge them
Worktree A second working copy of the same repo Each task gets its own copy, so agents don't collide
Turn One round of the agent's work Hermes saves each one so you can diff or restore it
Approval mode The agent's rule for what needs your OK Decides what runs without asking you

If this was useful

I build Hermes IDE, and the New folder form is for exactly this first
run. It's free, on macOS, Windows and Linux.
Download it (2.2.9 or later), press
⌘N (Ctrl+Shift+N), click New folder…, then press ⌘J
(Ctrl+Shift+M) and pick your first prompt.

When you're running two agents on the same project, read
how to run Claude Code, Codex and Antigravity CLI on one repo.
For why I think agents belong at the centre of the IDE, read
The Editor-First IDE Is Dead.

Hermes is built in the open. If it helped, a
star on GitHub helps other
developers find it. If something confused you, open an issue there.
Beginner questions count as bug reports.

If you want the patterns behind agents themselves, my AI Agents
Pocket Guide is the short read.

AI Agents Pocket Guide: Patterns for Building Autonomous Systems with LLMs

Top comments (0)