@Mentions

Include files, docs, and web content in prompts using @mentions

The @mentions feature allows you to include external content in your prompts, similar to Cursor IDE’s mention system.

Quick Start

# Include a file
praisonai "@file:main.py explain this code"

# Include a doc
praisonai "@doc:project-overview help me understand this project"

# Search the web
praisonai "@web:python best practices give me tips"

Supported Mentions

Mention	Syntax	Description
File	@file:path/to/file.py	Include file content
Doc	@doc:doc-name	Include doc from .praison/docs/
Web	@web:search query	Search the web
URL	@url:https://...	Fetch URL content
Rule	@rule:rule-name	Include specific rule

File Mention

Include file content in your prompt:

praisonai "@file:src/main.py explain this code"

What happens:

1. The file content is read
2. Content is wrapped in a code block with language detection
3. Content is prepended to your prompt

Example with multiple files:

praisonai "@file:src/main.py @file:src/utils.py how do these files work together?"

Relative and Absolute Paths

# Relative path (from current directory)
praisonai "@file:src/main.py explain"

# Absolute path
praisonai "@file:/Users/me/project/main.py explain"

Doc Mention

Include documentation from .praison/docs/:

praisonai "@doc:project-overview help me add a new feature"

Prerequisites:

• Create docs using praisonai docs create
• Or add markdown files to .praison/docs/

Example:

# First create a doc
praisonai docs create coding-standards "Use type hints. Follow PEP 8."

# Then reference it
praisonai "@doc:coding-standards review my code"

Web Mention

Search the web and include results:

praisonai "@web:python asyncio tutorial explain async/await"

What happens:

1. Web search is performed using DuckDuckGo
2. Top 3 results are included
3. Results are prepended to your prompt

Requires duckduckgo-search package: pip install duckduckgo-search

URL Mention

Fetch and include content from a URL:

praisonai "@url:https://docs.python.org/3/tutorial/index.html summarize this"

What happens:

1. URL content is fetched
2. HTML is converted to text
3. Content is truncated if too long (max 10KB)

URL Safety

@url: mentions use the same URL allowlist as spider tools for security. Blocked URLs are rejected before fetching:

# Blocked URL example
praisonai "@url:http://localhost:8080/admin summarize this"

When a URL is blocked, the parser returns a placeholder instead of fetching:

# URL: http://localhost:8080/admin
[Blocked: URL is not allowed]

See the spider tools documentation for the complete list of blocked URL patterns.

Rule Mention

Include a specific rule from .praison/rules/:

praisonai "@rule:python-style apply these rules to my code"

Multiple Mentions

Combine multiple mentions in a single prompt:

praisonai "@file:main.py @doc:coding-standards @web:python best practices review and improve this code"

Processing order:

1. All mentions are extracted
2. Content is fetched for each mention
3. All content is prepended to the cleaned prompt
4. Agent processes the combined context

Context Format

When mentions are processed, the context is formatted as:

# File: main.py
```python
def hello():
    print("Hello, World!")

Doc: coding-standards

Use type hints for all functions. Follow PEP 8 style guide.

Web Search: python best practices

1. “Python Best Practices” - realpython.com …

Task:

review and improve this code

## Python API

```python
from praisonaiagents.tools.mentions import MentionsParser, process_mentions

# Initialize parser with default settings
parser = MentionsParser(workspace_path=".")

# Initialize with custom file size limit
parser = MentionsParser(
    workspace_path=".",
    max_file_chars=1000000  # 1 million chars
)

# Check if prompt has mentions
has_mentions = parser.has_mentions("@file:main.py explain")
print(has_mentions)  # True

# Extract mentions without processing
mentions = parser.extract_mentions("@file:main.py @doc:readme explain")
print(mentions)  # {'file': ['main.py'], 'doc': ['readme']}

# Process mentions and get context
context, cleaned_prompt = parser.process("@file:main.py explain this")
print(context)  # File content
print(cleaned_prompt)  # "explain this"

# Convenience function
context, prompt = process_mentions("@file:main.py explain")

Use Cases

Code Review

praisonai "@file:src/auth.py @doc:security-guidelines review this code for security issues"

Documentation

praisonai "@file:src/api.py generate API documentation for this file"

Learning

praisonai "@url:https://docs.python.org/3/library/asyncio.html explain async/await"

Research

praisonai "@web:machine learning trends 2024 summarize the latest developments"

Refactoring

praisonai "@file:old_code.py @doc:coding-standards refactor this code to follow our standards"

File Size Limits

By default, file content is limited to 500,000 characters (~125K tokens), which fits comfortably in modern LLMs like GPT-4o (128K), Claude 3.5 (200K), and Gemini (1M+).

Configuring the Limit

Environment Variable

# Set custom limit (1 million characters)
export PRAISON_MAX_FILE_CHARS=1000000
praisonai "@file:large_file.py explain"

# Disable limit entirely
export PRAISON_MAX_FILE_CHARS=0
praisonai "@file:huge_file.py explain"

Python API

from praisonaiagents.tools.mentions import MentionsParser

# Custom limit (1 million characters)
parser = MentionsParser(max_file_chars=1000000)
context, prompt = parser.process("@file:large_file.py explain")

# No limit
parser = MentionsParser(max_file_chars=0)
context, prompt = parser.process("@file:huge_file.py explain")

Limit Priority

1. Constructor parameter - Highest priority
2. Environment variable (PRAISON_MAX_FILE_CHARS)
3. Default - 500,000 characters

Truncation Warning

When a file is truncated, a warning is logged:

WARNING: File large_file.py truncated from 800,000 to 500,000 chars. 
Set PRAISON_MAX_FILE_CHARS=0 for no limit.

Recommended Limits by Model

Model	Context Window	Recommended max_file_chars
GPT-4o	128K tokens	400,000 (default is fine)
Claude 3.5 Sonnet	200K tokens	600,000
Claude Sonnet 4	1M tokens	3,000,000
Gemini 2.5 Pro	1M tokens	3,000,000
GPT-5	400K tokens	1,200,000

Token estimation: ~4 characters per token for English/code. Leave room for system prompt and output tokens.

Limitations

Limitation	Details
File size	Default 500KB, configurable via PRAISON_MAX_FILE_CHARS
URL content	Max 10KB after HTML stripping
Web search	Top 3 results only
Nested mentions	Not supported

Best Practices

Be Specific

Use specific file paths rather than directories

Combine Wisely

Don’t overload with too many mentions - context has limits

Create Docs

Create reusable docs for frequently needed context

Use Rules

Reference rules for consistent coding standards

Troubleshooting

Issue	Solution
File not found	Check the file path is correct and file exists
Doc not found	Create the doc with praisonai docs create
Web search failed	Install duckduckgo-search package
URL fetch failed	Check URL is accessible and valid

Related

• Docs - Manage project documentation
• Rules - Manage project rules
• CLI Overview - PraisonAI CLI documentation