Context Monitor CLI

CLI reference for context monitoring configuration

from praisonaiagents import Agent

agent = Agent(name="monitor-agent", instructions="Monitor context usage in real time.")
agent.start("Display live context usage metrics for this session.")

Configure context monitoring via CLI flags and interactive commands.

The user launches praisonai chat --context-monitor and watches live context usage update after each turn.

How It Works

Quick Start

1. Enable monitoring at launch

   praisonai chat --context-monitor --context-monitor-format json
   
2. Control monitoring in session

   /context on
   /context dump
   

CLI Flags

Enable Monitoring

praisonai chat --context-monitor

Output Path

praisonai chat --context-monitor-path ./debug/context.json

Output Format

# Human-readable (default)
praisonai chat --context-monitor-format human

# JSON format
praisonai chat --context-monitor-format json

Update Frequency

# After each turn (default)
praisonai chat --context-monitor-frequency turn

# After each tool call
praisonai chat --context-monitor-frequency tool_call

# Manual only
praisonai chat --context-monitor-frequency manual

# On overflow detection
praisonai chat --context-monitor-frequency overflow

Write Mode

# Synchronous (default)
praisonai chat --context-write-mode sync

# Asynchronous (better performance)
praisonai chat --context-write-mode async

Redaction

# Enable redaction (default)
praisonai chat --context-redact

# Disable redaction (not recommended)
praisonai chat --no-context-redact

Interactive Commands

Enable Monitoring

> /context on

Output:

✓ Context monitoring enabled
Output: ./context.txt

Disable Monitoring

> /context off

Set Path

> /context path ./debug/context.json

Set Format

> /context format json

Set Frequency

> /context frequency overflow

Manual Snapshot

> /context dump

Output:

✓ Context snapshot written to: ./context.txt

Environment Variables

export PRAISONAI_CONTEXT_MONITOR=false
export PRAISONAI_CONTEXT_MONITOR_PATH=./context.txt
export PRAISONAI_CONTEXT_MONITOR_FORMAT=human
export PRAISONAI_CONTEXT_MONITOR_FREQUENCY=turn
export PRAISONAI_CONTEXT_REDACT=true

config.yaml

context:
  monitor:
    enabled: false
    path: ./context.txt
    format: human
    frequency: turn
    write_mode: sync
  redact_sensitive: true

Output Formats

Human Format

================================================================================
PRAISONAI CONTEXT SNAPSHOT
================================================================================
Timestamp: 2024-01-07T12:00:00Z
Session ID: abc123
Agent: Assistant
Model: gpt-4o-mini
Model Limit: 128,000 tokens
Output Reserve: 8,000 tokens
Usable Budget: 120,000 tokens

--------------------------------------------------------------------------------
TOKEN LEDGER
--------------------------------------------------------------------------------
Segment              Tokens     Budget     Used
system_prompt         1,200      2,000    60.0%
history              12,500     84,616    14.8%
...

JSON Format

{
  "timestamp": "2024-01-07T12:00:00Z",
  "session_id": "abc123",
  "agent_name": "Assistant",
  "model_name": "gpt-4o-mini",
  "budget": {
    "model_limit": 128000,
    "output_reserve": 8000,
    "usable": 120000
  },
  "ledger": {
    "segments": {
      "system_prompt": {"tokens": 1200, "budget": 2000}
    }
  }
}

Frequency Options

Frequency	When Snapshots Are Written
turn	After each user/assistant turn
tool_call	After each tool execution
manual	Only on /context dump
overflow	When approaching context limit

Troubleshooting

Snapshots not appearing

# Check if monitoring is enabled
> /context config

# Enable monitoring
> /context on

# Force a snapshot
> /context dump

Sensitive data in snapshots

# Ensure redaction is enabled
praisonai chat --context-redact

# Check redaction status
> /context config

Performance issues

# Use async writes
praisonai chat --context-write-mode async

# Reduce frequency
praisonai chat --context-monitor-frequency overflow

Best Practices

Use async writes in production chat

--context-write-mode async avoids blocking the UI while snapshots are written.

Reduce frequency when stable

Switch from per-turn to overflow-only snapshots once context behaviour is verified.

Keep redaction enabled

Never disable redaction when snapshots may contain API keys or user PII.

Point snapshots to a writable path

Ensure PRAISONAI_CONTEXT_MONITOR_PATH exists and is excluded from version control.

Related

Context Monitor

Python API and snapshot formats

Security & Redaction

Protect sensitive data in snapshots