AWS Builder Center

Managing context windows effectively in Amazon Q Developer CLI

Learn how to effectively manage context windows in Amazon Q Developer CLI to avoid overflow issues and maintain productive AI-assisted development workflows. This Level 300 post shows you how to use built-in features like automatic directory-based conversation persistence with q chat --resume, context monitoring with /usage, conversation compaction with /compact, and manual conversation management with /save and /load commands.

Introduction

"I quit and reopen, and it overflows immediately - is there a cache?" This question from a colleague highlighted a common challenge developers face when using Amazon Q Developer CLI. Context windows is the maximum amount of information an AI model can process in a single conversation which can quickly fill up during long debugging sessions or when switching between multiple tasks. When this happens, your conversations become less effective, and you lose valuable context just when you need it most.
In this post, I'll show you how to effectively manage context windows in  Amazon Q Developer  CLI using built-in features like automatic conversation persistence, context monitoring, and strategic session management. Whether you're debugging a complex issue or juggling multiple projects, these techniques will help you maintain productive AI-assisted workflows without losing important conversation context.

Understanding context windows in Amazon Q CLI

Every AI model has a context window limit. For Amazon Q Developer CLI, this includes your conversation history, code snippets, file contents, and any additional context you've provided. When your context approaches this limit, the CLI becomes less effective at understanding your requests, and older conversation history may be truncated.
Amazon Q CLI provides several built-in features to help you manage context effectively. The key is understanding how these features work together and developing organizational habits that align with your workflow.

Directory-based conversation persistence

One of Amazon Q CLI's most powerful features is automatic conversation persistence based on your current directory. When you start a chat session, Amazon Q automatically associates that conversation with your working directory. This means:
  • Each project naturally maintains its own conversation context
  • When you return to a project directory, you can resume right where you left off
  • Different projects don't pollute each other's conversation history

Resuming conversations automatically

To resume your previous conversation in the current directory, use the  --resume  flag:
cd ~/projects/my-backend-service
q chat --resume
If it's your first time chatting in that directory, Amazon Q starts a new conversation. If you've chatted there before, it loads your previous conversation history automatically.
This directory-based approach solves a common problem: when working on multiple projects, you no longer need to manually track which conversation goes with which project. The directory structure provides natural boundaries for your conversation context.

Monitoring context usage

Before your context window overflows, you need visibility into how much you're using. Amazon Q CLI provides the  /usage  command to display your current context consumption:
q chat --resume
> /usage

Current context window (30140 of 200k tokens used)
████████████████████████████████████████████████████████████████████████████████ 15.07%
█ Context files: ~1400 tokens (0.70%)
█ Q responses: ~17760 tokens (8.88%)
█ Your prompts: ~10990 tokens (5.49%)
This breakdown shows you:
  • Total tokens used out of available limit
  • Percentage of context window consumed
  • How tokens are distributed across context files, responses, and prompts
Check  /usage  regularly, especially during long troubleshooting sessions. When you see usage approaching 75%, it's time to take action.

Optimizing context with conversation compaction

When your context window starts filling up, Amazon Q CLI's  /compact  command provides an elegant solution. This command intelligently summarizes your conversation history while preserving essential information:
> /compact
✓ Creating a summary...
"Previous discussion covered JWT token validation issues, implemented refresh token logic, and resolved CORS configuration problems."
Compaction doesn't delete your conversation, it creates a concise summary that maintains continuity while freeing up context space for new interactions. Use this feature proactively when:
  •  /usage  shows 60-75% context consumption
  • You're transitioning to a related but distinct subtask
  • Your conversation has covered multiple topics and you want to continue in the same session
Amazon Q will also warn you when your conversation history approaches the limit, prompting you to use  /compact .

Saving and loading conversations

Sometimes you need more control than automatic directory-based persistence provides. Perhaps you solved a complex problem and want to preserve that exact conversation for future reference, or you're working on a temporary fix and want to save your main conversation before experimenting.
Amazon Q CLI provides  /save  and  /load  commands for manual conversation management:
# Save your current conversation with a descriptive name
> /save jwt-authentication-fix
✓ Conversation saved as 'jwt-authentication-fix'

# Later, load that specific conversation
> /load jwt-authentication-fix
✓ Loaded conversation 'jwt-authentication-fix'
Conversations are saved as JSON files, making them portable and easy to organize. You can create a dedicated directory structure for important conversations:
# Organize saved conversations by project
mkdir -p ~/.q-conversations/backend-service
mkdir -p ~/.q-conversations/frontend-app

# Save project-specific troubleshooting sessions
cd ~/projects/backend-service
q chat --resume
# ... work on authentication issue ...
> /save ~/.q-conversations/backend-service/auth-fix-2025-01-15

When to use /save vs directory-based persistence

Use directory-based persistence ( --resume ) for:
  • Ongoing project work where you want continuity
  • Natural context boundaries aligned with your project structure
Use  /save  and  /load  for:
  • Preserving breakthrough troubleshooting sessions
  • Creating reference conversations for specific problems
  • Experimenting with different approaches without losing your main conversation

Strategic directory organization

The directory-based persistence feature becomes even more powerful when combined with intentional directory organization. You don't need to save conversations in your actual project directories, you can create dedicated context directories.

For organized project work

If you work on well-defined projects, use Amazon Q CLI directly in your project directories:
# Navigate to your project
cd ~/projects/backend-service
q chat --resume

# Context automatically includes project-specific history
# All conversations about this codebase are immediately available

For ad-hoc work and experiments

If you frequently switch between unrelated tasks, create dedicated directories for different types of work:
# Create context directories for different work types
mkdir -p ~/q-contexts/debugging
mkdir -p ~/q-contexts/architecture-review
mkdir -p ~/q-contexts/experiments
mkdir -p ~/q-contexts/quick-questions

# Start focused conversations in each directory
cd ~/q-contexts/debugging
q chat --resume
# All debugging conversations stay isolated here

cd ~/q-contexts/quick-questions
q chat --resume
# Quick questions don't pollute your debugging context
This approach provides context isolation without requiring formal project structure. As one developer noted: "I have empty directories just for separating out my history on certain things." This simple technique is invaluable for maintaining clean conversation boundaries.

Walkthrough: Implementing a context management workflow

Let me demonstrate a complete workflow that addresses the original context overflow problem.

Prerequisites

  • An AWS account with Amazon Q Developer access
  • Basic command-line familiarity

Step 1: Set up your directory structure

Create dedicated directories based on your work style:
# For organized developers: use project directories
mkdir -p ~/projects/{backend,frontend,infrastructure}

# For ad-hoc developers: create context directories
mkdir -p ~/q-contexts/{debugging,research,experiments,current-work}

Step 2: Start with context monitoring

Begin each session by checking your context usage:
cd ~/projects/backend
q chat --resume

> /usage
Current context window (45000 of 200k tokens used)
████████████████████████████████████████████████████████████████████████████████ 22.5%
At 22.5%, you have plenty of room. Continue working normally.

Step 3: Use compaction proactively

As your conversation grows, monitor and compact when needed:
> /usage
Current context window (140000 of 200k tokens used)
████████████████████████████████████████████████████████████████████████████████ 70%

# Approaching 75% - time to compact
> /compact
✓ Creating a summary...
"Previous work: debugged authentication flow, updated JWT validation, added error handling for expired tokens."

> /usage
Current context window (65000 of 200k tokens used)
████████████████████████████████████████████████████████████████████████████████ 32.5%

Step 4: Save breakthrough moments

When you solve a complex problem, save that conversation:
> /save authentication-fix-20250115
✓ Conversation saved as 'authentication-fix-20250115'

Step 5: Switch contexts strategically

When moving to a completely different task, switch directories:
# Save current work if needed
> /save current-auth-work

# Switch to a different context
cd ~/q-contexts/research
q chat --resume

# Start fresh conversation for research
> What are the best practices for rate limiting in API gateways?

Best practices for context management

Proactive monitoring

  • Check  /usage  at the start of each session
  • Use  /usage  periodically during long troubleshooting sessions
  • Compact proactively at 60-75% usage rather than waiting for warnings

Strategic organization

  • Align directory structure with how you actually work
  • Use project directories for structured work
  • Create context directories for ad-hoc tasks
  • Don't overthink it—even empty directories work for separation

Effective saving

  • Use descriptive names for saved conversations:  api-performance-fix-20250115  not  conversation1 
  • Save breakthrough troubleshooting sessions for future reference
  • Create a consistent directory structure for saved conversations
  • Periodically review and clean up old saved conversations

Context optimization

  • Compact conversations before they fill up completely
  • Start fresh conversations for unrelated tasks by switching directories
  • Use  /save  before experimenting with different approaches
  • Return to saved conversations with  /load  when needed

Advanced techniques: Experimental features

Amazon Q CLI includes several experimental features for power users who need additional context management capabilities. These features require enabling through settings.
Note: The following features are experimental and subject to change in future releases. Commands, settings names, and behavior may be modified or removed. For production workflows, rely on the core features discussed earlier in this post.

Knowledge management for large codebases

For projects with extensive documentation or large codebases, enable the knowledge management system:
q settings chat.enableKnowledge true
Once enabled, you can add large reference materials that are searched on-demand rather than loaded into every conversation:
> /knowledge add docs/ --index-type best
> /knowledge add config/ --index-type fast

Tangent mode for side questions

When exploring side questions without polluting your main context, enable tangent mode:
q settings chat.enableTangentMode true
Use  /tangent  or Ctrl+T to create a temporary conversation branch for explorations that won't affect your main conversation.

Context usage indicator

Display context usage percentage directly in your prompt:
q settings chat.enableContextUsageIndicator true
This shows usage like  [my-agent] 15% >  in your prompt, providing constant visibility.
For more information on experimental features, see the  Amazon Q Developer CLI documentation .

Cleaning up

Periodically review and remove old conversation files to maintain optimal performance:
# Review saved conversations
ls ~/.q-conversations/

# Remove outdated sessions
rm ~/.q-conversations/backend-service/old-debug-session.json

# Amazon Q automatically manages directory-based conversations
# but you may want to start fresh occasionally by starting a new chat
# without --resume flag

Conclusion

In this post, I showed you how to effectively manage context windows in Amazon Q Developer CLI using directory-based conversation persistence, context monitoring with  /usage , conversation compaction with  /compact , and manual conversation management with  /save  and  /load . By developing organizational habits that align with your workflow—whether through project directories or dedicated context directories—you can maintain productive AI-assisted development without hitting context window limits.
Key takeaways:
  1. Use  q chat --resume  to automatically resume conversations based on your current directory
  1. Monitor context usage regularly with  /usage  to avoid overflow
  1. Compact conversations proactively with  /compact  when approaching 75% usage
  1. Save important troubleshooting sessions with  /save  for future reference
  1. Organize your workflow using directory structure, even empty directories work for context separation
The conversation that sparked this post ended with a realization: context management isn't just about technical commands, it's about developing organizational habits. As one developer noted, "It forces someone as disorganized as me to organize to get the most value." Whether you're naturally organized or prefer ad-hoc exploration, these techniques provide the flexibility to work effectively while maintaining valuable conversation context.
Next steps: Explore  custom agents  to pre-configure context for your most common workflows, and investigate  project rules  for automatically including relevant files in your conversations.
Have you developed your own context management strategies with Amazon Q CLI? I'd love to hear about your workflows, please share in the comments below!
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article