Limitations & Constraints

Binary Files Not Supported

Verdent's file tools only work with text-based formats. The following cannot be edited:

Workaround: Binary files can be referenced in code or discussed conceptually, but modifications require external tools.

file_read Line Limits

Limitation:

• Large files (>10,000 lines) should be read in sections
• Reading entire large files may cause context exhaustion

Solution: Use line ranges: file_read("file.js", start_line=100, max_lines=50)

bash Command Timeouts

Limitation:

• Maximum timeout: 120 seconds (2 minutes)
• Long-running operations will be automatically terminated

Solution: Break operations into smaller commands that complete within 2 minutes

Search Performance

Limitation:

• Broad glob patterns (**/*) can return thousands of results
• Regex searches slower than literal strings

Solution: Use specific patterns and exclude unnecessary directories

Context Exhaustion

Issue: During long sessions or complex operations, the AI's context window can fill up, limiting the ability to reference earlier conversation.

Mitigation Strategies:

• Use subagents for focused tasks (results only consume main context)
• Read files strategically with line ranges
• Use grep_file before reading full contents

Internet Required

Verdent requires an active internet connection at all times.

Impact: Cannot work offline Reason: AI processing requires cloud connectivity

Git Repository Required

All projects must be git repositories for workspace isolation features.

Impact: Non-git projects cannot use parallel agents or worktrees

Workaround: Initialize git in any project directory:

cd your-project
git init
git add .
git commit -m "Initial commit"

Nested Git Repositories

If the selected directory's parent folder or subfolder is already a Git repository, support for this scenario is currently limited.

Recommendation: Select a single Git repository as the project root.

Support Quality Varies

Excellent Support:

• JavaScript, TypeScript, Python, React, Node.js, Java, Go

Very Good Support:

• C/C++, Rust, Ruby, Swift, Kotlin

Good Support:

• PHP, Assembly, Julia, Objective-C

Reason: Common languages have more training data. Less common or domain-specific languages may have reduced support quality but remain functional.

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

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.

Binary File Modification

Limitation: Cannot edit images, PDFs, or compiled binaries

Workarounds:

• 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 window

Workarounds:

• 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

Context Window Exhaustion

Limitation: Long conversations fill the context window

Workarounds:

• 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.

Platform Command Differences

Limitation: bash commands differ between Windows and Unix

Workarounds:

• 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")