Frequently Asked Questions

Most common cause: Proxy configuration issue

Solution:

1. Open VS Code Settings (Cmd+, on macOS or Ctrl+, on Windows/Linux)
2. Search for "useProxy" or "verdent.enableProxy"
3. Toggle the proxy setting on/off (opposite of current state)
4. Try logging in again

Explanation: If you're behind a corporate firewall, you may need to enable the proxy setting. If you're on a home network, try disabling it.

Error: Free trial credits were not received or free trial access denied

Reason: A terms of service violation was detected during registration

Solution: Contact support@verdent.ai for assistance with your free trial access. The support team will review your account and help resolve the issue.

Error: Account registration was rejected or restricted

Reason: The registration violated Verdent's terms of service, resulting in access restriction

Solution: Contact support@verdent.ai for assistance. The support team can review your registration and provide guidance on resolving the issue.

Issue: Cannot find certain AI models in the model selection menu

Reason: Location-based restrictions from model providers

Explanation: Some AI model providers (Anthropic, OpenAI, Google) have regional restrictions that prevent certain models from being available in specific geographic locations. When this happens:

• Restricted models will not appear in your model selection menu
• You can still use all other available models without interruption
• No impact on your subscription or credits

Check Available Models: Visit https://www.verdent.ai/regions to see which models are available in your region

Note: Regional restrictions are set by the AI model providers, not by Verdent. Verdent cannot override these restrictions.

Visual Studio Code is a free, open-source code editor developed by Microsoft. It's a lightweight but powerful development environment that supports multiple programming languages and offers features like debugging, syntax highlighting, intelligent code completion, and integrated version control. Verdent integrates directly into Visual Studio Code as an extension, adding AI-powered coding capabilities to your existing workflow.

Verdent is an AI coding assistant extension for Visual Studio Code that helps with code generation, refactoring, debugging, and project navigation through natural language conversations.

Key capabilities:

• Code generation and modification via file tools
• Codebase exploration with specialized subagents
• Command execution through bash integration
• Custom extensibility via rules and MCP servers

Minimum requirements:

• Visual Studio Code 1.90.0 or higher
• Active Verdent subscription
• Internet connection

Platform support: macOS, Windows, Linux, WSL

1. Install Verdent extension from VS Code marketplace
2. Sign in with your Verdent account when prompted
3. Open any code file or project
4. Open Chat View and start conversing with Verdent

First task suggestion: Ask Verdent to explain your project structure or review a specific file.

Open Visual Studio Code and go to Help → About (or Code → About Visual Studio Code on macOS). The version number is displayed in the dialog. Verdent requires Visual Studio Code version 1.90.0 or higher.

You can also check via command line:

code --version

See Credits & Plans for the shared definition of credits, pricing tiers, and usage basics across Verdent products.

See What Happens If You Run Out of Credits for the shared account policy and recovery options.

Images pasted via clipboard or referenced by file path are processed within your conversation session. Images are not permanently stored and are cleared when you start a new conversation. File path references read the image locally without uploading.

Plan Mode is a read-only execution mode where Verdent analyzes code, conducts research, and creates detailed implementation plans without modifying files or executing commands. After generating a plan, Verdent presents two options: Edit (to request modifications and refine the plan) or Start Building (to switch to Agent Mode and begin execution). The agent can ask clarifying questions to remove uncertainty before execution. This mode is ideal for complex tasks where you want to review the approach before committing to changes, ensuring alignment between your expectations and Verdent's proposed solution.

No. Plan Mode is strictly read-only:

• Verdent can read files, search code, and analyze your codebase
• No file writes, edits, or deletions occur during Plan Mode
• Plans are displayed in the Chat View only
• Code execution begins only after you explicitly approve and switch to Agent Mode

Safety guarantee: Plan Mode cannot accidentally modify your code. It's designed for safe exploration and strategy development.

Switching is instant via the Input Box:

To Enter Plan Mode:

• Click Switch Mode button in Input Box
• Select Plan Mode from dropdown
• OR say: "Switch to Plan Mode"

To Exit Plan Mode:

• Click Switch Mode button in Input Box
• Select Agent Mode from dropdown
• OR choose Start Building after reviewing a plan

Mode persistence:

• Mode choice persists within the current session
• New sessions start in default Agent Mode
• You can switch modes freely at any time

Typical workflow: Plan Mode → review → Agent Mode → execute → back to Plan Mode for next complex feature.

Click the "New Session" button in the top bar. This clears the current conversation history and gives Verdent a fresh context window for your next task.

Yes, each VS Code window operates independently. You can have Verdent open in multiple projects, and each maintains its own separate conversation context.

Yes. Verdent uses standard Git commands, so it works with any Git repository regardless of hosting platform. For creating pull requests, Verdent uses the gh CLI which requires GitHub, but all other Git operations work universally.

Supported: All text-based file formats including:

• Source code (JavaScript, Python, TypeScript, Java, Go, etc.)
• Configuration files (JSON, YAML, TOML, XML, ENV)
• Documentation (Markdown, HTML, LaTeX)
• Build files (package.json, Makefile, requirements.txt)

Not supported: Binary files (images, videos, PDFs, compiled binaries, Office documents)

Workaround: Reference binary files in code but modifications require external tools.

Excellent support:

• JavaScript, TypeScript, Python, React, Vue, Angular
• Node.js, Go, Java/Spring, C#/.NET
• Swift, Kotlin, Flutter

Very Good support: Rust, C/C++, Ruby, R

Good support: PHP, Assembly, Julia

Common languages have stronger support due to extensive training data.

Three file operation tools:

• file_read: Read complete files or specific line ranges
• file_edit: Replace specific text patterns (targeted modifications)
• file_write: Create new files or complete file rewrites

Best practice: Use file_edit for modifications, file_write for new files only.

Running terminal commands or shell scripts through Verdent, including operations like running tests, installing packages, or executing build commands. Command execution requires approval in most Permission Modes to prevent unintended system changes.

Yes, using the bash tool. Verdent can run terminal commands with:

• Maximum timeout: 120 seconds (2 minutes)
• Command chaining with &&
• Cross-platform support (bash on Unix, PowerShell on Windows)

Safety: Commands execute with your user permissions. Use Manual Accept Mode to review before execution.

Maximum timeout: 120 seconds (2 minutes)

Commands exceeding 2 minutes will be automatically terminated. For longer operations, consider:

Alternatives:

• Break into smaller commands: bash("task1") && bash("task2")
• Break into smaller operations
• Run in background and check results separately

An iterative verification process where code is generated, tested, and repaired until it passes comprehensive testing. Verdent automatically runs tests, analyzes failures, fixes issues, and retests in multiple passes until the code works correctly. This delivers production-ready code, not just suggestions. Each result includes detailed summaries and code diffs showing exactly what changed.

Subagents are specialized AI agents with isolated context windows for specific tasks.

Built-in subagents:

• @Explorer: Codebase searches, architecture questions
• @Verifier: Quick validation checks
• @Code-reviewer: Security and quality reviews

When to use: Delegate research, validation, or review tasks to save main conversation context.

How to create custom subagents:

Create a markdown file in ~/.verdent/subagents/:

---
name: your-subagent
description: Purpose description
---
# System Prompt
[Behavior definition and expertise]

Use cases: Domain-specific expertise (finance, healthcare), team workflows, technology specialists.

When previous actions and information in the context create unintended behavioral patterns that affect future tasks. For example, if you repeatedly update code and then deploy it, the agent may begin associating all code updates with immediate deployment, even when you're just experimenting. Subagents prevent context pollution by operating with isolated context windows, allowing each specialized task to start with clean context and avoiding cross-contamination between different types of work.

Look at the input box at the bottom of the Verdent panel. The "Switch Permission" button displays your current mode (e.g., "Manual", "Auto", "Plan"). You can click it to switch modes.

Auto-Run Mode:

• File operations execute automatically without approval
• Commands still require permission
• Faster workflow for trusted codebases
• Best for solo projects with version control

Manual Accept Mode:

• Review and approve each protected operation
• Safer for shared codebases or production
• See exactly what will run before execution

Switch modes via Settings or command palette.

Operations that only read data without making changes: file reads and web searches. These are automatically approved in Auto-Run Mode, while file edits and command execution still require approval for safety.

No, permission modes are mutually exclusive - you can only use ONE at a time:

• Manual Accept - Default, maximum control
• Auto-Run - Streamlined for trusted projects
• Plan - Read-only planning mode
• Skip Permissions - Full autonomy

You can switch modes instantly via the Switch Permission button in the Input Box. Most users switch between modes based on task context (e.g., Plan Mode for complex features, Auto-Run for quick fixes).

Use the Explorer agent for discovery and search tasks without consuming main context. Load files directly with @-mentions only when you need to modify them. Explorer is ideal for "find all files that..." questions, while @-mentions are for "update this specific file" tasks.

Yes! Create custom subagents in ~/.verdent/subagents/:

---
name: your-subagent
description: Purpose description
---
# System Prompt
[Behavior definition and expertise]

Use cases: Domain-specific expertise (finance, healthcare), team workflows, technology specialists.

Yes. You can interrupt execution at any time. Verdent will complete the current step it's working on, then stop. Progress up to that point is preserved. You can review what's been done, make adjustments, and either continue or take a different approach.

Watch the todo list. It shows real-time status with one item marked "in progress" at any time. The active item shows exactly what Verdent is currently working on. Completed items are marked done, and pending items show what's remaining.

No. Verdent only creates commits when you explicitly request them. You maintain full control over when changes are committed. Simply ask "Stage all changes and create a commit" when you're ready.

No. Verdent only pushes to remote repositories when you explicitly request it. All Git operations (commit, push, merge, rebase) require your explicit instruction for safety.

Three customization methods:

1. VERDENT.md: Personal global preferences (~/.verdent/VERDENT.md)
2. AGENTS.md: Project-specific team standards (project root, version controlled)
3. plan_rules.md: Plan Mode output format (~/.verdent/plan_rules.md)

AGENTS.md overrides VERDENT.md for team consistency.

Most Verdent settings apply immediately without requiring a restart:

• Permission modes: Switch instantly via Input Box
• Model presets: Apply to next request
• Rules files: Apply to new conversations (save triggers reload)
• Subagents: Available immediately after creation
• Keyboard shortcuts: Apply after saving in VS Code

Exception: VS Code extension settings (like verdent.enableCheckpoints) take effect immediately but may require reopening files or sessions for full application.

Model Context Protocol (MCP) extends Verdent with external tools and services:

Configuration: ~/.verdent/mcp.json via Settings → MCP Servers

Capabilities:

• Database connections (PostgreSQL, MySQL, MongoDB)
• Cloud services (AWS, Azure, GCP)
• Project management tools (Jira, Linear)
• CI/CD pipelines (Jenkins, GitHub Actions)

Status: MCP integration docs in development. Contact support@verdent.ai for setup help.

The unit of measurement for context windows. Tokens represent pieces of text (words, parts of words, or characters) that the AI model processes. Context limits are measured in tokens rather than characters or words, with typical conversations consuming thousands of tokens.

Everything in your session: all messages in the conversation, file contents loaded into context, tool outputs (grep/search results, file reads), system prompts and instructions, and MCP server definitions. Each of these consumes tokens from your total context capacity.

Standard models (Claude 4.5 Sonnet, Haiku, GPT-5, GPT-5-Codex, MiniMax-M2) have 200K token context windows sufficient for most tasks. Claude Sonnet 4.5 offers extended 1M token context (5x larger) for large codebases with 1000+ files, complex multi-file refactoring, or long development sessions. The 1M context activates automatically when input exceeds 200K tokens or can be explicitly selected.

There's no fixed file limit - it depends on file sizes and total token count. For 200K contexts, avoid loading 20+ large files (>1000 lines each). Focus on files directly relevant to your current task. Use @-mentions selectively and leverage AGENTS.md documentation instead of loading many example files. With 1M context, file selection becomes much less critical.

Signs include slower response times, sessions running for several hours, or many large files loaded. Monitor your session length and file count. When you notice performance degradation, complete your current task, commit your progress, and start a fresh session with clean context.

Strategies:

1. Strategic file reading: Use line ranges for large files
2. Delegate to subagents: Explorer/Verifier for background research
3. Search before reading: Use grep_file to identify relevant files
4. Break operations: Use todo_update to track multi-step tasks

Rule of thumb: Files over 500 lines should use line ranges.

You must manually start a new session to reset context - Verdent does not automatically clear context. Best practice: reset after completing an atomic unit of work, testing, and committing to version control. For 1M token contexts, resets are needed much less frequently.

No - resetting context only clears the conversation history and loaded files from memory. Your actual code changes, commits, and file modifications are preserved. Always commit your work to version control before resetting context for safety. Reset → start fresh session → continue working on next task.

Be specific enough to eliminate ambiguity, but don't over-explain obvious details. Include: exact file paths, implementation approach, expected outcomes, and constraints. Bad: "Fix the code" - too vague. Good: "Add input validation to the email field in ContactForm.js to reject invalid email formats" - clear scope and goal. When in doubt, err on the side of more specificity.

Verdent automatically loads files mentioned by name in prompts and related files in the same directory. @-mentions (@filename.js) explicitly guarantee a file is in context, which is critical when working with tightly coupled files, referencing patterns from one file to apply in another, or when automatic detection might miss context in large codebases. Always use @-mentions when asking Verdent to "follow the same pattern as..." to ensure exact code reference.

No - Verdent maintains conversation context within a session, so you don't need to repeat architecture details or conventions already discussed. However, for critical constraints or when sessions get long (100+ messages), restate important context. Better approach: use project rules (AGENTS.md) to document persistent context like tech stack, coding standards, and patterns - then you never need to repeat them.

Use iterative refinement: review the output, identify what's wrong, then provide corrections in a follow-up prompt. Example: "The validation logic is good, but use Joi schema validation instead of manual checks. Match the validation pattern in ProductController.js." You can also ask for explanations: "Why did you use Redux instead of Context API?" then refine based on understanding. Don't repeat the same prompt - adjust based on what failed.

Use Plan Mode for: large refactorings or architectural changes, multi-file modifications where you want to review scope before execution, complex tasks where you're uncertain about requirements, or when you want Verdent to interview you with clarifying questions before implementation. Skip Plan Mode for: simple, well-defined tasks, quick bug fixes, or routine operations. Plan Mode adds overhead but prevents costly mistakes on complex work.

Match model preset to task complexity and budget:

Use Efficiency (3.2x more efficient than Sonnet):

• Quick bug fixes and simple code generation
• Routine operations and high-frequency tasks
• When speed matters more than depth

Use Balance (1x baseline) - Default:

• General development and everyday coding
• Feature implementation and code reviews
• Balanced performance for most scenarios

Use Performance (0.5x efficiency, 2x cost):

• Complex architectural decisions
• Large codebases requiring extensive context (200k+ tokens)
• Sophisticated debugging and refactoring

Pro tip: Most users keep Balance as default and switch to Performance only when hitting context limits or needing deep reasoning.

If Verdent cannot connect to AI services, check these common issues:

Test basic connectivity:

• Verify you have active internet access
• Try accessing other HTTPS services to confirm outbound connections work

Corporate/Enterprise environments:

• Contact your network administrator to whitelist Verdent's API endpoints
• Ensure outbound HTTPS traffic is allowed through your firewall
• Check if proxy servers are properly configured to pass through API requests
• SSL/TLS inspection may need exceptions for Verdent endpoints

Common symptoms:

• Extension appears to hang or timeout
• Authentication failures despite correct credentials

If issues persist after firewall configuration, contact Verdent support for specific endpoint details to whitelist.

Check:

• Location: File in project root directory
• Syntax: Valid Markdown
• Specificity: Rules are directive ("Always use..." not "Try to...")
• Fresh test: Start new conversation to test application

Precedence: AGENTS.md overrides VERDENT.md for project-specific behavior.

Causes:

• Text changed since last read
• Whitespace differences (spaces vs tabs)
• String not unique in file

Solutions:

• Read file again to get current contents
• Provide larger context string for uniqueness
• Use replace_all=true for multiple identical strings
• Verify file_path is correct

Check:

• Location: File in ~/.verdent/subagents/[name].md
• Invocation policy: Strict policy requires explicit @-mention
• YAML frontmatter: Valid syntax
• "When to use" guidelines: Match your request pattern

Test: Use explicit @-mention to verify subagent works: @your-subagent do task