> ## 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.

# Token Estimation CLI

> Configure how PraisonAI estimates token counts from the CLI

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="estimator", instructions="Preview token usage before heavy runs.")
agent.start("Estimate how many tokens this prompt will use.")
```

Control token estimation mode from the CLI — choose fast heuristics or accurate tiktoken counts when debugging context usage.

The user runs CLI token estimation to preview context size before starting an expensive chat session.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[User / CLI] --> M[Estimation Mode]
    M --> H[Heuristic]
    M --> A[Accurate tiktoken]
    M --> V[Validated]
    H --> C[Context Stats]
    A --> C
    V --> C

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

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
    class U input
    class M process
    class H,A,V mode
    class C output
```

## How It Works

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

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

## Quick Start

<Steps>
  <Step title="Run an agent with accurate token counts">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Assistant",
        instructions="Answer questions concisely.",
    )

    agent.start("Explain token estimation in one paragraph")
    ```

    Then check counts from the CLI:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai chat --context-estimation-mode accurate
    # In session: /context stats
    ```
  </Step>

  <Step title="Enable mismatch logging for debugging">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai chat \
      --context-estimation-mode validated \
      --context-log-mismatch
    ```

    Validated mode compares heuristic vs accurate estimates and logs when they diverge by more than 15%.
  </Step>
</Steps>

## CLI Flags

| Flag                        | Values                               | Default     | Description                              |
| --------------------------- | ------------------------------------ | ----------- | ---------------------------------------- |
| `--context-estimation-mode` | `heuristic`, `accurate`, `validated` | `heuristic` | How tokens are counted                   |
| `--context-log-mismatch`    | flag                                 | off         | Log when heuristic differs from accurate |

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Fast heuristic (default)
praisonai chat --context-estimation-mode heuristic

# Accurate with tiktoken
praisonai chat --context-estimation-mode accurate
```

## Interactive Commands

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> /context config   # View estimation mode
> /context stats    # Token counts per segment
```

## config.yaml

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
context:
  estimation:
    mode: heuristic
    log_mismatch: false
    mismatch_threshold_pct: 15.0
```

Environment variables: `PRAISONAI_CONTEXT_ESTIMATION_MODE`, `PRAISONAI_CONTEXT_LOG_MISMATCH`.

## Best Practices

<AccordionGroup>
  <Accordion title="Use heuristic in production">
    Heuristic mode is fastest and sufficient for compaction triggers in normal use.
  </Accordion>

  <Accordion title="Switch to accurate when counts look wrong">
    If compaction fires too early or too late, run with `--context-estimation-mode accurate` and check `/context stats`.
  </Accordion>

  <Accordion title="Use validated mode briefly when tuning">
    Enable validated + log-mismatch for a short session to calibrate heuristic accuracy for your model and prompt style.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Context Budgeter CLI" icon="gauge" href="/docs/features/context-budgeter-cli">
    Allocate token budgets per segment
  </Card>

  <Card title="Context Management" icon="layer-group" href="/docs/features/context-management">
    Full context system overview
  </Card>
</CardGroup>