Add documentation for /ctx

Signed-off-by: Víctor Mayoral Vilches <v.mayoralv@gmail.com>

README.md

@@ -1085,6 +1085,34 @@ Use ```/agent``` to list all the agents available.
 ![cai-008-config](imgs/readme_imgs/cai-008-config.png)
 </details>
 
+<details>
+<summary> How can I monitor context usage and token consumption? /context or /ctx </summary>
+
+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
+```
+</details>
 
 <details>
 <summary> How to know more about the CLI? /help </summary>

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`

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.