# Aider File Limits: Repo Map Scaling, File Addition Caps, and Context Management

The Aider file limit is not a rigid file count cap, but a boundary set by context windows and repository map budgets. While Aider imposes no programmatic cap on added files, above about 25k tokens of context, most models start to become distracted and fail to apply code edits cleanly. Balancing working sets through selective file additions, repo map tuning, and remote workspace indexing keeps pair programming fast and accurate.

Source: https://fast.io/resources/aider-file-limit/
Author: [Derek Labian](https://fast.io/authors/derek-labian/)
Last reviewed: 2026-10-21

## What Defines the Aider File Limit: Hard Caps Versus Token Ceilings

In Aider's official documentation on file editing problems, the project notes that above approximately 25,000 tokens of context, most large language models begin to lose track of system prompts and fail to apply code edits cleanly. This behavioral threshold marks the actual boundary developers face when pairing in the terminal.

Developers entering Aider often expect a fixed upload limit similar to cloud chat interfaces. The Aider file limit refers to the maximum number and size of files added to an active session using /add before token consumption degrades model reasoning and repo-map symbol compression occurs. Aider enforces no hard programmatic cap on the number of files you can add to a session, nor does it enforce an arbitrary per-file size ceiling. Instead, every file you add with `/add` is read from disk and injected directly into the prompt on every message cycle.

The practical ceiling of an Aider session is dictated by two distinct boundaries: the physical context window of the configured foundation model and the operational threshold where token bloat compromises code generation quality. While modern models like Claude 3.7 Sonnet, Claude 3.5 Sonnet, and GPT-4o accept between 128,000 and 200,000 tokens of input, packing that space with source code files introduces latency, inflates API bills, and degrades the model's ability to output precise unified diffs.

### How File and Context Limits Compare Across Coding Environments

Understanding how Aider manages working files requires comparing its local terminal architecture to graphical editors and vendor web interfaces. In web chat environments, vendors enforce rigid file count quotas to control ingestion pipelines and document parsing overhead. Aider operates directly against provider APIs, shifting file control entirely to the developer.

| Platform or Tool | Documented File Addition Cap | Per-File Size Limit | Working Context Ceiling | Source and Verification Date |
|---|---|---|---|---|
| Aider CLI | No hard file count limit | No hard file size limit (bounded by model context) | 128,000 to 200,000 tokens (upstream API window) | Aider Documentation (checked 2026-10-21) |
| Claude Chat | 20 files per conversation | 500 MB per file | Standard model context window | Anthropic Support (checked 2026-09-14) |
| Claude Projects | Unlimited file count | 30 MB per file | 200,000 tokens project context | Anthropic Support (checked 2026-09-14) |
| Cursor Composer | No hard file count limit | Truncated by token budget | 32,000 to 128,000 tokens depending on model | Cursor Documentation (checked 2026-10-21) |
| Continue CLI | No hard file count limit | Truncated by context window | Dependent on local or cloud model configuration | Continue Documentation (checked 2026-10-21) |

The comparison illustrates a critical structural difference. In Claude Projects, files reside in a project knowledge store and are drawn into context during processing. In Aider, every file added via `/add` is an active file, meaning its entire text travels over the wire with every single prompt you submit. Adding 20 source files in Aider does not establish a background index; it occupies permanent prompt space until explicitly dropped.

### The In-Memory Cost of File Additions

Because Aider does not throttle `/add` operations, developers frequently run `/add src/**/*.ts` or add entire module directories. This practice immediately breaks session economics.

When you issue `/add`, Aider reads each targeted file from your local git working tree, calculates its token footprint using the tokenizer matching your current model, and includes the file's path and full contents in the conversation payload. When addressing the question of an aider add file limit or aider max files, developers must realize that targeting thirty source files containing several hundred lines each can consume tens of thousands of tokens before submitting your first prompt. On a model with a 128,000-token window, you have consumed nearly half of your available context space before typing your first instruction.

Similarly, there is no hardcoded aider file size limit that blocks large files from loading, but large files immediately exhaust single-turn context limits. Every subsequent exchange re-transmits those tokens alongside your chat history, the repository map, and the model's generated diffs. If you make ten requests during a refactoring task, you pay input costs on those tokens ten separate times. Understanding the distinction between files the model needs to edit and files the model needs to know about is the foundation of effective Aider session management.

## How the Repository Map Allocates Tokens and Compresses Symbols

To solve the problem of whole-codebase awareness without exhausting context windows on every turn, Aider uses a repository map. The repository map provides a concise, structural view of your entire git repository, allowing the model to understand existing classes, functions, and method signatures without reading every implementation line.

The token budget is influenced by the --map-tokens switch, which defaults to 1k tokens. Aider allocates a default 1k-token budget for repository maps, scaling up to 4k+ tokens on larger models. Instead of sending raw code, Aider uses Tree-sitter to parse source files across dozens of programming languages into abstract syntax trees. From these trees, Aider extracts structural definitions, exported types, function signatures, and class hierarchies.

The repository map acts as a topological guide. When you ask the model to implement a new feature that depends on an authentication service located in another directory, the model reads the authentication method signature from the map and calls it accurately, even though `auth_service.py` was never added to the active chat.

### How Tree-Sitter and Graph Ranking Select Symbols

Aider does not populate the repository map by picking files at random or truncating code alphabetically. It builds a directed graph representing the identifiers and call relationships across your codebase.

Tree-sitter parses the source files into Concrete Syntax Trees, identifying definitions and references. Aider maps where identifiers are declared and where they are called, then applies a PageRank-style graph algorithm to rank the relative importance of every symbol in the project. Symbols that are central to the repository's architecture or frequently referenced receive higher weights.

Aider repo map dynamically adjusts to file counts and active working sets. When no files are added to the chat session, Aider applies a multiplier controlled by `--map-multiplier-no-files`, which defaults to 2. In an empty session, Aider expands the repository map budget to 2,048 tokens. This gives the model maximum global visibility while you ask architectural questions or determine which files require modification.

The moment you add a file using `/add`, Aider contracts the repository map budget back to the base 1,024-token limit. It then recalculates symbol priorities, heavily weighting definitions that relate directly to the files you just added. The map shifts focus from general repository structure to the immediate neighborhood of your active edits.

### Symbol Compression and Dropping in Large Codebases

In a repository containing 2,000 files and 300,000 lines of code, even a list of raw function signatures exceeds 1,024 tokens. When the total symbol volume surpasses the aider repo map limit set by `--map-tokens`, Aider applies progressive symbol compression.

Compression follows a strict priority order:

1. Method bodies and local variables are excluded entirely, preserving only top-level class names, function declarations, and type signatures.
2. Private methods and internal helper functions are pruned, retaining public interfaces and exported symbols.
3. Peripheral utility modules and deeply nested leaf files with low graph centrality are omitted from the map.
4. If space remains constrained, Aider compresses file listings into simple path references without expanding their inner symbols.

You can inspect what Aider includes in this topological view by running `/map` inside your session or launching Aider with `--show-repo-map`. If you work in a monorepo or large codebase where critical interfaces are being dropped from the map, you can raise the allocation:

```bash
aider --map-tokens 2048 --map-refresh auto
```

Allocating 2,048 or 4,096 tokens to the repository map gives models like Claude 3.7 Sonnet rich structural context across massive projects. However, setting `--map-tokens` too high consumes baseline prompt tokens on every turn. Setting `--map-tokens 0` disables the repository map entirely, which is useful when working in tiny scripts or when context conservation is paramount.

## How In-Chat File Additions Degrade Model Reasoning

A common workflow mistake among new Aider users is confusing `/add` with a bookmarking mechanism. In Aider, adding a file designates it as an active workspace target. The distinction between editable files and reference files determines both token spend and model behavior.

Adding ten to fifteen dense source files rapidly consumes half or more of the active context buffer. When context fills with raw source code, model reasoning degrades. The model's attention mechanism must distribute its focus across thousands of lines of peripheral implementation details rather than concentrating on the logic of your requested change.

This degradation produces specific, repeatable failures in terminal coding sessions:

- Format non-compliance: The model fails to produce correctly delimited unified diffs, resulting in `Failed to apply edit to <filename>` errors.
- Hallucinated diff anchors: The model misremembers surrounding code lines, proposing edits against code that does not exist in the local file.
- Lost constraints: The model ignores negative constraints in your prompt, such as instructions to preserve specific error handling or avoid modifying certain functions.
- Premature truncation: The model exhausts its output token limit trying to regenerate large files instead of producing concise diffs.

### The Difference Between /add and /read-only

Aider provides two distinct commands for introducing files into the chat: `/add` and `/read-only`. Understanding their mechanics prevents accidental token inflation and unwanted file modifications.

```text
/add <file1> <file2>      # Adds files as editable targets
/read-only <file3>        # Adds files as read-only reference context
/drop <file1>             # Removes a file from active context
```

Both commands read the targeted files from disk and inject their entire contents into the LLM prompt. Neither command compresses the text. If a data model file is 1,200 lines long, running `/read-only` consumes the exact same token footprint as running `/add`.

The difference lies entirely in the system instructions passed to the model:

- Files added via `/add` are marked as editable. The system prompt instructs the model that it is authorized to propose code modifications, refactor functions, and output diffs for these files.
- Files added via `/read-only` are marked as reference material. The model is told it must not propose modifications or generate diffs for these files.

Use `/read-only` when the model needs to inspect an interface, data class, or configuration file to write correct code in an editable file, but only when that interface is not already adequately represented in the repository map.

### Token Economics for Dense Source Trees

To understand why active files must be kept lean, consider the token breakdown of an active pair programming session. A typical enterprise TypeScript or Python source file contains between 300 and 600 lines, averaging 2,500 tokens once imports, type annotations, and docstrings are accounted for.

Here is how token consumption accumulates in an active Aider session:

```text
Base System Prompt:              ~1,500 tokens
Repository Map (--map-tokens):   ~1,024 tokens
Active Chat History (3 turns):   ~4,500 tokens
---------------------------------------------
Baseline Overhead:               ~7,024 tokens

Adding 4 source files:          +10,000 tokens  -> Total:  17,024 tokens (Safe zone)
Adding 10 source files:         +25,000 tokens  -> Total:  32,024 tokens (Distraction risk)
Adding 18 source files:         +45,000 tokens  -> Total:  52,024 tokens (Severe degradation)
```

Once the prompt crosses 30,000 tokens, you have entered the zone where edit application failures multiply. At 50,000 tokens of active context, each prompt submission becomes noticeably slower, costs more, and increases the likelihood that Aider will report failed diff merges.

To maintain context hygiene:
- Use `/tokens` frequently to inspect your current token consumption across chat history, active files, and repository map overhead.
- Use `/drop <filename>` the instant an edit on that file is completed and verified.
- Use `/clear` between distinct development tasks to wipe conversational history while retaining your active editable files.
- Use `/reset` when pivoting to an entirely new feature to drop all files and clear history simultaneously.

## Managing Large Non-Code Assets, Bulky Documentation, and External Schemas

Source code is not the only material developers need when building software. Projects routinely require API documentation, massive OpenAPI specifications, database migration dumps, JSON fixtures, and architecture design records. Attempting to manage these non-code assets within Aider reveals a severe architectural bottleneck.

Tree-sitter is engineered specifically for programming languages with well-defined grammars, such as TypeScript, Python, Rust, and Go. It cannot parse an extensive JSON schema, a raw CSV file, or a PDF manual into structural syntax trees. When a non-code file is added to Aider, the repository map cannot extract signatures or compress its contents.

If you run `/add schema.json` or `/add api_reference.md`, Aider has only one option: it reads the entire raw text into the active prompt. Adding a single comprehensive API specification can inject tens of thousands of tokens of static text into every prompt cycle. This immediately blows past the model's distraction threshold and crowds out the source code you actually intend to edit.

### Excluding Non-Code Noise with .aiderignore

The first step in protecting your Aider session from non-code bloat is establishing a comprehensive `.aiderignore` file in your repository root. Similar to `.gitignore`, `.aiderignore` instructs Aider to skip matching files when scanning directories, building repository maps, and executing git operations.

Create an `.aiderignore` file to block data files, build outputs, and bulky documentation from entering Aider's purview:

```text
# data files and database fixtures
*.csv
*.tsv
*.parquet
*.sqlite3
*.dump

# large schemas and generated specs
schema.json
swagger.json
openapi.yaml

# build artifacts and package caches
dist/
build/
coverage/
node_modules/
.next/

# documentation trees
docs/
architecture/*.pdf
```

You can pass a custom ignore file using `aider --aiderignore .custom-ignore` or set the `AIDER_AIDERIGNORE` environment variable. When working in a large monorepo, use the `--subtree-only` flag to restrict Aider's repository mapping and file discovery to your immediate working subproject.

### Decoupling Documentation into Cloud Workspaces

External workspace indexing decouples large documentation and reference assets from git-tracked files. Instead of bloating your git repository with static manuals or forcing coding agents to swallow massive markdown folders, engineering teams move reference material into dedicated cloud workspaces.

In [intelligent workspaces](/product/workspaces/) on Fast.io, non-code assets are stored centrally and indexed for retrieval. Rather than attaching entire reference books to a local CLI session, agents connect to the workspace using the Model Context Protocol. You can explore how [persistent storage for AI agents](/storage-for-agents/) changes context economics.

The workflow operates through clear functional steps:

1. Reference assets, including architectural RFCs, third-party SDK documentation, API specs, and database schemas, are uploaded to an organization-owned workspace or synced from cloud storage. Cloud Sync connects Google Drive, Dropbox, Box, and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand.
2. Intelligence Mode is enabled on the workspace, which automatically indexes the files for hybrid search across full text, semantic meaning, and structured metadata. Learn more about [Fast.io AI features](/product/ai/) that power this search layer.
3. The coding assistant connects to Fast.io over Streamable HTTP using the remote MCP endpoint at `https://mcp.fast.io/mcp/code`. Setup instructions for developers and agents are available in the [Fast.io MCP documentation](https://mcp.fast.io/docs) and the [Fast.io MCP tooling reference](https://mcp.fast.io/skill.md).
4. When the coding assistant needs specific details about an API contract or schema definition, it performs a targeted search query through the MCP server. It retrieves only the relevant three-paragraph endpoint specification or interface definition, consuming 300 tokens instead of 80,000.

This architecture preserves Aider's local speed and git integration while granting the model access to an arbitrarily large corpus of team knowledge. Fast.io workspaces include per-file version history, a detailed activity log of changes, and role-based permissions set per organization, workspace, and share. Monthly plans start with a 14-day free trial that requires a credit card. Review complete tier options on the [Fast.io pricing](/pricing/) page:

| Plan | Monthly Price | Included Storage | Included Seats | Monthly AI Credits |
|---|---|---|---|---|
| Starter | $9.99/mo | 250 GB | 3 seats | 100,000 credits |
| Business | $49.99/mo | 5 TB | 10 seats | 600,000 credits |
| Enterprise | $199.99/mo | 25 TB | 30 seats | 3,000,000 credits |

## Practical Rules of Thumb for Sizing Aider Working Sets in Production Codebases

Managing file limits in Aider is ultimately an exercise in operational discipline. By treating context as an expensive, volatile resource, you can maintain high code edit accuracy across complex commercial codebases.

Applying practical rules of thumb keeps your Aider sessions operating inside the model's peak reasoning zone while preventing unexpected token exhaustion:

- The 2-to-5 file rule: Limit your active `/add` working set to between two and five files simultaneously. If a feature touches twelve files, break the implementation into sequential commits, modifying three files at a time.
- Verify before dropping: Complete the edit on a module, run your tests using `/test`, commit the changes via `/commit`, and immediately run `/drop <filename>`.
- Trust the repository map: Avoid adding files simply to remind the model of an existing method name. The Tree-sitter map already exposes class definitions and call signatures. Add a file only when the model must rewrite its logic or read private implementation details.
- Clear conversational residue: Chat history retains old code snippets and rejected diffs. After five to seven turns on a single task, run `/clear` to purge conversational residue while keeping your active files loaded.

### Configuring Architect Mode for Complex Refactoring

When a task legitimately spans multiple files and requires extensive architectural coordination, single-model editing often stumbles. Aider's Architect Mode resolves this by splitting reasoning from code generation.

In Architect Mode, Aider pairs two distinct models:
1. A reasoning model (such as Claude 3.7 Sonnet or OpenAI o3-mini) that evaluates your prompt, inspects the repository map, reasons through multi-file dependencies, and designs a comprehensive implementation plan.
2. An editor model (such as Claude 3.5 Sonnet or DeepSeek V3) that receives the plan and the specific target files, generating clean unified diffs.

You can configure Architect Mode and persistent file limits in your project's `.aider.conf.yml` file:

```yaml
# model pair configuration
architect: true
model: claude-3-7-sonnet-20250219
editor-model: claude-3-5-sonnet-20241022

# repository map and context tuning
map-tokens: 2048
map-multiplier-no-files: 2
map-refresh: auto

# file management
aiderignore: .aiderignore
subtree-only: false
```

This configuration provides 2,048 tokens of repository map context for the reasoning model while keeping the editor model focused exclusively on the files being changed. By combining architect mode with selective file management and external documentation indexing, you eliminate context degradation and transform Aider into a dependable tool for complex software engineering.

## Frequently asked questions

### How many files can you add to an Aider session?

Aider enforces no hard programmatic limit on the number of files you can add to a session. You can add dozens of files using /add, but Aider includes the full content of every added file in each prompt. To prevent model distraction and failed code edits, the recommended rule of thumb is to keep active files between two and five.

### What is the maximum file size Aider can edit?

Aider does not impose an internal file size cap. The practical limit is bounded by the context window of your underlying language model. For instance, a model with a two-hundred-thousand token window can load extensive code, but files exceeding several thousand lines increase latency, inflate costs, and degrade edit accuracy.

### How does Aider manage repository maps when too many files are added?

The token budget is influenced by the --map-tokens switch, which defaults to 1k tokens. When codebases grow large, Aider uses Tree-sitter and a PageRank algorithm to rank symbols, compressing the map by dropping method bodies, private helpers, and peripheral files to remain within budget.

### What is the difference between /add and /read-only in Aider?

Both commands load the full text of a file into the prompt, consuming identical token counts. Files added with /add are marked as editable targets that Aider can propose diffs for, while files added with /read-only are marked as read-only reference material that the model cannot edit.

### How do non-code files like PDFs and large JSON schemas affect Aider?

Non-code files cannot be parsed into syntax trees by Tree-sitter. When added to Aider, they are injected as raw text, rapidly consuming tens of thousands of context tokens. Large specifications and documentation should be excluded via .aiderignore and indexed in external workspaces.

### What is the recommended repo map token budget for large codebases?

For small to medium projects, the default 1024-token budget is optimal. For large monorepos running on high-capacity models like Claude 3.7 Sonnet, setting --map-tokens to 2048 or 4096 provides broader symbol visibility without overwhelming the prompt.

## Sources

- [Aider Documentation: File Editing Problems](https://aider.chat/docs/troubleshooting/edit-errors.html): Above about 25k tokens of context, most models start to become distracted and become less likely to conform to their system prompt.
- [Aider Documentation: Repository Map](https://aider.chat/docs/repomap.html): The token budget is influenced by the --map-tokens switch, which defaults to 1k tokens.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.