How to Manage Aider Token Limits: Repo-Map Budgets, Chat History, and MCP Retrieval

Every interactive coding session with Aider operates within two distinct token boundaries: the repository map budget, which defaults to 1,024 tokens to map codebase structure via tree-sitter, and the conversation history threshold, which begins automatic summarization once chat history exceeds 8,000 tokens.

Developers frequently encounter token exhaustion when pairing with AI coding assistants on non-trivial codebases. Many assume that Aider enforces an arbitrary internal file size cap or token ceiling. In reality, Aider never enforces artificial token limits on user prompts or code edits. Instead, it reports token limit errors directly from API providers when the underlying large language model exceeds its physical context window or completion output limit.

To balance comprehensive code awareness against strict model context boundaries, Aider divides token management into three core operational layers:

• Model Context Window and Output Limits: The physical capacity of the connected frontier model. For example, Anthropic Claude 3.5 Sonnet provides a 200,000 token input window with an 8,192 token maximum output limit, while OpenAI GPT-4o provides a 128,000 token input window with a 4,096 or 16,384 token output ceiling. Exceeding the total input window triggers an immediate API context error, while asking for changes that affect dozens of files simultaneously triggers output token truncation.
• Repository Map Budget (--map-tokens): Aider generates a concise map of your entire git repository using tree-sitter abstract syntax tree (AST) parsers. Rather than injecting full source files into context, it extracts class declarations, method names, and function signatures. The --map-tokens setting defines a suggested token allocation (defaulting to 1,024 tokens) to represent this structural map.
• Chat History Ceiling (--max-chat-history-tokens): As you discuss bugs, review diffs, and iterate on features, conversational turns accumulate. The --max-chat-history-tokens setting acts as a soft threshold (defaulting to 8,000 tokens for frontier models). Once conversation history crosses this boundary, Aider automatically summarizes earlier turns to reclaim input tokens for active work.

Understanding how these layers interact is the foundation of efficient terminal pair programming. When you add too many source files or let chat sessions run without maintenance, you consume the headroom needed for complex reasoning and diff generation.

Every time you submit a prompt, Aider constructs a structured payload and transmits it to the model API. Aider token usage reflects the total volume of input tokens sent across this payload, combined with the output tokens returned in the model response.

The anatomy of an Aider prompt payload consists of six distinct layers sent on every conversation turn:

1. System Prompt: Base instructions defining Aider's identity, formatting requirements, and edit formats (such as diff blocks or whole-file edits).
2. Repository Map: The tree-sitter AST symbol index sized according to --map-tokens.
3. Read-Only Context: External reference files added using /read-only, which provide background awareness without allowing edits.
4. Active Editable Files: Full file contents added using /add. Every line of every active file is transmitted on every turn so the LLM can generate accurate line diffs.
5. Chat History: Prior user messages, assistant responses, and tool outputs, bounded by --max-chat-history-tokens.
6. Active User Message: The specific prompt, bug description, or command submitted for the current turn.

Because active files and conversation history are resent on every turn, token consumption compounds rapidly. To inspect this overhead in real time, Aider provides built-in terminal inspection commands:

/tokens
/drop src/legacy_module.py
/clear
/undo

Running /tokens outputs a breakdown of your current session. It details the tokens consumed by active files, the repository map, and chat history, alongside the model's remaining context window. Running /drop removes unneeded files, while /clear purges conversational messages without losing your active file set.

Modern frontier models support prompt caching, which significantly alters the economics of Aider sessions. Providers like Anthropic and DeepSeek cache static prefixes across sequential API requests. In Aider, system instructions, repository maps, and stable file contents serve as cached prompt prefixes.

When prompt caching is active, reading cached tokens costs a fraction of standard input pricing and reduces response latency. However, frequently modifying files or adding large documents invalidates the cache prefix, forcing the model to re-ingest the entire context at full price. Maintaining disciplined token hygiene preserves prompt cache efficiency throughout long pairing sessions.

You can fine-tune Aider token limit settings to match your repository architecture and workflow complexity. Rather than relying on static defaults, adjusting --map-tokens and --max-chat-history-tokens allows you to customize context allocation for small scripts, medium services, or large monorepos.

The --map-tokens setting controls the density of the tree-sitter symbol graph. When Aider analyzes your repository, it constructs a graph connecting definitions and call sites, applying a PageRank-style algorithm to prioritize the symbols most relevant to your active chat context.

• Increase --map-tokens (e.g., 2,048 to 4,096 tokens): Recommended for large repositories with complex cross-module dependencies, microservices, or deep class hierarchies. A larger map provides the LLM with broader visibility into external signatures and helper utilities, reducing hallucinated method calls.
• Decrease --map-tokens (e.g., 512 tokens): Recommended for small projects, focused scripts, or when using models with smaller context windows where every token must be preserved for editing.
• Disable the map (--map-tokens 0): Turns off AST repo mapping entirely. Useful when working on standalone single-file utilities or when you prefer to manually curate every relevant file with /add.

Similarly, --max-chat-history-tokens governs how long Aider retains conversational detail before triggering automated summarization. Setting this value higher preserves intermediate reasoning and debugging attempts across multi-step refactoring tasks, while setting it lower keeps prompts lightweight and focused.

You can configure these options via command-line flags, environment variables, or a persistent project configuration file named .aider.conf.yml:

model: claude-3-5-sonnet-20241022
map-tokens: 2048
max-chat-history-tokens: 12000
map-refresh: auto
cache-prompts: true
stream: true

You can also export environment variables in your shell profile:

export AIDER_MAP_TOKENS=2048
export AIDER_MAX_CHAT_HISTORY_TOKENS=12000

The companion setting --map-refresh defines how frequently Aider recalculates the AST map. Setting --map-refresh auto refreshes the map when files change, while --map-refresh manual prevents background recalculations until you explicitly request an update, preserving stable prompt caching across rapid edit cycles.

Avoid Aider Token Limits by Offloading Documentation to Fast.io

Keep your Aider token limit and context window focused on source code. Offload API specifications, architecture guides, and reference documents into a Fast.io workspace, and let coding assistants search indexed files via the remote MCP server. Every organization starts with a 14-day free trial, which requires a credit card.

Start 14-Day Trial

While Aider's repository map excels at tracking code definitions, developers frequently need access to external context: API documentation, architectural decision records, database schemas, compliance guidelines, and third-party library manuals.

The standard reflex is to run /add on external markdown files, OpenAPI specifications, or related repository files. This approach breaks down quickly on non-trivial projects.

When you add multiple documentation files or reference schemas to an Aider session, two immediate bottlenecks emerge:

• Input Token Inflation: Adding 10 to 30 comprehensive reference files can easily load 40,000 to 100,000 tokens into the prompt payload. Because Aider resends all active files on every request, a five-turn conversation can consume half a million input tokens within minutes.
• Attention Dilution and Needle-in-a-Haystack Failures: Even when an LLM possesses a 200,000 token context window, stuffing that window with extraneous documentation degrades recall precision. Models suffer from attention dilution, often overlooking specific constraints or generating inaccurate code snippets because the prompt is saturated with irrelevant text.

Developers encounter a similar ceiling in web interfaces like Claude Projects, where project knowledge is limited by the context window (30MB per file, as documented in Anthropic's upload guide at https://support.claude.com/en/articles/8241126-upload-files-to-claude). Users frequently migrate to CLI agents like Aider seeking relief from context constraints, only to discover that attaching dozens of files locally creates prompt bloat and exceeds API rate limits.

Furthermore, Aider's AST parser only indexes code syntax in supported programming languages. It cannot parse or graph-rank PDF manuals, Word documents, unstructured internal notes, or raw JSON schemas. Storing these materials locally and forcing them into the prompt via /add wastes context headroom that should belong to the code under active development.

The solution to prompt bloat is architectural decoupling: keep only the files requiring active edits in Aider's local git session, and offload external documentation, reference codebases, and technical specifications to an intelligent cloud workspace.

Fast.io provides an intelligent workspace platform designed for agentic teams, offering dedicated storage for agents that connects directly to local developer workflows. Rather than storing large PDF manuals, architecture documents, and API schemas on your local disk and attaching them to Aider, you place them into an org-owned Fast.io workspace.

Getting documentation into the workspace requires no manual data preparation. You can upload files directly through the web interface or CLI, or use Cloud Sync to keep folders synchronized from Dropbox, Box, or OneDrive. Google Drive imports today, with sync coming soon. For public documentation or vendor specifications, URL import pulls files directly from web addresses without local disk overhead.

Once files arrive in a workspace with Intelligence Mode enabled, Fast.io automatically indexes them for hybrid search, combining exact full-text matching with semantic retrieval. You do not need to configure an external vector database, manage chunking strategies, or generate embedding indexes.

Coding assistants and terminal agents connect to this indexed knowledge using the Model Context Protocol (MCP). Fast.io provides a consolidated MCP toolset hosted remotely over Streamable HTTP at https://mcp.fast.io/mcp (or https://mcp.fast.io/mcp/key when authenticating via Bearer token).

{
  "mcpServers": {
    "fastio": {
      "type": "streamableHttp",
      "url": "https://mcp.fast.io/mcp/key",
      "headers": {
        "Authorization": "Bearer YOUR_FASTIO_API_KEY"
      }
    }
  }
}

When an agent needs to consult an API specification or verify an architectural standard, it queries the workspace via MCP rather than reading whole files into prompt memory. Fast.io performs semantic retrieval across the indexed corpus and returns only the relevant paragraphs, snippets, and source citations.

This retrieval pattern transforms token economics. Instead of carrying 50,000 tokens of static documentation on every turn, the agent retrieves a 400-token excerpt precisely when needed. Aider's local context window remains reserved for source code, prompt cache prefixes remain stable, and token limit errors disappear.

Collaborative workspaces also bridge the gap between autonomous agents and human teammates. Engineers can review file version history, track modifications through an append-only audit log, and co-edit documentation using Collaborative Notes.

Every organization starts with a 14-day free trial, which requires a credit card. Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo on Fast.io subscription pricing.