@ 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

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

❯ @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

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:

❯ @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.

Comparison with Other Tools

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

Related

• Message Queue - Queue messages while processing
• Interactive Mode - Full interactive TUI
• Slash Commands - /help, /stats, /queue