A context workflow that introduces your project to a coding assistant accurately and under your control

How the system fits together

Project instructions (CLAUDE.md / AGENTS.md) → file selection for the task → Repomix bundle of the scope you chose → work with the assistant → change review → usage monitoring with ccusage.

• 
  Claude Code required

  Coding assistant that reads the project instructions and works with the context

  Tool guide

• 
  Codex optional

  Alternative coding assistant that reads the AGENTS.md file

  Alternative: If you use Codex instead of Claude Code

  Tool guide

• 
  Repomix required

  Collects the files you choose into a single context file, leaves out files that look like secret keys, and shows the token count

  Tool guide

• 
  ccusage optional

  Usage and estimated cost report from local Claude Code logs

  Alternative: Skip this step if you don't want to track spending

  Tool guide

• 
  Serena optional

  Symbol-level code search in a large repository (MCP server)

  Alternative: Only when the main path isn't enough, in the indexed branch

  Tool guide

• C
  codebase-memory-mcp optional

  Code knowledge graph for a large repository (MCP server); an alternative to Serena

  Alternative: If you prefer this over Serena; follow the developer's README to install it

  Tool guide

• 
  Spec Kit optional

  Plans a large feature by breaking it down from a specification into tasks; it does not replace a code index

  Alternative: If your problem is task planning, not context

  Tool guide

Before you start

Step-by-step setup

The steps you check stay only in this browser; they do not confirm that the setup works. You finished 0/9 steps.

1. Step 1 · In a code editor

   Add a persistent instruction file to the project

   I finished this step

   What for: The assistant reads the project's rules, commands and restrictions on its own in every session.

   1. Create CLAUDE.md in the root of the project folder if you use Claude Code, or AGENTS.md if you use Codex. In Claude Code, typing /init in a session makes the assistant generate a starter file; you correct it.
   2. Write only what the assistant can't figure out by reading the code: build and test commands, folders not to touch, naming conventions, project-specific pitfalls.
   3. Keep the file short: the Claude Code documentation targets under 200 lines per file. Don't write secret keys or passwords in it.
   4. If your project already has AGENTS.md and you want to use it in Claude Code too, there are two options: add the single line @AGENTS.md to CLAUDE.md (an import), or set /config > Project instructions to claude-md-and-agents-md in Claude Code. Reading AGENTS.md directly requires Claude Code 2.1.277+.
   Windows · macOS · LinuxFolder: Project folder

   › codex --ask-for-approval never "Summarize the current instructions."Copy

   AGENTS.md · mdCopy

   # Project rules
   
   ## Commands
   - Development server: npm run dev
   - Test: npm test
   - Build: npm run build
   
   ## Do not touch
   - dist/ and node_modules/ folders
   - .env files
   
   ## How to work
   - Read the relevant file first, then change it.
   - Run the tests after every change and report the result.

   A simplified template based on the sample AGENTS.md structure in the Codex documentation; change the commands to match your project. For Claude Code, the same content can live in a file named CLAUDE.md.

   How you know it worked

   • There is a CLAUDE.md or AGENTS.md file in the project root.
   • In Claude Code, if CLAUDE.md exists it appears in the Memory files list of the /context command. If only AGENTS.md is loaded, the sign described in the documentation is a line like 'no CLAUDE.md found; AGENTS.md loaded: <path>' shown in the conversation at the start of the session.
   • If you use Codex, the check command from the documentation summarizes the loaded instructions; it sends a model request and uses up your plan quota or costs money. The Codex steps follow the Codex documentation.
   If you get stuck: problems specific to this step

   • The project has both CLAUDE.md and AGENTS.md, but Claude Code reads only one
     By default, Claude Code doesn't read AGENTS.md when CLAUDE.md exists. Add the line @AGENTS.md to CLAUDE.md or set /config > Project instructions to claude-md-and-agents-md. If you have a CLAUDE.local.md file, it also prevents AGENTS.md from being read.
   • Codex doesn't see the end of a large instruction file
     Codex cuts off the combined instructions at the project_doc_max_bytes limit (32 KiB by default). Shorten the file or split it across subfolders.
   • The 'Project instructions' setting doesn't appear in /config
     According to the documentation, this means the session can't read AGENTS.md: Claude Code is older than 2.1.277; the built-in plugin that reads AGENTS.md has been disabled with /plugin; or you are in the first session after upgrading from 2.1.276 or earlier (it is read in the next session); Bedrock sessions and sessions with telemetry disabled are also affected below 2.1.281. In every case, put the @AGENTS.md import in CLAUDE.md.
   Based on: Claude Code docs: how Claude remembers your project (CLAUDE.md, AGENTS.md), OpenAI Codex docs: custom instructions with AGENTS.mdGet help with this step →
2. Step 2 · In a coding agent

   Select the files the task needs

   I finished this step

   What for: Put only the folders relevant to the task into the context bundle, not the whole repository.

   !You check this step yourself; the system should not move past it without your approval.

   1. Write the task in one sentence: what will change, and which page or module.
   2. Ask the assistant: 'Which files and folders should be checked for this task? Just give me a list, don't change any files.'
   3. Read the list yourself. Remove unnecessary folders and add anything you see missing. The --include patterns in the next step come from this list.

   How you know it worked

   • You have a short, approved list of the folders relevant to the task.
   If you get stuck: problems specific to this step

   • The assistant gives a very broad list every time
     Make your task sentence more specific. The Claude Code cost documentation says vague requests trigger broad scanning, while specific requests make it read fewer files.
   Based on: Claude Code docs: managing costs
3. Step 3 · In the terminal

   Check your Node version and Repomix

   I finished this step

   What for: See the environment the tool will run in before you start the bundle.

   1. Open the terminal in the project folder.
   2. First check the Node version. It must be 22 or higher.
   3. Then ask the version-pinned Repomix for its version. Repomix downloads the package itself on the first run; no separate installation is needed. npx may ask for confirmation (y) before downloading the package; if it asks, type y.
   Windows · macOS · LinuxFolder: Project folder

   › node --versionCopy

   Windows · macOS · LinuxFolder: Project folder

   › npx repomix@1.18.1 --versionCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   How you know it worked

   • node --version prints v22 or a higher version.
   • The Repomix command prints version 1.18.1.
   If you get stuck: problems specific to this step

   • Node turns out to be older than 22
     Repomix requires Node 22.0.0 or later. Before updating Node, check your project's own Node version rule (e.g. .nvmrc); don't change the project's version because of Repomix.
   • npx asks for confirmation, or the command is canceled in a non-interactive shell
     npx asks for confirmation before downloading a package that isn't available locally; the --yes flag skips this prompt. Run the command as npx --yes repomix@1.18.1 --version.
   Based on: Repomix guide: installation, Repomix npm registry data: version, license, Node requirement, npm docs: npxGet help with this step →
4. Step 4 · In the terminal

   Bundle only the scope you selected with Repomix

   I finished this step

   What for: Produce a single, controlled context file for the task with a visible token count.

   1. If the list from the previous step is the src/pages and docs folders, write the --include pattern in the command accordingly; patterns are separated by commas.
   2. Use --ignore to exclude unnecessary paths such as logs, build output and backups. Repomix also respects .gitignore, .ignore and .repomixignore files; for permanent exclusions, put a .repomixignore in the project root.
   3. --token-count-tree shows per-file token counts as a tree; the number at the end (500) is a threshold: only files with 500 tokens or more are listed, smaller files don't appear in the list. If you see a file larger than expected, narrow the scope.
   4. Don't turn off the security check. Repomix leaves files that look like secret keys out of the output and lists them in the terminal; still, look through the output file before sharing it.
   Windows · macOS · LinuxFolder: Project folder

   › npx repomix@1.18.1 --include "src/pages/**,docs/**" --ignore "**/*.log,dist/**" --token-count-tree 500 -o repomix-gorev.xmlCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   How you know it worked

   • repomix-gorev.xml is created in the project folder.
   • The token counts and the result of the security check appear in the terminal.
   • File contents come only from the paths you selected with --include (except those covered by ignore rules). The output also includes a file summary and a directory structure section.
   If you get stuck: problems specific to this step

   • The bundle is much larger than expected
     Find the largest files in the --token-count-tree output and add them to the --ignore list. The --compress option documented by the developer extracts only the structure of the code (classes, function signatures); don't use it if you need the details.
   • The security check removed a file from the output
     Don't force the file in. If it contains a secret key, move the key out of the file; if it doesn't, decide whether the task actually needs it. The Repomix page says the check targets common formats, so it may not catch every secret.
   Based on: Repomix guide: command-line options, Repomix GitHub README, Repomix guide: security checkGet help with this step →
5. Step 5 · In a coding agent

   Give the bundle to the assistant and request the task

   I finished this step

   What for: Give the assistant the context you selected together with a clearly defined task, and set the scope yourself.

   1. First, know this: a Repomix bundle does NOT LIMIT what a coding agent with file system access (Claude Code, Codex) can read; the agent can also read files outside the bundle. The bundle is mainly useful for showing your project to a chat assistant that takes file uploads. If you work with Claude Code or Codex, you usually don't need to hand over the bundle; a large XML file also uses up tokens.
   2. If you use a chat assistant, upload the repomix-gorev.xml file (Repomix also has a --copy option to copy it to the clipboard). If you use a coding agent, name the folders you selected and the places not to touch in your task sentence; you can also add this boundary to the instruction file.
   3. Tell the assistant to explain what it will do before making changes. If the plan is wrong or reaches files outside the bundle, narrow the task; don't start with a wrong plan.

   How you know it worked

   • The assistant presents a plan that matches your task sentence and the files you provided.
   • If the plan reaches folders you didn't expect, you notice it and narrow the task; Repomix doesn't prevent this on its own.
   If you get stuck: problems specific to this step

   • The assistant says it needs a file outside the bundle or wants to read it
     Coding agents can read outside the bundle too. If the need is real, add that path to the --include list and regenerate the bundle; if not, write a clear boundary into your task sentence.
   Based on: Repomix GitHub README, Repomix guide: command-line options, Claude Code docs: managing costsGet help with this step →
6. Step 6 · In the terminal

   Review the changes the assistant made

   I finished this step

   What for: No change becomes permanent in your project without you seeing it.

   !You check this step yourself; the system should not move past it without your approval.

   1. Check which files changed, then read the diff line by line.
   2. If a file you didn't expect has changed, ask the assistant why or revert that change.
   3. Run the project's tests yourself and look at the result. The assistant saying 'tests passed' isn't enough.
   Windows · macOS · LinuxFolder: Project folder

   › git statusCopy

   Windows · macOS · LinuxFolder: Project folder

   › git diffCopy

   How you know it worked

   • The list of changed files matches the task.
   • No change you don't understand or don't want remains in the diff output.
   If you get stuck: problems specific to this step

   • Many unrelated files appear to have changed
     Don't commit the changes. Tell the assistant to limit the task to the files in the bundle and try again; if needed, revert the changes with git.
   Based on: Git docs: git-diffGet help with this step →
7. Step 7 · In the terminal

   Name the bundle after the commit and recognize an outdated bundle

   I finished this step

   What for: Avoid mistaking an old bundle for a current one after the code changes.

   1. A Repomix bundle is like a snapshot: it doesn't refresh on its own when the code changes. Regenerate the bundle for every new task.
   2. First add repomix-*.xml files to .gitignore; don't commit bundles to the repository. Otherwise previous bundles show up in the git status --short output and it is never empty.
   3. Put the ID of the commit the bundle was generated from in the output file name. First get the ID (e.g. a1b2c3d), then write the file name with that ID by hand: repomix-a1b2c3d.xml. This naming is DijiKoçum's suggestion, not a Repomix feature.
   4. WARNING: the commit ID doesn't capture UNCOMMITTED changes. Before generating the bundle, the git status --short output should be empty; if it isn't, the bundle name gives false assurance.
   5. To check whether an old bundle is current, list the commits between the ID in the bundle name and the current commit: if the output is empty, it is current as far as commits go; if not, regenerate the bundle. git status --short shows uncommitted changes.
   6. The surum_tarihi in the commands is not the release date of the version but the day the version was checked (2026-10-17). Release dates are listed in the claims.
   Windows · macOS · LinuxFolder: Project folder

   › git rev-parse --short HEADCopy

   Windows · macOS · LinuxFolder: Project folder

   › git status --shortCopy

   Windows · macOS · LinuxFolder: Project folder

   › npx repomix@1.18.1 --include "src/pages/**,docs/**" --ignore "**/*.log,dist/**" -o repomix-a1b2c3d.xmlCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   Windows · macOS · LinuxFolder: Project folder

   › git log --oneline a1b2c3d..HEADCopy

   How you know it worked

   • You see a short commit ID; your output file name contains your ID instead of a1b2c3d.
   • If git status --short is empty and the git log output is empty, the bundle matches the current code.
   If you get stuck: problems specific to this step

   • The assistant mentions a file that was deleted or moved
     You may be using an old bundle. Run git log --oneline <id>..HEAD with the ID from the bundle name, also check git status --short, and regenerate the bundle.
   Based on: Git docs: git-rev-parse, Git docs: git-status, Git docs: git-log, Repomix guide: command-line options
8. Step 8 · In the terminal

   Monitor usage with ccusage

   I finished this step

   What for: See how your Claude Code usage changes when you change your context workflow.

   1. ccusage reads the local logs (JSONL files) that Claude Code keeps on your computer.
   2. The dollar amount shown is an estimate; it is not your Anthropic invoice or subscription fee. In the default auto mode, if the log contains a cost written by Claude Code, that is used; otherwise it is calculated from the token count using model pricing.
   3. For the calculation, ccusage uses pricing data from sources such as LiteLLM and models.dev; the CCUSAGE_OFFLINE=1 variable forces offline operation. The display mode shows only the cost recorded in the log and shows $0.00 where there is none. The documentation doesn't explain which requests go to the network by default, so don't assume ccusage never goes online.
   4. With Claude Code's default setting, logs are kept for 30 days. The retention period is set by cleanupPeriodDays; you raise it in Claude Code's settings file (settings.json) (minimum 1). If you want to see older usage, raise this setting first.
   Windows · macOS · LinuxFolder: Any folder

   › npx ccusage@20.0.34 claude dailyCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   Windows · macOS · LinuxFolder: Any folder

   › npx ccusage@20.0.34 claude sessionCopy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   How you know it worked

   • A table of token counts and estimated cost by date or by session appears.
   • The sessions in the table match your Claude Code work.
   If you get stuck: problems specific to this step

   • The report comes back empty
     ccusage looks for logs in ~/.config/claude/projects/ and ~/.claude/projects/. If you run Claude Code with a different data folder, the CLAUDE_CONFIG_DIR variable must point to that folder.
   Based on: ccusage guide: Claude Code data source, ccusage guide: cost modes, ccusage guide: environment variables, Claude Code docs: managing costs, Claude Code docs: the .claude directory and automatic cleanup
9. Step 9 · In the terminal

   Advanced option for a large repository: a code index with Serena

   I finished this step

   What for: In a large repository where file selection isn't enough, let the assistant search the code at the symbol level.

   1. This step is only needed when the main path isn't enough. Serena is installed with the uv tool; install uv first from the developer's page.
   2. Install Serena with a pinned version, initialize it with serena init, then run serena setup claude-code to connect it to Claude Code (serena setup codex for Codex). The Serena documentation gives the setup command as the automatic configuration route.
   3. If needed, ask the assistant something like 'Activate the project <project path>' so Serena recognizes your project (the Serena workflow page gives this format as an example and says the project is created automatically on first activation). For how the global configuration relates to the session, see Serena's configuration page.
   4. Index once in the project folder with the serena project index command. The developer says the index updates itself as files change during use; that page doesn't explain what happens to changes you make while Serena is not running.
   5. For Serena's file scope and installation notes, see the developer's user guide. For the codebase-memory-mcp alternative, the developer's README gives an install script that downloads and runs on macOS and Linux, and a download-first, inspect, then run route on Windows. This guide doesn't use lines that download and run directly; if you choose that tool, read the README and make your own decision.
   Windows · macOS · LinuxFolder: Any folder

   › uv tool install -p 3.13 serena-agent==2.0.0Copy

   Version pinned (as of October 17, 2026). Check the vendor documentation before moving to a newer version.

   Windows · macOS · LinuxFolder: Any folder

   › serena initCopy

   Windows · macOS · LinuxFolder: Project folder

   › serena setup claude-codeCopy

   Windows · macOS · LinuxFolder: Project folder

   › serena project indexCopy

   How you know it worked

   • The Serena commands finish without errors.
   • serena appears in the client's MCP server list (according to the documentation, setup registers it).
   If you get stuck: problems specific to this step

   • The client can't find the serena command
     The developer's documentation says the client may not find the command even if it is on PATH; give the full path to the serena executable in the client settings.
   • You want to install Serena from an MCP or plugin marketplace
     The Serena README warns against this: installation commands in marketplaces may be outdated. Use the uv command from the README directly.
   Based on: Serena GitHub README (installation, license), Serena docs: client configuration, Serena docs: project workflow and indexing, Serena PyPI entry (version, release date), codebase-memory-mcp GitHub READMEGet help with this step →

What you pay for

The items are separate, not a total; which ones you need depends on the path you set up. Prices change, so check the source of each item.

• SubscriptionCoding assistant — subscription route

  With Pro, Max, Team and Enterprise subscriptions, Claude Code usage is included in the plan and subject to the plan's limits; prices are on Anthropic's pricing page. For Codex, the terms of your plan are on OpenAI's side. source

• API usageCoding assistant — API route

  With an API/Console account, Claude Code is billed by token consumption. The estimate shown by ccusage does not replace this invoice. source

• No costRepomix and ccusage

  Both are MIT-licensed open-source command-line tools; they don't charge anything themselves. The context you send to the assistant while working increases the assistant's token consumption. source

• No costSerena (optional)

  Serena is licensed under GPL-3.0-or-later. The JetBrains plugin is separate and paid (a trial is available); the language server route in this guide doesn't require it. source

• Setup serviceSetup service

  If you like, DijiKoçum can set up the project instruction file and the context workflow for you; the scope is agreed in a call. source

Sources

• Claude Code docs: how Claude remembers your project (CLAUDE.md, AGENTS.md) · Official documentation · read October 17, 2026
• Claude Code docs: managing costs · Official documentation · read October 17, 2026
• OpenAI Codex docs: custom instructions with AGENTS.md · Official documentation · read October 17, 2026
• Repomix guide: installation · Official documentation · read October 17, 2026
• Repomix guide: command-line options · Official documentation · read October 17, 2026
• Repomix guide: security check · Official documentation · read October 17, 2026
• Repomix GitHub README · Source code · read October 17, 2026
• Repomix npm registry data: version, license, Node requirement · Vendor page · read October 17, 2026
• ccusage guide: Claude Code data source · Official documentation · read October 17, 2026
• ccusage guide: cost modes · Official documentation · read October 17, 2026
• ccusage npm registry data: version, license · Vendor page · read October 17, 2026
• Serena GitHub README (installation, license) · Source code · read October 17, 2026
• Serena docs: client configuration · Official documentation · read October 17, 2026
• Serena docs: project workflow and indexing · Official documentation · read October 17, 2026
• codebase-memory-mcp GitHub README · Source code · read October 17, 2026
• Spec Kit GitHub README · Source code · read October 17, 2026
• Git docs: git-diff · Official documentation · read October 17, 2026
• Git docs: git-rev-parse · Official documentation · read October 17, 2026
• Git docs: git-log · Official documentation · read October 17, 2026
• Git docs: git-status · Official documentation · read October 17, 2026
• npm docs: npx · Official documentation · read October 17, 2026
• ccusage guide: environment variables · Official documentation · read October 17, 2026
• ccusage guide: getting started · Official documentation · read October 17, 2026
• Serena PyPI entry (version, release date) · Vendor page · read October 17, 2026
• Claude Code docs: the .claude directory and automatic cleanup · Official documentation · read October 17, 2026