Your First Session with a Terminal Coding Agent: A Walkthrough

Your first session with a coding agent should be small, on a throwaway branch, in a project with tests. The goal is not to build something impressive. It is to learn the rhythm: you describe a task, the agent reads and proposes, you approve or refuse actions, and you review the diff. This walkthrough uses Claude Code as the example, but the same steps apply to other terminal agents.

Step 1: Prepare the project

Install the tool by following the vendor's current instructions, then sign in. Do this outside the project folder if you like; the install is separate from your code. Before you start, make sure your working tree is clean so every change the agent makes is easy to see.

cd my-project
git status                 # should say "nothing to commit"
git switch -c try-agent    # throwaway branch
npm test                   # confirm tests pass BEFORE the agent touches anything

That last command matters. If tests already fail, you will not know whether the agent broke something.

Step 2: Start the agent in the project folder

claude

The agent starts an interactive session rooted in the current directory. It can see files under that folder. It may ask whether you trust the folder; answer only if you do. From here you type requests in plain English.

Step 3: Ask a question before asking for a change

A read-only question is the safest first prompt and shows how the agent explores:

Give me a short overview of this project: what it does, the main folders,
and how to run the tests.

Watch which files it reads. If its summary is wrong, you have learned something useful: your README or project instructions are missing information. We fix that in the next few posts.

Step 4: Give one small, checkable task

Add input validation to the createUser function in src/users.js:
reject an empty name or an email without "@" by throwing an Error with a
clear message. Add tests for both cases and run npm test.

This prompt names the file, the function, the exact behaviour, where the tests go and how to verify. Vague prompts such as "improve user handling" force the agent to guess.

Step 5: Handle permission prompts

When the agent wants to edit a file or run a command, the tool shows the request and waits. You can usually approve once, approve for the session, or deny. In your first session, approve edits one at a time and read each command. Be cautious with anything that deletes, installs packages, uses the network or touches files outside the project. Denying is always safe; the agent will try another way or ask you.

Step 6: Review the result yourself

When the agent says it is done, do not take its word. Use git:

git status
git diff
npm test

Check that only the expected files changed, the validation matches what you asked, and the new tests really fail if you remove the validation. If you like the result, commit it. If not, throw it away:

git restore .              # discard edits to tracked files
git clean -fd              # remove new untracked files (careful: deletes them)

Step 7: Steer with a follow-up

If the result is close, do not start over. Say what to change: "Use the existing ValidationError class from src/errors.js instead of Error." Follow-ups keep the useful context in the session.

Why this rhythm matters

Every later skill in this course builds on the same cycle: a clear request, bounded permissions, and an honest review. If you learn to keep each pass small, you can always see what changed and why. People who skip this stage and hand over large tasks early tend to spend more time untangling the result than they saved. Treat the first few sessions as practice for reading agent output, not as a test of the tool. Write down any surprise, such as an unexpected file edit or a command you did not anticipate, because those notes become the first lines of your project instruction file.

What to notice in your first hour

• How many files the agent read before editing.
• Whether it ran the tests without being told.
• Whether it touched files you did not mention.
• Which of your project conventions it missed. These go into your instruction file.

First-session mistakes

• Working on your main branch with uncommitted changes.
• Granting broad "always allow" permissions before you understand them.
• Starting with a large feature instead of a ten-minute task.
• Skipping the diff because the tests passed.