Chat Loop Configuration Guide

The Basic Agent Chat Loop supports comprehensive configuration via .chatrc files.

Quick Start

Copy the example config:

cp AWS_Strands/.chatrc.example ~/.chatrc

Edit for your preferences:

nano ~/.chatrc  # or your preferred editor

Run chat loop - config loads automatically:

python AWS_Strands/chat_loop.py --agent AWS_Strands/Product_Pete/agent.py

Configuration Locations

Configs are loaded in this order (later overrides earlier):

Built-in defaults - Always available as fallback
Global config - ~/.chatrc - Applies to all agents
Project config - .chatrc in current dir or up to 3 parents - Project-specific
Explicit config - --config /path/to/config - Highest priority

Configuration Sections

Colors

Customize ANSI escape codes for terminal output:

colors:
  user: '\033[97m'      # Bright white (default)
  agent: '\033[94m'     # Bright blue
  system: '\033[33m'    # Yellow
  error: '\033[91m'     # Bright red
  success: '\033[92m'   # Bright green
  dim: '\033[2m'        # Dim
  reset: '\033[0m'      # Reset

Alternative color schemes:

Monochrome (for colorblind users):

colors:
  user: '\033[1m'     # Bold
  agent: '\033[0m'    # Normal
  system: '\033[2m'   # Dim

High contrast:

colors:
  user: '\033[97;1m'  # Bright white bold
  agent: '\033[96;1m' # Bright cyan bold

Features

Toggle functionality on/off:

features:
  auto_save: true               # Save conversations on exit (default: true)
  rich_enabled: true            # Use rich library for formatting
  show_tokens: true             # Display token counts (default: true)
  show_metadata: true           # Show agent metadata on startup
  readline_enabled: true        # Command history

Paths

File system locations:

paths:
  log_location: .logs                      # Log files

Note: Conversation sessions are now saved to ./.chat-sessions/ in the current working directory (project-local, not configurable). This provides context separation - sessions from different projects are kept separate.

Behavior

Runtime behavior:

behavior:
  max_retries: 3               # Maximum retry attempts on failure
  retry_delay: 2.0             # Seconds between retries
  timeout: 120.0               # Request timeout (seconds)
  spinner_style: dots          # Thinking indicator style

Available spinner styles:

dots, line, arc, arrow, arrow2, arrow3, balloonBox, betaWave, bouncingBall, bouncingBar, boxBounce, boxBounce2, christmas, circle, circleHalves, circleQuarters, clock, dots2-12, earth, grenade, growHorizontal, growVertical, hamburger, hearts, layer, line, line2, monkey, moon, noise, orangeBluePulse, orangePulse, pipe, point, pong, runner, sand, simpleDots, simpleDotsScrolling, smiley, soccerHeader, speaker, squareCorners, squish, star, star2, toggle, toggle2-13, triangle, weather

UI

User interface preferences:

ui:
  show_banner: true            # Welcome banner
  show_thinking_indicator: true  # "Thinking..." spinner
  show_duration: true          # Query duration
  show_status_bar: true        # Top status bar (agent, model, queries, time)

Status Bar: Enabled by default, shows a persistent status bar at the top:

┌─────────────────────────────────────────────────┐
│ Clara │ Sonnet 4.5 │ 3 queries │ 12m 34s        │
└─────────────────────────────────────────────────┘

Updates after each query
Shows session time and query count
Clean box drawing characters

Audio

Audio notification settings:

audio:
  enabled: true                # Play sound when agent completes
  notification_sound: null     # Custom WAV file (null = bundled sound)

Platform support:

macOS: Uses afplay (built-in)
Linux: Uses aplay or falls back to paplay
Windows: Uses winsound module

Custom notification sounds:

audio:
  enabled: true
  notification_sound: /path/to/custom.wav

The notification sound must be a WAV file. The bundled sound (when notification_sound: null) is a pleasant, non-intrusive notification tone.

Disable audio:

audio:
  enabled: false

Harmony

OpenAI Harmony format support for gpt-oss models:

harmony:
  enabled: auto                 # Harmony processing (auto/yes/no)
  show_detailed_thinking: true  # Show reasoning with labeled prefixes

harmony.enabled options:

auto (default) - Automatically detect harmony agents by checking for:
- Explicit uses_harmony attribute on the agent
- Model names containing "gpt-oss" or "harmony"
- Harmony-specific methods or attributes
- Agent class names containing "harmony"
yes - Force enable harmony processing for all agents
no - Disable harmony processing completely

Detailed thinking mode: When show_detailed_thinking: true (default), the agent's internal reasoning is displayed with labeled prefixes:

💭 [REASONING]
I need to analyze this query...

📊 [ANALYSIS]
Looking at the structure...

📝 [COMMENTARY]
This is a common pattern...

💬 [RESPONSE]
Here are the optimizations...

When show_detailed_thinking: false, only the final response is shown:

Here are the optimizations...

Per-agent harmony settings:

agents:
  'My Harmony Agent':
    harmony:
      enabled: yes              # Force enable for this agent
      show_detailed_thinking: false  # Hide internal reasoning

Context

Context usage monitoring and warning thresholds:

context:
  warning_thresholds: [80, 90, 95]  # Warning percentages

Warning thresholds:

List of percentages (0-100) at which to show context usage warnings
Thresholds are checked from highest to lowest
Highest threshold shows error message with suggestion to use #compact
Second-highest shows warning message
Lower thresholds show informational messages
Default: [80, 90, 95] (warn at 80%, 90%, and 95%)

Examples:

More aggressive warnings:

context:
  warning_thresholds: [50, 75, 90, 95]  # Warn earlier

Minimal warnings:

context:
  warning_thresholds: [95]  # Only warn when critical

Custom per-agent:

agents:
  'Memory Heavy Agent':
    context:
      warning_thresholds: [60, 80, 90, 95]  # Warn earlier for this agent

View context usage: Use the #context command to see current token usage, session time, and warnings.

Sessions

Conversation session management settings:

sessions:
  resume_confirmation: true    # Ask before resuming sessions
  max_sessions: 50             # Max sessions to keep (auto-cleanup)
  auto_cleanup_days: 30        # Delete sessions older than N days (0 = never)
  resume_strategy: auto        # Strategy: auto|replay

Resume confirmation:

true: Always ask before replaying queries to restore context
false: Auto-resume without confirmation

Auto-cleanup:

max_sessions: Limits total number of stored sessions
auto_cleanup_days: Deletes sessions older than specified days
Set auto_cleanup_days: 0 to keep sessions forever

Resume strategies:

auto: Try context injection, fallback to replay (future)
replay: Always replay all queries (current implementation)

Saved session structure:

./.chat-sessions/              # Project-local (in current directory)
├── myagent_20250126_143022.json    # Machine-readable
├── myagent_20250126_143022.md      # Human-readable
└── .index.json                      # Fast lookup index

Enable auto-save to use sessions:

features:
  auto_save: true              # Required for session persistence

Sessions are saved to ./.chat-sessions/ in your current working directory, providing context separation between different projects.

Usage:

# List all saved sessions
You: sessions

# Resume a session by number
You: resume 1

# Resume on startup
chat_loop myagent --resume
chat_loop myagent --resume 1

# List sessions from CLI
chat_loop --list-sessions

Per-Agent Configuration

Override settings for specific agents:

agents:
  'Complex Coding Clara':
    features:
      auto_save: true
      show_tokens: true
    behavior:
      timeout: 300.0
    ui:
      show_metadata: false
    audio:
      enabled: false          # Silent agent - no audio

  'Product Pete':
    colors:
      agent: '\033[95m'       # Magenta
    features:
      auto_save: true
    audio:
      notification_sound: ~/sounds/product-complete.wav

Agent names must match exactly (as shown in banner).

Usage Examples

Global Configuration

Apply to all agents:

cp AWS_Strands/.chatrc.example ~/.chatrc
nano ~/.chatrc

Project Configuration

For a specific project:

cd ~/my-project
cp ~/path/to/.chatrc.example .chatrc
nano .chatrc

Explicit Configuration

Use a specific config file:

python AWS_Strands/chat_loop.py --agent <agent> --config /path/to/custom.chatrc

Workflow-Specific Configs

Different configs for different workflows:

# Coding workflow
python AWS_Strands/chat_loop.py --agent Clara --config ~/.chatrc-coding

# Research workflow
python AWS_Strands/chat_loop.py --agent Dave --config ~/.chatrc-research

Configuration Tips

1. Start with Example

Copy .chatrc.example and modify incrementally:

cp AWS_Strands/.chatrc.example ~/.chatrc

2. Test Changes

Run with info command to verify settings:

python AWS_Strands/chat_loop.py --agent <agent>
> info

3. Per-Agent Overrides

Use agent-specific configs for specialized workflows:

Clara: Auto-save, longer timeout, hide metadata
Pete: Custom colors for product work
Dave: Very long timeout for deep research

4. Color Accessibility

For colorblind users, use monochrome or high-contrast schemes.

5. Performance Tuning

Adjust for your use case:

Research: Higher timeout, disable thinking indicator
Quick queries: Lower retries, faster retry_delay
Production: Enable auto_save, logging

6. Team Consistency

Commit .chatrc to project root for team consistency:

cp AWS_Strands/.chatrc.example .chatrc
# Edit for project
git add .chatrc
git commit -m "Add chat loop config"

Configuration Priority

When the same setting exists in multiple configs:

Explicit --config (highest)
Per-agent override in project .chatrc
Project .chatrc (current dir or parents)
Per-agent override in global ~/.chatrc
Global ~/.chatrc
Built-in defaults (lowest)

Example:

# ~/.chatrc (global)
behavior:
  max_retries: 3

# .chatrc (project)
behavior:
  max_retries: 5
agents:
  'Complex Coding Clara':
    behavior:
      max_retries: 10

# Result for Clara: max_retries = 10 (agent override wins)
# Result for Pete: max_retries = 5 (project config wins)

Troubleshooting

Config not loading?

Check YAML syntax:

python3 -c "import yaml; yaml.safe_load(open('.chatrc'))"

Verify file location:
```
ls -la ~/.chatrc
ls -la .chatrc
```

Check for YAML library:

python3 -c "import yaml; print('✓ YAML available')"

Colors not working?

Ensure ANSI codes are quoted:

colors:
  user: '\033[97m'  # Correct - quoted
  # user: \033[97m  # Wrong - unquoted

Agent-specific config not applying?

Check agent name matches exactly:

# Run chat loop and check banner for exact name
python AWS_Strands/chat_loop.py --agent <agent>
# Look for: "COMPLEX CODING CLARA - Interactive Chat"
# Config should use: 'Complex Coding Clara'

Advanced Usage

Dynamic Config Loading

Config can be reloaded per agent in scripts:

from AWS_Strands.chat_config import get_config, ChatConfig

# Load specific config
config = ChatConfig(config_path=Path('custom.chatrc'))

# Get values with agent overrides
timeout = config.get('behavior.timeout', 120.0, agent_name='Clara')

# Runtime changes (not persisted)
config.set('features.auto_save', True, agent_name='Pete')

Config in Scripts

Integrate config in custom scripts:

from AWS_Strands.chat_loop import ChatLoop
from AWS_Strands.chat_config import get_config

config = get_config()
chat = ChatLoop(agent, name, desc, config=config)
chat.run()

Schema Reference

Full configuration schema:

colors:
  user: string        # ANSI escape code
  agent: string
  system: string
  error: string
  success: string
  dim: string
  reset: string

features:
  auto_save: boolean
  rich_enabled: boolean
  show_tokens: boolean
  show_metadata: boolean
  readline_enabled: boolean

paths:
  log_location: string  # Path with ~ and $VAR expansion

behavior:
  max_retries: integer   # 0-10 recommended
  retry_delay: float     # Seconds
  timeout: float         # Seconds
  spinner_style: string  # See spinner styles above

ui:
  show_banner: boolean
  show_thinking_indicator: boolean
  show_duration: boolean
  show_status_bar: boolean  # Top status bar with agent, model, queries, time

audio:
  enabled: boolean          # Play sound when agent completes
  notification_sound: string | null  # Path to WAV file or null for bundled sound

harmony:
  enabled: string           # auto / yes / no - Harmony processing control
  show_detailed_thinking: boolean  # Show reasoning with labeled prefixes

context:
  warning_thresholds: list[int]  # List of percentages (0-100) for warnings

agents:
  '<agent_name>':
    # Any of the above sections can be overridden
    colors: {...}
    features: {...}
    paths: {...}
    behavior: {...}
    ui: {...}
    audio: {...}
    harmony: {...}
    context: {...}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Chat Loop Configuration Guide

Quick Start

Configuration Locations

Configuration Sections

Colors

Features

Paths

Behavior

UI

Audio

Harmony

Context

Sessions

Per-Agent Configuration

Usage Examples

Global Configuration

Project Configuration

Explicit Configuration

Workflow-Specific Configs

Configuration Tips

1. Start with Example

2. Test Changes

3. Per-Agent Overrides

4. Color Accessibility

5. Performance Tuning

6. Team Consistency

Configuration Priority

Troubleshooting

Config not loading?

Colors not working?

Agent-specific config not applying?

Advanced Usage

Dynamic Config Loading

Config in Scripts

Schema Reference

See Also

FilesExpand file tree

CONFIG.md

Latest commit

History

CONFIG.md

File metadata and controls

Chat Loop Configuration Guide

Quick Start

Configuration Locations

Configuration Sections

Colors

Features

Paths

Behavior

UI

Audio

Harmony

Context

Sessions

Per-Agent Configuration

Usage Examples

Global Configuration

Project Configuration

Explicit Configuration

Workflow-Specific Configs

Configuration Tips

1. Start with Example

2. Test Changes

3. Per-Agent Overrides

4. Color Accessibility

5. Performance Tuning

6. Team Consistency

Configuration Priority

Troubleshooting

Config not loading?

Colors not working?

Agent-specific config not applying?

Advanced Usage

Dynamic Config Loading

Config in Scripts

Schema Reference

See Also