# Running a coding agent

> A coding agent works inside your repository with your tools. This topic gets a first session going: installing and configuring the agent, letting it read and explain the codebase, making a first small change, understanding what it asks permission for, where the sandbox around it ends, how to handle the API keys it uses without leaking them, and managing the session so its context stays useful.

Page: https://schubergphilis.github.io/ai-training/topics/coding-with-agents/first-session/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

*Coding with agents* · topic `coding-with-agents/first-session`

A coding agent works inside your repository with your tools. This topic gets a first session going: installing and configuring the agent, letting it read and explain the codebase, making a first small change, understanding what it asks permission for, where the sandbox around it ends, how to handle the API keys it uses without leaking them, and managing the session so its context stays useful.

## Concepts

- **Install and setup**: Getting a coding agent running in a terminal or editor: installing the tool, authenticating to a model provider, opening it in a repository and checking it can run the project's own commands. Setup is also where you decide what the agent may reach, so do it in a repository you can afford to have touched and with a clean working tree. [glossary](https://schubergphilis.github.io/ai-training/glossary/#install-and-setup)
- **Codebase understanding**: Using the agent to orient in unfamiliar code before changing it: ask where a feature lives, how a request flows, what a module depends on. The agent reads files and searches faster than you can, and its explanation is a fast first map. Verify the map against the code on anything you will act on, since agents summarize confidently. [glossary](https://schubergphilis.github.io/ai-training/glossary/#codebase-understanding)
- **First change**: A small, well-bounded edit done with the agent to learn how it works: a fix with a failing test, a rename, a documentation update. Brief it, watch which files it reads, read the diff it proposes and run the tests yourself. The point is to calibrate how it behaves in your project before trusting it with something larger. [glossary](https://schubergphilis.github.io/ai-training/glossary/#first-change)
- **Permissions**: What the agent may do without asking: read files, edit files, run commands, reach the network. Coding agents prompt for approval on risky actions by default and let you widen or narrow that. Approving everything for convenience turns a mistake in a command into a mistake in your repository or system, so widen access per project and per task. [glossary](https://schubergphilis.github.io/ai-training/glossary/#permissions)
- **Sandbox**: An isolated environment the agent runs in so that a wrong command damages only what is inside it: a container, a virtual machine or a separate user account. The sandbox limits which files, network destinations and credentials the agent can reach. It is a control you set up before the session, and a coding agent with no sandbox has exactly the access you have. [glossary](https://schubergphilis.github.io/ai-training/glossary/#sandbox)
- **Trust boundary**: The line between what the agent may decide on its own and what is enforced from outside it. Instructions in a prompt are requests the model can ignore or be tricked out of, so a control that matters is enforced by the harness, the operating system or the network. Knowing what the agent sends to its provider, from file contents to command output, is part of drawing that line. [glossary](https://schubergphilis.github.io/ai-training/glossary/#trust-boundary)
- **Secrets hygiene**: Handling the API keys and tokens an agent needs so a leak stays small. Use a personal key, never a shared one, and keep it in a password manager or an environment variable. A key never goes into a file the agent can commit. If a key may have been exposed, revoke it first and investigate afterwards, because rotation is cheap and a leaked key is used by someone else quickly. [glossary](https://schubergphilis.github.io/ai-training/glossary/#secrets-hygiene)
- **Session and context**: A session is one conversation with the agent and its context window is the session's memory. Every file read and command output lands in it, so long sessions fill up and the agent starts forgetting earlier instructions. Keep one task per session, start fresh for unrelated work, and ask for a summary before compacting or handing off. [glossary](https://schubergphilis.github.io/ai-training/glossary/#session-and-context)

## Links

- **Builds on:** [Delegating to an agent](https://schubergphilis.github.io/ai-training/topics/using-agents/delegating/)
- **Leads to:** [Deciding and specifying](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/specification/), [Plan, implement, verify](https://schubergphilis.github.io/ai-training/topics/coding-with-agents/workflow/), [Inspecting what the agent sends](https://schubergphilis.github.io/ai-training/topics/customizing-agents/inspecting-the-agent/)
- **Competencies drawing on it:** [Ships a change with a coding agent through plan, implement and verify](https://schubergphilis.github.io/ai-training/competencies/coding-with-agents/ships-with-agent/)

## Lessons

- [Your first session with a coding agent](https://schubergphilis.github.io/ai-training/coding-with-agents/first-session/) (tutorial)
- [Keeping API keys out of the agent's reach](https://schubergphilis.github.io/ai-training/coding-with-agents/keys-and-secrets/) (tutorial)
- [Sandboxing a coding agent](https://schubergphilis.github.io/ai-training/coding-with-agents/sandboxing/) (tutorial)

## Sources

- `AEC-12` [Getting started with Claude Code](https://lsimons.github.io/agent-engineer-course/12-getting-started-with-claude-code/), Agent Engineer Course (course)
- `DLAI-5` [Claude Code: A Highly Agentic Coding Assistant](https://www.deeplearning.ai/courses/claude-code-a-highly-agentic-coding-assistant), DeepLearning.AI (course)
- `Academy claude-code-101` [Claude Code 101](https://academy.claude.com/courses/claude-code-101), Claude Academy (course)
- `Academy claude-code-in-action` [Claude Code in action](https://academy.claude.com/courses/claude-code-in-action), Claude Academy (course)
- `OpenAI Academy get-started-with-codex-jkhsq` [Get Started with Codex](https://academy.openai.com/public/courses/get-started-with-codex-jkhsq), OpenAI Academy (course)