Welcome to the fifth unit of Foundation — Getting Started with Claude Code! So far, we've learned what Claude Code is, how to manage sessions with essential commands, and how Claude autonomously uses tools to create files and execute commands. Now we'll explore where all this work is stored and how Claude maintains transparency about every action it takes.

In this lesson, we'll discover how Claude Code persists our conversations in plain text files on our filesystem and how the /resume command reconstructs previous sessions. Unlike many AI tools that operate as black boxes, Claude Code stores everything locally in standard formats that we can inspect, search, and understand.

When we work with Claude Code, every interaction builds on what came before. Claude remembers which files we created, what commands we ran, and the context of our project. This enables multi-turn conversations where we can say "update that function we wrote earlier" and Claude knows exactly what we mean.

But when we close a terminal session and return later, how does /resume restore our entire conversation? The answer: everything is written to disk in standard, human-readable formats. Claude maintains a simple directory structure in our home directory where all conversation data lives transparently. This means we can audit what Claude has done, search through our history, and never be locked out of our own data.

When we first interact with Claude Code, it creates a hidden directory in our home folder called ~/.claude. This directory stores all our global state: conversation logs, debug information, and session data.

Let's explore this directory ourselves. Right after starting Claude Code but before making any requests, we'll see:

After we make our first request to Claude, the directory expands:

Notice what changed: the history.jsonl file appeared, and the session-env/ directory was created. These are generated as soon as we start interacting with Claude.

Each subdirectory has a specific purpose: debug/ contains diagnostic logs, projects/ holds our conversation histories, session-env/ and track shell state, stores analytics, and manages task lists.

The projects/ subdirectory is where all our conversation logs are stored. Each project gets its own folder, and inside each project folder are individual conversation files:

Each .jsonl file represents a complete conversation session. The filenames are session identifiers (the same IDs from /status). Timestamps show when we last worked on that conversation. This is how /resume finds previous sessions: it scans this directory, reads the timestamps, and presents our most recent conversations.

The .jsonl extension stands for JSON Lines: one complete JSON object per line. This makes files easy to read, append to, and process with standard tools.

Here's what a conversation log looks like:

Each line records a specific event: our messages, Claude's responses (including tool uses), tool results, and file modification tracking. This gives us a complete, auditable record of everything that happened.

When we use /resume, Claude identifies our current project, lists all .jsonl files in the corresponding projects/ folder, and sorts them by modification time. When we select a conversation, Claude loads that entire .jsonl file sequentially, reconstructing the conversation from those JSON events.

For example, selecting "Sales analysis (3 min ago)" opens ~/.claude/projects/our-project/abc123.jsonl and reads each line. It processes user messages, assistant messages, tool calls, and tool results in order, rebuilding the entire context. By the time the file is fully loaded, Claude knows everything we discussed, every file we created, and every command we ran.

This is why /resume seamlessly continues conversations even after days or weeks—the complete history is preserved in those .jsonl files.

Because conversation logs are stored in standard text format, we can search them using familiar bash tools. Note: These bash commands should be run directly in your terminal, not inside Claude Code. We can count how many times we used a specific tool:

Or search for specific requests:

We can search by date, tool name, error messages, or any pattern using grep, awk, jq, and other standard tools. This is practical: if we remember discussing a feature last week but can't recall which conversation, we can search for keywords across all our logs.

The ~/.claude directory also contains a file called history.jsonl. This file serves a different purpose than conversation logs—it records the slash commands we've used across all sessions:

Conversation logs in the projects/ directory capture full interactions with Claude (messages, tool uses, outputs), while history.jsonl focuses specifically on command usage. Think of conversation logs as detailed transcripts of individual sessions and history.jsonl as a summary of meta-actions across all sessions.

Every action Claude Code takes is recorded in plain text files stored in predictable locations. We can see exactly what Claude wrote, trace every command executed, verify tool usage, search our entire history, and understand how /resume works. This transparency builds trust, enables debugging, supports accountability, and preserves our autonomy by ensuring we always control our own data.

In this unit, we've uncovered how Claude Code maintains transparency through conversation persistence. We explored the ~/.claude directory structure, examined the JSONL format, understood how /resume works by loading log files, and learned to search conversation history using standard bash tools.

Advanced users can create optional ~/.claude/settings.json or .claude/settings.json files for customization (see https://code.claude.com/docs/en/settings). For this course, we'll use slash commands like /model and /permissions instead.

Now it's time to put this knowledge into practice and experience these features firsthand in your own environment!