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

# @ Mentions

> Include files and directories in your prompts with @ mentions

# @ Mentions

PraisonAI CLI supports @ mentions for including file and directory content directly in your prompts. Simply type `@` followed by a file or directory path to inject its content into your message.

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start interactive mode
praisonai chat

# Include a file in your prompt
❯ @main.py explain this code

# Include a directory listing
❯ @src/ what files are in this directory?

# Multiple @ mentions
❯ @config.yaml @main.py compare these files
```

## How It Works

```
┌─────────────────────────────────────────────────────────────┐
│                    @ Mention Flow                            │
├─────────────────────────────────────────────────────────────┤
│  1. User types @                                             │
│     ↓                                                        │
│  2. Autocomplete shows matching files/directories            │
│     ↓                                                        │
│  3. User selects or types full path                          │
│     ↓                                                        │
│  4. On submit, file content is injected into prompt          │
│     ↓                                                        │
│  5. LLM receives prompt + file content                       │
└─────────────────────────────────────────────────────────────┘
```

## Autocomplete

When you type `@`, an autocomplete dropdown appears showing matching files and directories:

<img src="https://mintcdn.com/praisonai/fT4nF3hY6KPMOPvS/docs/cli/at-mentions-at-mentions.gif?s=2881d968dc0643cac4dda246d611802b" alt="@ Mentions Demo" width="1497" height="1104" data-path="docs/cli/at-mentions-at-mentions.gif" />

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
❯ @main
  📄 main.py
  📄 main_test.py
  📁 main/
```

### Features

| Feature                 | Description                          |
| ----------------------- | ------------------------------------ |
| **Fuzzy matching**      | Type partial names to filter results |
| **File icons**          | 📄 for files, 📁 for directories     |
| **Cached results**      | Fast repeated searches (30s TTL)     |
| **Respects .gitignore** | Ignores common patterns              |

### Ignored Patterns

The following are automatically ignored:

* `.git`, `__pycache__`, `node_modules`
* `.venv`, `venv`, `.DS_Store`
* `*.pyc`, `*.pyo`, `*.egg-info`

## File Content Injection

<img src="https://mintcdn.com/praisonai/SX0Y8_-DRBjzOTnt/docs/cli/at-mentions-at-mentions-reads-file-content.gif?s=f397795831f145ba9ed577db5405574e" alt="@ Mentions Reads File Content" width="1651" height="1296" data-path="docs/cli/at-mentions-at-mentions-reads-file-content.gif" />

When you submit a prompt with `@file.txt`, the file content is automatically included:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
❯ @README.md summarize this file
📄 Included: README.md (5432 chars)

# Summary of README.md
...
```

### File Size Limits

* Files larger than **50KB** are automatically truncated
* A `[truncated, file too large]` message is appended

### Supported File Types

All text-based files are supported:

* Source code: `.py`, `.js`, `.ts`, `.go`, `.rs`, etc.
* Config files: `.yaml`, `.json`, `.toml`, `.ini`
* Documentation: `.md`, `.txt`, `.rst`
* And more...

## Directory Listings

Use `@directory/` to include a directory listing:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
❯ @src/ what's in this directory?
📁 Listed: src/ (15 items)

--- Directory listing of src/ ---
  main.py
  utils.py
  config.yaml
  tests/
--- End of src/ ---
```

### Directory Limits

* Maximum **50 entries** shown
* Hidden files (starting with `.`) are excluded
* Common ignore patterns applied

## Path Formats

| Format   | Example                 | Description            |
| -------- | ----------------------- | ---------------------- |
| Relative | `@main.py`              | From current directory |
| Nested   | `@src/utils/helpers.py` | Subdirectory paths     |
| Home     | `@~/config.yaml`        | Expands `~` to home    |
| Absolute | `@/etc/hosts`           | Full system path       |

## Multiple @ Mentions

You can include multiple files in a single prompt:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
❯ @package.json @tsconfig.json compare these configs

📄 Included: package.json (1234 chars)
📄 Included: tsconfig.json (567 chars)

# Comparison
...
```

## Error Handling

| Error             | Message                             |
| ----------------- | ----------------------------------- |
| File not found    | `⚠ Not found: path/to/file`         |
| Permission denied | `⚠ Permission denied: path/to/file` |
| Binary file       | Content may appear garbled          |

## Programmatic Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.cli.features import FileSearchService, CombinedCompleter

# File search service
service = FileSearchService(
    root_dir="/path/to/project",
    cache_ttl=30,  # seconds
    max_depth=5
)

# Search for files
results = service.search("main", max_results=20)
for result in results:
    print(f"{result.file_type}: {result.path} (score: {result.score})")

# Combined completer for prompt_toolkit
completer = CombinedCompleter(
    commands=["help", "exit", "queue"],
    root_dir="/path/to/project"
)
```

## Detection API

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.cli.features.at_mentions import detect_at_mention

# Detect @ mention context
context = detect_at_mention("read @src/main.py", cursor_pos=17)
if context and context.is_active:
    print(f"Query: {context.query}")  # "src/main.py"
    print(f"Start: {context.start_pos}")  # 5
```

## Best Practices

<Tip>
  **Use relative paths** - They're shorter and work across machines
</Tip>

<Tip>
  **Be specific** - `@src/utils.py` is better than `@utils.py` if multiple exist
</Tip>

<Warning>
  **Avoid large files** - Files over 50KB are truncated. Consider using specific sections.
</Warning>

## Comparison with Other Tools

| Feature           | PraisonAI | Windsurf | Cursor | Gemini CLI |
| ----------------- | --------- | -------- | ------ | ---------- |
| File mentions     | ✅         | ✅        | ✅      | ✅          |
| Directory listing | ✅         | ✅        | ✅      | ✅          |
| Fuzzy search      | ✅         | ✅        | ✅      | ✅          |
| Autocomplete      | ✅         | ✅        | ✅      | ✅          |
| @diff             | ❌         | ✅        | ✅      | ❌          |
| @web              | ❌         | ✅        | ✅      | ❌          |

## Related

* [Message Queue](/cli/message-queue) - Queue messages while processing
* [Interactive Mode](/cli/interactive-tui) - Full interactive TUI
* [Slash Commands](/cli/slash-commands) - `/help`, `/stats`, `/queue`