Running a coding agent
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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
Links
- Builds on: Delegating to an agent
- Leads to: Deciding and specifying, Plan, implement, verify
- Competencies drawing on it: Ships a change with a coding agent through plan, implement and verify
Lessons
- Your first session with a coding agent (tutorial)
- Keeping API keys out of the agent's reach (tutorial)
- Sandboxing a coding agent (tutorial)
Your reference
Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.
Your first session with a coding agent
Unlocks when you finish Your first session with a coding agent.
Takeaways
- Start the agent in the directory that's the task's world, and ask it to explain before you ask it to change.
- Find the evidence yourself first: the file, the failing test, the wrong output. Then put those in the brief, with limits and a done-criterion.
- The permissions prompt is where your judgment enters; weigh the blast radius, and keep the prompt on.
- Pick the permission mode per task: read-only for a question, the prompt for a first change in a project, accept edits only where git can restore what you did not read, and skip every check only inside a sandbox.
- The agent's summary is a claim. The diff is the evidence, and you run the check you named.
- Give each task its own session. Reset the fixture and start fresh.
Example
Show the list · open in the lesson
Run this, and compare what you see with the output below.
python3 todo.py listPrints the lines below (verified in CI from site/examples/coding-with-agents/first-session/list.py)
1. [ ] Buy milk 2. [x] Call the plumber 3. [ ] Water the plants
Keeping API keys out of the agent's reach
Unlocks when you finish Keeping API keys out of the agent's reach.
Takeaways
- A coding agent's key is billed to you. Use a personal key, never a shared one, and keep it in a password manager.
- A key never goes in a file the agent can read and commit. The shared settings file is both. Hand the key over through an environment variable set from the password manager, or let a key helper fetch it at start.
- Deny the agent's reads of the secrets that stay in the repository, such as
.env..gitignorekeeps a file out of commits and does nothing about the agent reading it. - Run a secret scanner over the working directory and the transcript, and read every line of the report.
- A key that appears where it shouldn't is revoked first and investigated second.
Example
Start the agent · open in the lesson
Run this, and compare what you see with the output below.
python3 agent.pyPrints the lines below (verified in CI from site/examples/coding-with-agents/keys-and-secrets/where_is_the_key.py)
key sk-fake-...c0de from .agent/settings.json (env.AGENT_API_KEY) deny rules: none
Sandboxing a coding agent
Unlocks when you finish Sandboxing a coding agent.
Takeaways
- A file the agent reads goes to the model provider in the next request, whether or not a sandbox is on. A sandbox limits which files it can read and which hosts it can send them to.
- The ways to contain an agent run from the built-in sandbox, quick to start and limited to shell commands, through the sandbox runtime, containers, dev containers and virtual machines, to a vendor-hosted agent that needs no setup and gives you only the vendor's controls.
- A permission rule, a hook or a prompt checks what the agent asks for, and injected text can steer that request. For the controls that matter most, limit what the running process can reach: a network allowlist enforced by a proxy, and credentials held by a sidecar.
- In Claude Code,
allowedDomainslists the hosts,strictAllowlistblocks the rest without asking when it comes from your own or a passed settings file, andallowUnsandboxedCommands: falsewithfailIfUnavailable: truestops the agent's commands from running outside the sandbox. - Keep a token the agent needs in a proxy or sidecar that adds it on the way out, and assume the agent can use it for the whole session.
Example
Which commands get out? · open in the lesson
Read the settings and the three commands above. For each command, decide whether the sandbox lets it through, asks you, or blocks it. Then run the script from the fixture's folder and compare.
python3 check_allowlist.pyPrints the lines below (verified in CI from site/examples/coding-with-agents/sandboxing/check_allowlist.py)
allowedDomains: pypi.org deniedDomains: (none) strictAllowlist: true 1. pypi.org:443 allowed (matches pypi.org) 2. files.pythonhosted.org:443 blocked, no prompt (not on the list) 3. collect.example.invalid:443 blocked, no prompt (not on the list)
Sources
AEC-12Getting started with Claude Code, Agent Engineer Course (course)DLAI-5Claude Code: A Highly Agentic Coding Assistant, DeepLearning.AI (course)Academy claude-code-101Claude Code 101, Claude Academy (course)Academy claude-code-in-actionClaude Code in action, Claude Academy (course)