🧭 Fundamentals

An agent is a program that perceives its environment, makes decisions, and acts autonomously to achieve a goal — unlike a chatbot that only answers questions.

Understanding this difference is essential to knowing what to expect from Claude Code and how to request tasks efficiently.

Perception → Decision → Action; autonomous cycle; objective vs. one-time response; persistent context.

The terminal is a text interface that gives you direct access to the operating system—files, processes, network. It’s where the agent runs real commands.

Graphical interfaces are slow and difficult to automate. In the terminal, Claude Code can read, write, run, and search in seconds.

Shell, stdin/stdout, pipe, file permissions, PATH, child process.

Claude Code uses concrete tools: Read (reads files), Edit (modifies files), Bash (runs commands), Search (searches for patterns in code).

Knowing what tools are available helps you understand what the agent can and can’t do for each task.

Read, Edit, Write, Bash, Glob, Grep — Claude Code’s native tools.

Refactor code, build features, write tests, migrate APIs, fix bugs, generate documentation — all without leaving the terminal.

Limiting the scope of use increases effectiveness. Knowing "where the agent shines" saves time and prevents frustration.

Code tasks, repository automation, CI/CD, boilerplate generation, log analysis.

A chatbot responds to text. An agent takes actions in the real world: creates files, runs tests, makes commits. Claude Code is an agent.

Changing the mindset from "asking" to "delegating tasks" transforms how you use the tool.

Action vs. response; side effect; execution permission; controlled autonomy.

The first contact: open the terminal, type claude, give it a simple task and watch the agent work step by step.

Seeing the agent work in practice—with the tools appearing in real time—is the best way to internalize the concept.

Interactive session, headless mode, claude --help, first delegated task.

The agent runs a continuous cycle: Think (reason about what to do), Use Tool (real-world action), Observe (read the result) and repeat.

Understanding the loop helps you write better tasks and know why the agent asks certain questions or makes certain decisions.

ReAct loop, "chain of thought," environment observation, iteration until completion.

Tools are the agent’s “hands”: Read (reads files), Edit (edits files), Bash (runs commands), Glob (lists files), Grep (searches text).

Each tool has different costs, permissions, and scope. Knowing them helps you understand logs and optimize the workflow.

Tool call, tool result, explicit vs. implicit permission, token cost per tool.

Before acting, the agent reasons internally: breaks the problem into steps, identifies dependencies, and chooses the right tool for each step.

Providing enough context for the task makes the plan more accurate, reducing unnecessary back-and-forth.

Task decomposition, explicit vs. implicit plan, internal scratchpad, progress tracking.

The agent asks for confirmation before destructive actions (deleting files, running dangerous commands) or when it doesn't have enough context.

Knowing when and how the agent will pause to ask for help avoids surprises and helps you configure permissions correctly in settings.json.

allowlist, denylist, interactive confirmation, autonomous mode, --dangerously-skip-permissions.

The agent doesn't browse websites, click graphical UIs (without plugins), have memory between sessions by default, or have internet access without external tools.

Knowing the limits prevents mistaken expectations and helps you supplement with other tools when needed.

No native persistent memory, no GUI access, sandboxing, local project scope.

While it runs, Claude Code displays each tool call, what was read, and what was changed — the reasoning log is visible in real time.

Reading the logs helps you understand decisions, catch errors earlier, and gain confidence in what the agent is doing.

Verbose output, tool trace, explicit reasoning, human verification, safe interruption (Ctrl+C).

Context is everything the model "knows" at the moment: the conversation, the files read, and the results from tools. It’s the session’s active working memory.

Without understanding the context, you won't know why the agent "forgot" something or why its responses got strange at the end of the session.

Prompt, conversation history, tool results in context, CLAUDE.md as persistent context.

Tokens are fragments of text (≈ 4 chars in English, ≈ 3 in Brazilian Portuguese). Each word becomes 1–3 tokens. Models process and charge by the token.

Understanding tokens helps you estimate costs, manage context window usage, and avoid exceeding the limit that degrades responses.

Input tokens, output tokens, tokenizer, cost per 1M tokens, file length in tokens.

The context window is the maximum number of tokens the model can process at once. Claude 3 Sonnet has 200K tokens — about 500 pages of text.

When the window fills up, the agent starts to "forget" parts of the conversation, or the system truncates the context automatically.

200K tokens, automatic truncation, performance degradation, sliding window.

Context fills up because of: large files read in full, long histories, verbose responses, and many tool calls accumulated in the same session.

Identifying the culprit lets you take action: split sessions, use /clear, or change your file-reading strategy.

Large file, long history, accumulated tool results, unnecessary reading of binary files.

The command /compact resumes the previous conversation, freeing up space in the context window. Claude Code also compacts automatically when needed.

Knowing when and how to compact avoids losing critical context and keeps the agent effective during long sessions.

/compact, /clear, automatic summarization, CLAUDE.md as external memory.

Practices such as using CLAUDE.md for fixed instructions, splitting large tasks into smaller sessions, and avoiding unnecessary file reads save tokens and improve quality.

A lean context means more accurate responses, lower costs, and longer sessions before degradation.

CLAUDE.md, short focused sessions, selective reading, avoid copying entire code blocks into messages.

The terminal is a program that interprets text commands. On Mac: Terminal or iTerm2. On Windows: PowerShell or WSL. On Linux: any emulator.

Claude Code only works in the terminal. Without knowing how to open and use the terminal, you can't even start the agent.

Shell (bash/zsh), prompt ($), terminal emulator, stdin/stdout, exit code 0 = success.

The file system is a tree. Absolute path: /home/user/projeto. Relative path: ./src. The starting point is the current directory.

Claude Code operates in the directory where you start it. Understanding paths is essential for pointing the agent to the right files.

Root (/), home (~), absolute path, relative path, . (current), .. (parent).

cd (change directory), ls (list), mkdir (create folder), pwd (where I am), cat (view file), cp/mv/rm.

Claude Code uses these commands in almost every task. Recognizing them in logs helps you track what the agent is doing.

cd, ls -la, mkdir -p, pwd, cat, cp, mv, rm -rf (careful!), man (help).

A CLI (Command-Line Interface) is a program you control through text in the terminal: git, npm, python, claude are CLIs.

Claude Code IS a CLI. Understanding how CLIs work (flags, subcommands, --help) helps you use any command-line tool.

Flags (--flag), positional arguments, subcommands, --help, return code.

Package managers install CLIs: npm install -g @anthropic-ai/claude-code (Node), brew install (Mac), apt install (Linux).

Installing Claude Code is the first practical step. Understanding how package managers work helps you avoid installation errors.

npm, Node.js, PATH, global vs. local version, which claude, update.

Never run commands copied from the internet without understanding what they do. rm -rf /, curl | bash without checking, and sudo are unnecessary are real risks.

The terminal has real power over the system. A wrong command can delete files, expose credentials, or install malware.

Read before executing, use sudo sparingly, keep secrets in environment variables, and add .env to .gitignore.