diff --git a/README.md b/README.md index 92be3c0a..cc7e6225 100644 --- a/README.md +++ b/README.md @@ -1085,6 +1085,34 @@ Use ```/agent``` to list all the agents available. ![cai-008-config](imgs/readme_imgs/cai-008-config.png) +
+ How can I monitor context usage and token consumption? /context or /ctx + +Use ```/context``` (or the short form ```/ctx```) to view your current context window usage and token statistics. + +This command displays: +- Total context usage (used tokens / max tokens) with percentage +- Visual grid representation with the CAI logo showing filled context +- Detailed breakdown by category: + - System prompt tokens + - Tool definitions tokens + - Memory/RAG tokens + - User prompts tokens + - Assistant responses tokens + - Tool calls tokens + - Tool results tokens +- Free space available + +**Why this matters**: Different models have different context limits (e.g., GPT-4: 128k tokens, Claude: 200k tokens). Monitoring your context usage helps you avoid hitting these limits during long conversations, which could cause errors or require conversation truncation. + +```bash +# Show context usage +/context + +# Or use the short form +/ctx +``` +
How to know more about the CLI? /help diff --git a/docs/cai/getting-started/commands.md b/docs/cai/getting-started/commands.md index b84afd74..10e99e35 100644 --- a/docs/cai/getting-started/commands.md +++ b/docs/cai/getting-started/commands.md @@ -27,6 +27,39 @@ This document provides documentation for all commands available in the CAI (Cont - Configure CTF (Capture The Flag) variables - Manage configuration through environment variables +### **Context Usage Monitoring (`context.py`)** +### **ContextCommand** +- **Command**: `/context` or `/ctx` +- **Purpose**: View context usage and token statistics for the current conversation +- **Features**: + - Display total context usage (used/max tokens) with percentage + - Visual grid representation of context usage with CAI logo + - Detailed breakdown by category: + - System prompt tokens + - Tool definitions tokens + - Memory/RAG tokens + - User prompts tokens + - Assistant responses tokens + - Tool calls tokens + - Tool results tokens + - Free space visualization + - Context usage tracking across conversation history + - Real-time token consumption monitoring +- **Usage Example**: + ```bash + # Show context usage for current agent + /context + + # Alternative short form + /ctx + ``` +- **Output Includes**: + - Visual grid showing filled vs free context space + - Percentage breakdown per category + - Token counts formatted with 'k' suffix for thousands + - Color-coded categories for easy identification + - Summary of total input tokens from last iteration + ### **Cost Tracking (`cost.py`)** ### **CostCommand** - **Command**: `/cost` diff --git a/docs/tui/commands_reference.md b/docs/tui/commands_reference.md index 51018cdf..b783772d 100644 --- a/docs/tui/commands_reference.md +++ b/docs/tui/commands_reference.md @@ -377,6 +377,48 @@ Load a previously saved conversation. ## Utility Commands +### `/context [agent_name]` or `/ctx` + +Display context window usage and token statistics for the current conversation. + +**Syntax**: +``` +/context [agent_name] +/ctx [agent_name] +``` + +**Examples**: +```bash +# Show context usage for active terminal +/context + +# Show context usage for specific agent +/context redteam_agent + +# Compact syntax +/ctx +``` + +**Output Includes**: +- Total context usage (used/max tokens) with percentage +- Visual grid representation with CAI logo +- Breakdown by category: + - System prompt tokens + - Tool definitions tokens + - Memory files (RAG) tokens + - User prompts tokens + - Assistant responses tokens + - Tool calls tokens + - Tool results tokens +- Free space available +- Color-coded visualization for easy identification + +**Notes**: +- Context usage helps monitor when you're approaching model limits +- Different models have different context windows (e.g., GPT-4: 128k, Claude: 200k) +- Use `/context` regularly during long conversations to avoid hitting limits +- Context usage is terminal-specific in TUI mode + ### `/cost [agent_name]` Display API usage costs and token statistics.