Vibe Coding: Let's take a look under the hood of Claude Code. Part 1

06:58
24.07.2025
DmitriiFilippov
22

In this article, we will dive into the inner workings of Claude Code - an agent designed to assist in development by Anthropic. We will analyze it from an architectural perspective, look at the available tools, and break down the system prompts that define its behavior.

In this article, we will dive into the inner workings of Claude Code - a Coding agent from Anthropic. We will analyze it from the perspective of its architecture, look at the available tools, and break down the system prompts that define its behavior.

I replaced its standard Claude model with GPT-4.1, which allowed me to thoroughly analyze the logs, architecture, and system prompts that define its behavior.

Vibe Coding: Diving into the code of Claude - Analyzing structure and algorithms.

Let’s start with the basics. Claude Code uses the ReAct - Agent (Reasoning and Acting) architecture, which allows the agent to interact with the environment through a set of specialized tools to perform tasks.

Available Tools - Claude Code

The agent has access to the following tools:

Vibe Coding: Uncovering the secrets of working with Claude - A first look at the code.

Tools for Working with Files and Code

Tool	Description and Features
Read	Reads the content of a file. It can display images (PNG, JPG) and work with temporary screenshot files. It is recommended to read several potentially useful files at once.
Write	Writes new content to a file, completely overwriting it. If the file already exists, it must be read first.
Edit	Performs specific line replacement in a file. Requires an exact match of the replaced line, including indentation. The file must be read before editing.
MultiEdit	Allows multiple replacement operations in a file in one step. Changes are applied sequentially and atomically: either all or none.
NotebookRead	A specialized tool for reading cells and their output from Jupyter Notebook files (.ipynb).
NotebookEdit	Edits cells in Jupyter Notebook, supporting insertion, replacement, and deletion operations.

Tools for Searching and Navigation

Tool	Description and Features
LS	Outputs a list of files and directories at the specified absolute path.
Glob	Quickly finds files by pattern (e.g., *.py). Results are sorted by modification time, which helps to find the most recent files.
Grep	Powerful content search in files using ripgrep. Supports multi-line search and various output formats.
WebSearch	Performs internet search. Allows filtering results by domain and takes into account the current date for up-to-date information.
WebFetch	Extracts and processes content from a web page. It does not simply download HTML, but converts it to Markdown and analyzes it using a fast AI model.

Tools for Task Management and Command Execution

Tool	Description and Features
Task	Launches a new, independent agent to perform complex subtasks, such as file searching when the result is not obvious. Enables parallelization of work.
Bash	Executes commands in a persistent Bash shell session. Used for working with Git and GitHub (gh). Not recommended for searching and reading files — Grep, Glob, and Read are better suited for that.
TodoWrite	Creates and manages a structured to-do list. A critical tool for planning and tracking progress in multi-stage tasks.
exit_plan_mode	Ends the planning phase and moves directly to coding. Used to confirm the plan with the user.

⚠️Complete description of all tools with parameters is posted on GitHub — the link is also available on my Telegram channel.

System Prompt

If the total description volume of tools is about 10,000 tokens, the system prompt adds another 2,700 tokens, which describes in detail the tasks, capabilities, and limitations of the agent, with constant reminders about the prohibition of creating malicious code.

Key Features of the Prompt

Few-Shot Approach: Active use of examples to explain correct behavior. Even for demonstrating brief responses, specific examples are provided.

Incomplete Tool Description: Interestingly, the system prompt only mentions the most critical tools and does not provide a comprehensive list. This suggests that Claude, like OpenAI, is moving away from the practice of listing all tools and their parameters in the system prompt itself.

Role of TodoWrite: The tool TodoWrite plays a central role in the architecture. Instructions not only mention it but insist on its "VERY frequent" and "critically important" use, turning it into a fundamental mechanism for solving complex tasks.

User's First Message and Dynamic Context

The approach to handling the user's first message is quite interesting. In addition to the main request, system reminders are passed to the model:


When answering user questions, you may use the following context:
# important-reminders-about-instructions
Do what you are asked to do; no more, no less.
NEVER create files unless they are absolutely necessary...
ALWAYS prefer editing an existing file over creating a new one...


Hello, can you check which folders are in my terminal?


This is a reminder that your to-do list is currently empty...
please use the TodoWrite tool to create it...

This mechanism serves two functions:

TodoWrite: Task Management

Let's take a closer look at the TodoWrite tool.

It is used to plan and break down complex tasks into manageable steps and inform the user about progress.

Basic principles of TodoWrite:

Frequent use: The tool is used for any non-trivial tasks that require more than two steps (but if asked to use the tool in a message, it will be invoked even if you're solving a task like 2+2).
Status management:
- pending: The task is waiting to be completed.
- in_progress: The task is in progress (only one task at a time).
- completed: The task is successfully completed.
Strict rules: A task is marked as completed ONLY after it has been fully and correctly completed.

Example JSON generated by TodoWrite:

[
  {
    "content": "Create folder project_ai",
    "status": "pending",
    "priority": "high",
    "id": "1"
  },
  {
    "content": "Create main.py file inside the project_ai folder and write a simple program in it",
    "status": "pending",
    "priority": "high",
    "id": "2"
  },
  {
    "content": "Check if the file and folder were created successfully",
    "status": "pending",
    "priority": "high",
    "id": "3"
  }
]

Example of a task sequence

Let's see how TodoWrite is used in practice with the task: "Create README file andmain.py".

User's request: "Create a README file and main.py with a simple program."
Planning: The assistant calls TodoWrite and creates two tasks with the status pending.
Start working: The assistant calls TodoWrite again to change the status of the first task to in_progress.
Creating the file: The assistant uses the Write tool to create the README.md file.
Completing the first task: After successfully creating the file, the assistant calls TodoWrite, changing the status of the first task to completed and the second to in_progress.
Working on the second task: The process is repeated for the main.py file.
Completing all tasks: The assistant marks the last task as completed.
Final response: "The README.md and main.py files were created..."

TodoWrite Implementation Features

I noticed that every time the status of a specific task is updated, the LLM is forced to send the entire todos list. It would be much more efficient to send only the task id and the new status. When working with a 12-step list, the model sends the entire list every time, even for updating just two statuses.

The current approach, where the model constantly sends the entire plan, creates a loophole. The LLM can "hallucinate" and subtly adjust the original plan to match the one it actually performed, rather than the one that was initially intended, simply by sending the necessary actions.

Another point: the response from TodoWrite only confirms the status update, but does not inform, for example, about the completion of all tasks or show the remaining list, which I think would be more useful.

In the next article, we will connect Claude Code to models from other providers, which will allow it to be run even with local models.

BONUS the leaked ClaudeCode from four months ago - https://github.com/ripgrim/anon-kode/tree/main

Leave a comment if there are any other aspects of Claude Code's internal workings you're interested in, and we’ll try to analyze them!

And don’t forget to check out my Telegram channel.