> ## 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, 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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" ``` Mentions Include Files in Prompts ## 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: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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:** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai "@file:src/main.py @file:src/utils.py how do these files work together?" ``` ### Relative and Absolute Paths ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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/`: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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:** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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) ## Rule Mention Include a specific rule from `.praison/rules/`: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai "@rule:python-style apply these rules to my code" ``` ## Multiple Mentions Combine multiple mentions in a single prompt: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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: ````markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai "@file:src/auth.py @doc:security-guidelines review this code for security issues" ``` ### Documentation ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai "@file:src/api.py generate API documentation for this file" ``` ### Learning ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai "@url:https://docs.python.org/3/library/asyncio.html explain async/await" ``` ### Research ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai "@web:machine learning trends 2024 summarize the latest developments" ``` ### Refactoring ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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 Use specific file paths rather than directories Don't overload with too many mentions - context has limits Create reusable docs for frequently needed context 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](/cli/docs) - Manage project documentation * [Rules](/cli/rules) - Manage project rules * [CLI Overview](/cli/cli) - PraisonAI CLI documentation