What You’ll Learn
Known limitations of Verdent, including file format restrictions, tool constraints, and platform-specific considerations.
Known Limitations
What Verdent Cannot Do
System Administration
Autonomous Execution
Real-Time Monitoring
Network Operations
No Direct System Administration
Cannot:
- Modify system settings
- Install system software
- Change system-level configurations
- Restart system services
Scope: Verdent operates within its workspace environment, not at the system administration level.Controlled Execution Only
Plan Mode Constraints:
- Plan Mode is read-only for safety
- Cannot execute file modifications in Plan Mode
- Must switch to Agent Mode for code changes
Safety Features:
- All file modifications tracked
- Worktree isolation prevents accidental main branch changes
- Review changes before rebasing worktrees
Verdent cannot execute commands in a worktree that you haven’t explicitly opened. All operations are scoped to the active workspace.
No Real-Time Monitoring
Cannot:
- Monitor running processes continuously
- Track file system changes in real-time
- Alert on system events
- Stream log files continuously
Alternative: Use MCP integrations for external monitoring tools.No Network Operations Without MCP
Built-in Limitations:
- Cannot make arbitrary HTTP requests (use
web_fetch for specific pages)
- No direct database connections (requires MCP)
- Cannot access cloud services directly (requires MCP)
- No real-time API integrations (requires MCP)
Solution: Configure MCP servers for external system access.
Operating System Differences
bash Tool Behavior:
| Platform | Shell | Notes |
|---|
| macOS | bash/zsh | Full bash functionality |
| Windows | PowerShell | Some bash commands unavailable, use PowerShell equivalents |
- Windows uses backslashes (
\), Unix uses forward slashes (/)
- File paths may need adjustment for cross-platform projects
macOS Considerations
| Issue | Details | Workaround |
|---|
| Gatekeeper warnings | First launch may show security warning | System Preferences → Security → Open Anyway |
| Keychain access | May prompt for keychain permission | Grant access for authentication storage |
Windows Considerations
| Issue | Details | Workaround |
|---|
| SmartScreen warnings | May block initial installation | Click “More info” → “Run anyway” |
| Long path support | Git worktrees may hit path limits | Enable long paths in Windows settings |
| Line endings | Git may warn about CRLF/LF | Configure git config core.autocrlf true |
# Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
Workarounds for Common Limitations
Binary Files
Large Files
Context Window
Platform Differences
Timeouts
Binary File Modification
Limitation: Cannot edit images, PDFs, or compiled binariesWorkarounds:
- Reference external tools in bash commands:
bash("convert input.png -resize 50% output.png")
- Generate scripts that external tools can execute
- Document manual steps for binary file operations
Example:# Image conversion
bash("convert input.png -resize 50% output.png")
# PDF to text
bash("pdftotext document.pdf output.txt")
Large File Handling
Limitation: Files over 10,000 lines strain the context windowWorkarounds:
- Use line ranges:
file_read("large.log", start_line=1000, max_lines=100)
- Search first:
grep_content("ERROR", glob="large.log") to find relevant sections
- Break files into smaller modules for easier management
Always use grep_content first to identify relevant sections, then read only those specific line ranges.
Context Window Exhaustion
Limitation: Long conversations fill the context windowWorkarounds:
- Delegate to @verifier subagent for isolated validation tasks
- Start new conversation for distinct tasks
- Use worktrees to isolate different task contexts
- Close unused worktrees to reduce cognitive load
Best Practice: Start fresh sessions for distinct tasks rather than continuing very long conversations.Limitation: bash commands differ between Windows and UnixWorkarounds:
- Use cross-platform tools: npm scripts instead of raw bash
- Conditional commands:
bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then ...; fi")
- Project-specific AGENTS.md with platform notes
Example:# Cross-platform
bash("npm run build")
# Platform-specific conditional
bash("if [[ \"$OSTYPE\" == \"linux-gnu\"* ]]; then make; else nmake; fi")
Timeout Constraints
Limitation: bash commands timeout after 2 minutes (hard limit, cannot be extended)Workarounds:
- Chain commands:
bash("task1") then bash("task2") then bash("task3")
- Break into smaller sequential operations that each complete within 2 minutes
- Run long operations outside Verdent and provide results
Example:# Extend timeout
bash("npm run long-build", timeout=600000)
# Chain operations
bash("npm install && npm test && npm run build")
Feature-Specific Limitations
Parallel Agent Limits
- No formal limit on number of parallel agents
- Practical limit: 2-4 agents for most systems
- Resource impact: Each agent consumes memory and credits
Recommendation: Monitor system resources; reduce agents if performance degrades.
MCP Server Limitations
- Requires Node.js for most MCP servers
- Some servers may require additional setup
- Server errors may not always have clear messages
Recommendation: Test MCP servers manually first; check server logs for detailed errors.
Future Improvements
Limitations are continuously being addressed. Check Verdent release notes for updates on expanded capabilities, increased limits, and new integrations.
See Also
