Your First Agent Session: Getting Real Work Done

Series: Claude Learning Journey · Getting Started

An agent session is where Claude moves beyond a chatbot and into tool use. You give it a goal, it works out how to achieve it, and it calls tools to read files, run commands, and make changes until the task is done. The session is stateful — Claude remembers what it has tried, what worked, and what did not.

Starting an agent session

In the desktop app, you are already in an agent-capable environment. When you give Claude a task that requires reading files, running commands, or making changes, Claude will automatically use its tools to accomplish it. You do not need to enable anything — the capability is present from the start.

For example, instead of just responding to a question, Claude can:

• Read files you reference
• Run shell commands
• Search the web
• Write or edit files
• Think through a multi-step problem autonomously

In the CLI, the --agent flag explicitly enables this mode:

claude --agent

The desktop app behaves as if agent mode is always on — Claude will use tools when the task calls for them.

Agent mode changes the interaction pattern. In a normal chat, you say something and Claude responds. In agent mode, you say something like “fix the login bug in auth.py” and Claude decides what to read, what to try, and what to change. You watch it work and either let it finish or redirect if it goes wrong.

What a real session looks like

Here is a simplified example of what actually happens in a useful session:

You: "The userprofile page is returning a 500 error on production but works fine locally. Can you help me track it down?"

Claude: I will start by looking at the userprofile route handler and the API call it makes.
[reads app/routes/users.py]
Claude: I can see the endpoint calls get_user_by_id(). Let me check that function.
[reads app/models/users.py]
Claude: The function assumes user.company_id is always present, but the migration last week made it nullable. The N+1 query is failing when company_id is null. Let me add a null check.
[edits app/models/users.py]
Claude: Done. I have added a null check. Do you want me to run the tests to verify it works?

That is a real bug investigation using the desktop app. The key difference from a normal chat is that Claude acted without being asked to read each individual file — it saw a path to the solution and followed it.

Knowing what to ask

The quality of the output is a function of the quality of the request. A vague request produces vague results. A specific, bounded request produces a specific result.

Vague: “Help me with the codebase.”

Specific: “Add rate limiting to the /api/search endpoint. Use an in-memory token bucket with a limit of 30 requests per minute per IP. Do not change the existing function signature.”

The second version tells Claude exactly what to do, what approach to use, and what constraints to respect. Claude will follow it precisely.

Bounded autonomy

You do not have to give Claude full autonomy. Agent mode still lets you guide it:

• “Read the file and show me what you found before making changes”
• “Do not touch anything in the migrations folder”
• “Confirm with me before running any destructive commands”

You can ask for a draft, review it, then say “go ahead” or “modify X first.” This works well when you want to stay in control without having to micromanage every step.

When agent mode is not the right tool

Agent mode is for tasks that require reading multiple files, running commands, and making changes. It is overkill for:

• Answering a factual question you can Google
• Writing a single small function from scratch
• Explaining a concept you could read in documentation

If the task is a 30-second fix, a normal chat is faster and more efficient. Agent mode earns its complexity on tasks that would take you 10 minutes of reading and editing.

Try it yourself

Think of one small task from your current project — a bug you have been meaning to look at, a function that needs writing, a refactor you have been putting off. Ask Claude to do it in agent mode and see what it produces. Review the changes before accepting them. Notice how the session felt compared to just asking in a normal chat.

What’s Next

Every conversation has a context — what Claude knows about the current situation. The next post covers contexts and how to manage what the model knows and forgets.

Part of the Claude Learning Journey series · Next: Understanding Contexts: What the Model Remembers