How to give Claude or Codex your whole project as context

You ask Claude to refactor a module, or ask Codex to add a feature, and the answer is confidently wrong. It invents a function that does not exist, ignores your config, and misses the one file where the real logic lives.

Nine times out of ten, the model is not the problem. The context is. The assistant only saw the two files you pasted, not the project they belong to. It was reasoning about a keyhole view and guessing at the rest.

"Give the model the whole project" sounds obvious, but doing it well is not the same as dumping every file into a chat window. This guide separates two workflows: letting a coding agent work directly inside a repository, and creating a portable context.md for browser chats, model changes, and mixed project documents.

Why one or two files is never enough

Modern coding assistants are good at reasoning across a lot of text. The bottleneck is rarely their ability to read — it is what you actually give them. A model can only connect the dots it can see.

When you paste a single file, the assistant has no idea how it is called, what types flow into it, which config toggles change its behavior, or what the tests expect. So it fills the gaps with plausible-sounding assumptions. That is where hallucinated APIs and off-by-one architecture decisions come from.

Whole-project context fixes this by giving the model the surrounding evidence: the entry point, the module you care about, the relevant config, the schema, the docs, and maybe an example test. Not everything — just enough that the assistant reasons from your project instead of from the average project it saw in training.

What "whole-project context" really means

Whole-project context does not mean every byte in the repository. A large codebase will not fit in a prompt, and most of it is noise for any single task. Dependencies, build artifacts, lockfiles, and generated code rarely help the model and quickly burn through the context window.

What you actually want is a curated project view: the files that matter for the task, each clearly labeled, with enough structure that the assistant can tell where one source ends and the next begins. Think of it as briefing a new engineer. You would not print the whole repo and drop it on their desk. You would hand them the handful of files that explain the shape of the thing.

Good context is curated, not complete. The goal is signal, not volume.

A useful project context pack usually contains a mix like this:

• The main entry point and the module the task touches.
• Relevant config: package.json, tsconfig, environment templates, CI files.
• Type definitions or schemas that describe the data.
• The README or architecture notes that explain intent.
• One representative test, so the model learns your conventions.
• Any spec, PDF, or design doc that defines the requirements.

Agent-native repository access vs a portable context.md

Claude Code and Codex can work inside an authorized project workspace. In that mode, the agent can inspect the repository structure, search for relevant files, follow imports, run permitted commands, and read project instructions. You do not need to flatten the entire repository into one prompt first.

The two approaches are complementary. Use repository access when the agent must navigate and change code. Use a portable pack when the destination cannot read the repository directly or when requirements live across PDFs, DOCX files, exports, notes, and configs.

What CLAUDE.md does

CLAUDE.md is a Claude Code instruction and project-memory file. It is useful for stable guidance such as architecture notes, coding conventions, build and test commands, and recurring workflows. Claude Code discovers these files according to its project hierarchy and loads the relevant guidance into its working context. See Anthropic's official Claude Code memory documentation.

It should describe how Claude works in the repository; it should not contain a giant snapshot of every source file. Keep task-specific evidence in the task or a portable context pack.

What AGENTS.md does

AGENTS.md gives Codex persistent instructions and context for a project. Codex can combine global guidance with repository-level and nested instructions, allowing more specific rules closer to the files being changed. Typical content includes required test commands, repository conventions, architectural constraints, and review expectations. See OpenAI's official AGENTS.md guide.

Like CLAUDE.md, it is an instruction layer rather than a generated archive of the repository. MarkDone does not create or replace either file.

When browser chats need context.md

A browser chat usually cannot inspect your local repository on its own. A portable context.md is useful when you want a second opinion from another provider, need a reviewable handoff for a colleague, or must combine repository documentation with material stored elsewhere.

This is especially helpful for mixed projects where the brief is in DOCX, the research is in PDF, the API example is JSON or TOON, deployment settings are YAML, and feedback arrives as CSV. Those sources often sit outside Git but still define what the code should do.

The quick approaches, and where they break

Most people reach for one of a few habits to get a project in front of an assistant. Each works a little, then hits a wall.

Pasting files one at a time. This is the default, and it is where source boundaries disappear. After the third paste, the model can no longer tell which snippet came from which file, and you have lost track of what you already included. It is slow, error-prone, and easy to accidentally leave out the one file that mattered.

Zipping the repo and uploading it. Some tools accept an archive, but you lose control over what goes in. Node modules, build output, and secrets ride along, the token count explodes, and you cannot review what the model is actually reading before it reads it.

Pointing the assistant at a public repo. This only works for public code, gives you no control over which files are emphasized, and does nothing for private work, unpushed changes, PDFs, or design docs that live outside the repository.

Screenshots of code. Common and almost always a mistake — the model has to OCR the image, indentation gets mangled, and long files are cut off at the screen edge.

The common thread is a lack of structure and a lack of review. You either give the model too little with no labels, or too much with no boundaries, and in both cases you cannot see what it sees.

What good context material looks like

Before packaging anything, it helps to know what makes a project readable to a model. Four properties do most of the work.

Clear source boundaries. Every file should be wrapped so the model knows exactly where it starts and ends, with its name attached. This lets the assistant cite the right file and reason about how they connect, instead of treating everything as one undifferentiated blob.

File names and metadata. A path like src/auth/session.ts tells the model far more than the code alone. Names carry intent. A short table of what is included up front helps the assistant orient before it reads a single line.

A token budget you can see. A project view can easily run tens of thousands of tokens. Knowing the size up front tells you whether to trim before you paste, rather than discovering the limit halfway through a conversation.

No secrets. Config files are exactly where API keys, database URLs, and tokens hide. A project pack that includes .env is a project pack you should not paste anywhere until it is redacted.

Package mixed project documents into one context.md

For a browser chat or cross-provider handoff, combine the documents you chose into a single structured Markdown file — a context.md — and hand that to the assistant. Markdown is plain text, so it is readable by both you and the model, and it travels to any tool without conversion.

You can assemble it by hand: collect the files, wrap each one with a labeled begin/end marker, add a summary table at the top, scan for secrets, and check the token count before you send it. It works, but it is tedious and easy to get wrong on a real project.

The faster path is to let MarkDone's AI Context Builder assemble selected material locally in your browser. Add a reviewed project folder or individual PDF, DOCX, Markdown, JSON, TOON, YAML, CSV, text, and common source-code files; it produces one context.md with:

• A summary table of every source and its token count.
• Relative project paths and a compact included-file tree for folder imports.
• One clearly marked section per file, with begin and end boundaries.
• Automatic detection of API keys, tokens, and other secrets, with optional redaction.
• A running token total, so you know the size before you paste.
• A single copy action for Claude, Codex, or any assistant.

Because it runs in the browser, the selected files are not uploaded. You review the finished Markdown before it goes anywhere. For folders, MarkDone keeps relative paths, reads root and nested .gitignore rules locally, and leaves common dependency, build, generated, binary, and sensitive files visible but unchecked by default. It supports common web, backend, systems, shell, and project-file formats; it does not clone a remote repository or replace an agent's native repository access.

What a project context pack looks like

The exact layout can vary, but a project handoff for a coding assistant tends to look like this:

# Project Context Pack

## Use This Context For

- Add rate limiting to the login route without breaking existing tests.

## Pack Summary

| # | Source | Type | Tokens |
|---|---|---|---:|
| 1 | README.md | Markdown | 610 |
| 2 | architecture.md | Markdown | 940 |
| 3 | requirements.pdf | PDF | 1,180 |
| 4 | package.json | JSON | 240 |
| 5 | deployment.yaml | YAML | 520 |

## Source 3: requirements.pdf

--- BEGIN SOURCE: requirements.pdf ---
...
--- END SOURCE: requirements.pdf ---

The task line, the summary table, and the labeled source boundaries are what turn a pile of files into something a model can reason about.

With this in front of it, Claude or Codex can compare the architecture notes, requirements, package metadata, and deployment settings. For implementation work, let the coding agent inspect the repository itself and use the pack as supporting task context.

Watch the token budget

Even a curated project pack can get large. Context windows are bigger than they used to be, but a bloated prompt is still slower, more expensive, and harder for the model to use well — relevant details get buried under boilerplate.

If your pack is heavy, trim it: drop generated files, cut unrelated modules, and keep one representative example rather than ten near-identical ones. Check the size with a token counter before you send it. When a big chunk of the pack is structured data rather than code, a compact format like TOON can cut the token cost noticeably — see what your JSON really costs in an LLM prompt for the numbers.

Keep it private and redacted

Your source code, configs, and internal docs are some of the most sensitive files you own. The moment they leave your machine, they are subject to whatever retention and training policy the tool on the other end happens to have.

Two habits keep this safe. First, redact before you send — config files in particular are full of keys and connection strings, and a secret scanner catches the obvious ones before they reach a prompt. Second, prepare the pack locally so you can review exactly what is included before anything is uploaded. If you want the broader picture on where files go once you hand them over, read what really happens after you click upload.

How this differs from repo-packing tools

Developer tools such as repo packers flatten a Git repository into a single file for an LLM. MarkDone does not do that. It complements repository-native tools by combining supported documents and structured-data files that may live outside Git: a PDF spec, DOCX requirements, Markdown notes, JSON or TOON data, a CSV export, and a YAML config. It prepares those selected files in the browser and scans their extracted text for common secrets.

For a deeper walkthrough of the format itself, and how to build one from non-code files too, see how to build an LLM context pack from local files.

For task-specific examples, see how to prepare a codebase for AI code review and how to give Claude context for a bug fix.

Use context.md for model changes and handoffs

A portable pack is valuable when work moves between Claude, Codex, ChatGPT, Gemini, or a local model. The task, source list, warnings, and evidence travel together, so the next model does not depend on hidden conversation history.

Review and refresh the pack before each handoff. Project instructions such as CLAUDE.md and AGENTS.md remain with their native agents; context.md carries the selected evidence for the task.

The takeaway

When Claude or Codex gives you a bad answer about your own project, the fix usually is not a cleverer prompt. It is better evidence. Pick the files that explain the task, package them into one structured, secret-scanned context.md, and hand the model something it can actually reason about.

Curate the sources, keep the boundaries clear, watch the token count, and review it before it leaves your machine. Do that, and almost any assistant stops guessing and starts working from your project.