Your First Agentic CLI

Install Claude Code or Codex CLI, run your first multi-step task, and understand the agentic loop that drives everything - hands-on guide for builders new to agentic tools.

TL;DR: Agentic CLIs like Claude Code and Codex CLI are not chatbots in a terminal. They plan, act, verify, and loop - reading your files, running commands, fixing failures - until the task is done. This guide gets you installed, through your first real task, and under the hood in one sitting.

What "agentic" actually means

A regular AI chat tool waits for your next message. An agentic tool does not. When you give it a task, it enters a loop: gather context, take an action, observe the result, decide the next action, repeat. Every step is informed by what the previous step revealed.

In practice this looks like: you say "fix the failing tests" and the tool runs your test suite, reads the error output, finds the relevant source files, edits them, runs the tests again, and only stops when they pass - or when it needs your input to proceed. You are still in the loop; you can steer, correct, or interrupt at any point. But you are not the one chaining every step together.

That difference - the agent deciding its own next action instead of waiting for yours - is what people mean by "agentic."

Pick your tool: Claude Code or Codex CLI

Two first-party agentic CLIs are widely used as of mid-2026. Both are capable; the right choice depends on which AI platform you already use.

• Claude Code (Anthropic) - runs on Claude models, available with a Claude Pro, Max, Team, or Enterprise subscription or via the Anthropic Console. Native installer, VS Code extension, desktop app, and web interface all share the same underlying engine. Full docs at code.claude.com.
• Codex CLI (OpenAI) - runs on OpenAI models, included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans. Available on macOS, Windows, and Linux. Docs at developers.openai.com/codex.

The install and first-task steps below cover both. The concepts in "Under the hood" apply to either - the agentic loop is the same idea regardless of which model is doing the reasoning.

Install and authenticate

Claude Code

On macOS, Linux, or WSL, run the native installer (it auto-updates):

curl -fsSL https://claude.ai/install.sh | bash

On Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Alternatively, install via Homebrew (brew install --cask claude-code) or WinGet (winget install Anthropic.ClaudeCode). Then open your project directory and start a session:

cd your-project
claude

On first launch you are prompted to sign in. Follow the browser flow once and your credentials are stored - you will not be asked again.

Codex CLI

On macOS or Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

On Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Or with npm or Homebrew: npm install -g @openai/codex or brew install --cask codex. Then start:

codex

Sign in with your ChatGPT account or API key on first run.

Your first multi-step task

Once inside a session, describe what you want in plain language. The agent takes it from there.

Start by understanding the codebase

Before touching any code, ask the agent to orient itself:

what does this project do?

where is the main entry point?

The agent reads your files and summarizes. You did not have to point it anywhere - it found the relevant files on its own.

Make a real change

Try a concrete task:

write unit tests for the calculator functions, run them, and fix any failures

Watch what happens. The agent will:

1. Search your project for the calculator code
2. Read those files to understand the function signatures
3. Write a test file
4. Run the tests
5. If any fail, read the error output, fix the code or the tests, and run again

It asks your approval before modifying files (in the default permission mode). Approve once or enable "accept all" if you trust the direction it is heading.

Commit the result

commit my changes with a descriptive message

The agent stages the files, writes a commit message, and runs git commit. You can also ask it to create a branch, open a pull request, or resolve merge conflicts - git operations are fully conversational.

Under the hood: the agentic loop

Every agentic CLI runs the same core cycle. Understanding it helps you write better prompts and know when to step in.

The three phases

Claude Code's official docs describe the loop as three phases that blend together and repeat:

1. Gather context - read files, search for patterns, run a command to see current state, look up an error message online. The agent builds a picture of the situation.
2. Take action - edit a file, run a test, execute a shell command, write a new file. Each action is a tool call - a discrete, structured request the model makes to the runtime environment.
3. Verify results - read the output of the command it just ran, check whether the tests pass, compare before/after. The result feeds back into the next gather-context phase.

The loop continues until the task is done, until the agent needs information only you have, or until you interrupt it.

Tools are how agents act

Without tools, a language model can only produce text. With tools, it can act. The built-in tool categories for Claude Code are:

• File operations - read files, edit code, create and rename files
• Search - find files by pattern, search content with regex
• Execution - run shell commands, start servers, run tests, use git
• Web - search the web, fetch documentation, look up error messages
• Code intelligence - see type errors and warnings after edits, jump to definitions, find references (requires a code intelligence plugin for your language)

Each tool call returns information the model reads before deciding its next step. This is the feedback mechanism that makes the loop intelligent rather than scripted.

Permissions and safety

By default, the agent asks your approval before modifying files or running shell commands. In Claude Code you can cycle through modes with Shift+Tab:

• Default - asks before file edits and shell commands
• Accept edits - edits files and runs common filesystem commands (mkdir, mv, cp, etc.) without asking; still asks for other commands
• Plan mode - explores and proposes a plan without touching source files; permission prompts still apply as in default mode
• Auto mode - a research preview that lets Claude act without routine permission prompts; a background classifier reviews each action for safety before it runs

Before Claude edits any file, it automatically snapshots the file contents. If something goes wrong, run /rewind - or press Esc twice when the prompt input is empty - to open the rewind menu. From there you can restore your files, your conversation, or both to any earlier point in the session. Note that this only covers direct file edits; changes made by shell commands (like rm or mv) are not tracked, which is why Claude still asks before running commands with external side effects.

In Codex CLI, approval modes range from the default (reads, edits, and commands within the working directory, asking for external access) to read-only (no changes) and full access (unrestricted). The right mode depends on how well you know the codebase and how much you trust the current task.

Give the agent a memory: CLAUDE.md and AGENTS.md

Each session starts with a fresh context window. The agent does not remember what you told it last time - unless you write it down for it.

In Claude Code, create a CLAUDE.md file in your project root. The agent reads it at the start of every session. Put the things you would otherwise re-type every time:

# CLAUDE.md

## Commands
- Run tests: `npm test`
- Build: `npm run build`

## Conventions
- Use 2-space indentation
- API handlers live in `src/api/handlers/`
- Never push directly to main

Run /init inside a Claude Code session to generate a starting CLAUDE.md automatically - the agent analyzes your codebase and writes the file. You refine from there.

In Codex CLI, the equivalent is an AGENTS.md file in your repository. It tells the agent how to navigate your codebase, which commands to run for testing, and how to follow your project's conventions. The format is the same idea: plain text, kept short, read every session. Run /init in Codex to generate a scaffold.

Claude Code also builds auto memory as you work. It saves learnings like build commands, debugging patterns, and your preferences across sessions without you writing anything. The first 200 lines (or 25 KB) of its memory file load automatically at the start of each conversation.

Tips that make a real difference

• Be specific upfront. "Fix the bug where users with expired cards see a blank checkout screen - check src/payments/ especially token refresh" gives the agent a head start. "Fix the bug" works, but expect more back-and-forth.
• Give it something to verify against. "Implement validateEmail - test cases: user@example.com true, invalid false, user@.com false. Run the tests after." The agent performs better when it can check its own work.
• Explore before implementing. Use plan mode (press Shift+Tab twice from default in Claude Code) to have the agent read and plan without editing. Review the plan, adjust it in conversation, then let it build.
• Interrupt freely. Press Esc to stop mid-action and redirect. You are not stuck waiting for a long task to finish before steering.
• Iterate, do not restart. If the first attempt missed the mark, say what was wrong. The agent adjusts. You do not start over from a blank prompt.

Key takeaways

• Agentic CLIs run a loop - gather context, take action, verify results - without waiting for your next message at each step.
• Tools (file read/write, shell execution, web search) are what turn a language model into an agent that can actually do things.
• Claude Code installs with one curl command; Codex CLI installs the same way. Both work in your existing project directory with no special setup.
• CLAUDE.md (Claude Code) and AGENTS.md (Codex) are plain markdown files that give the agent persistent memory across sessions. Create them early - use /init in either tool to generate a starter file automatically.
• Permission modes and file snapshots keep you in control. Use /rewind or Esc twice (when input is empty) to access the rewind menu and restore code or conversation to any earlier point. Shell command side-effects (rm, mv, etc.) are not covered by snapshots.
• Specific prompts with verifiable outcomes (tests, expected output) produce better results than vague ones.

Try this next: Once you have run your first task, the next step is wiring the agent to external tools - databases, APIs, design docs - using the Model Context Protocol. See Model Context Protocol: Connect Your Agent to Everything to learn how MCP servers extend what your agent can reach.