> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Monitor CLI

> CLI reference for context monitoring configuration

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Context Monitor CLI"
        Request[📋 User Request] --> Process[⚙️ Context Monitor CLI]
        Process --> Result[✅ Result]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Request input
    class Process process
    class Result output
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Context Monitor CLI

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Context Monitor CLI"
        In[📝 chat --context-monitor] --> Mon[👁️ Monitor]
        Mon --> Agent[🤖 Agent]
        Agent --> Out[✅ Live Snapshot]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class In input
    class Mon process
    class Agent agent
    class Out output
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI
    participant Monitor
    participant Agent

    User->>CLI: praisonai chat --context-monitor
    CLI->>Monitor: Enable snapshots
    Agent->>Monitor: Emit usage each turn
    Monitor-->>User: Live context stats
```

## Quick Start

<Steps>
  <Step title="Enable monitoring at launch">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai chat --context-monitor --context-monitor-format json
    ```
  </Step>

  <Step title="Control monitoring in session">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    /context on
    /context dump
    ```
  </Step>
</Steps>

## CLI Flags

### Enable Monitoring

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai chat --context-monitor
```

### Output Path

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai chat --context-monitor-path ./debug/context.json
```

### Output Format

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Human-readable (default)
praisonai chat --context-monitor-format human

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

### Update Frequency

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Synchronous (default)
praisonai chat --context-write-mode sync

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

### Redaction

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable redaction (default)
praisonai chat --context-redact

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

## Interactive Commands

### Enable Monitoring

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> /context on
```

**Output:**

```
✓ Context monitoring enabled
Output: ./context.txt
```

### Disable Monitoring

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> /context off
```

### Set Path

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> /context path ./debug/context.json
```

### Set Format

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> /context format json
```

### Set Frequency

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> /context frequency overflow
```

### Manual Snapshot

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> /context dump
```

**Output:**

```
✓ Context snapshot written to: ./context.txt
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check if monitoring is enabled
> /context config

# Enable monitoring
> /context on

# Force a snapshot
> /context dump
```

### Sensitive data in snapshots

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Ensure redaction is enabled
praisonai chat --context-redact

# Check redaction status
> /context config
```

### Performance issues

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Use async writes
praisonai chat --context-write-mode async

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

## Best Practices

<AccordionGroup>
  <Accordion title="Use async writes in production chat">
    `--context-write-mode async` avoids blocking the UI while snapshots are written.
  </Accordion>

  <Accordion title="Reduce frequency when stable">
    Switch from per-turn to overflow-only snapshots once context behaviour is verified.
  </Accordion>

  <Accordion title="Keep redaction enabled">
    Never disable redaction when snapshots may contain API keys or user PII.
  </Accordion>

  <Accordion title="Point snapshots to a writable path">
    Ensure `PRAISONAI_CONTEXT_MONITOR_PATH` exists and is excluded from version control.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Context Monitor" icon="eye" href="/docs/features/context-monitor">
    Python API and snapshot formats
  </Card>

  <Card title="Security & Redaction" icon="shield-halved" href="/docs/features/context-security-redaction">
    Protect sensitive data in snapshots
  </Card>
</CardGroup>