@ 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
# Start interactive mode
praisonai --interactive
# 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:
❯ @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
When you submit a prompt with @file.txt, the file content is automatically included:
❯ @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:
❯ @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
| 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:
❯ @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
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
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
Use relative paths - They’re shorter and work across machines
Be specific - @src/utils.py is better than @utils.py if multiple exist
Avoid large files - Files over 50KB are truncated. Consider using specific sections.
| Feature | PraisonAI | Windsurf | Cursor | Gemini CLI |
|---|
| File mentions | ✅ | ✅ | ✅ | ✅ |
| Directory listing | ✅ | ✅ | ✅ | ✅ |
| Fuzzy search | ✅ | ✅ | ✅ | ✅ |
| Autocomplete | ✅ | ✅ | ✅ | ✅ |
| @diff | ❌ | ✅ | ✅ | ❌ |
| @web | ❌ | ✅ | ✅ | ❌ |
