Core Concepts

Verdent introduces a few core concepts that help you use AI more effectively. This page walks through the main building blocks of how work happens in Verdent: Projects, Tasks, Execution Modes, Model Selection, and Workspaces, and how they fit together. A typical flow looks like this:

• You start by opening a Project — the local folder where your code and files live.
• Inside a project, you create a Task — running an agent to perform work within your codebase.
• When running a task, you choose an Execution Mode — Agent Mode to execute with write permissions, or Plan Mode to analyze and plan without modifying files.
• If needed, you can also choose a Model — different providers and models are better suited for different kinds of work.
• When multiple tasks need to change code in parallel, you use Workspaces — isolated working environments that keep changes separated and reduce conflicts.

---

​

Projects

A project in Verdent is a local folder that you actively work in. It usually contains a codebase, but it does not need to be a Git repository. Project Features:

• Session Persistence: Each project keeps its own session history and context
• Project Rules: Project-specific rules and guidelines (AGENTS.md)
• Quick Switching: Switch between projects instantly without losing context

Project Management:

---

​

Tasks

A task in Verdent represents running an agent to perform work within your current codebase. Think of it as a chat session with an agent. Tasks run in the current workspace, not in isolated environments. Creating multiple tasks means running multiple agents within the same codebase and workspace. While each task maintains its own conversation context, tasks are not isolated from each other—they all operate on the same files.

​

Task Lifecycle

​

Task Management

​

Rollback

Rollback lets you return to a previous point in the same task and continue from there. What gets reverted:

• Conversation context added after the rollback point
• Code changes made after the rollback point

Why it’s useful:

• Recover quickly when the task goes in the wrong direction
• Try a different approach without manually undoing changes or rewriting context

​

Duplicate

Duplicate lets you fork a task from any point and continue in parallel. What it creates:

• A new task that starts with the same context up to the selected point
• Two tasks that evolve independently from that point forward

Why it’s useful:

• Explore multiple solutions side-by-side
• Compare approaches with the same starting assumptions and context

​

Task States

---

​

Execution Modes

When you run a task, you choose how Verdent should execute it. Verdent supports two primary execution modes that control how the AI handles permissions and interactions: Primary Modes:

• Agent Mode (default) - Full autonomous execution with file modifications and command execution. Best for active development, implementing features, bug fixes, and running tests.
• Plan Mode - Read-only mode for analysis and planning without file modifications. Can ask clarifying questions before execution. Excellent for complex tasks, reviewing approaches, and architectural decisions.

Learn more: Execution Modes Overview

---

​

Model Selection

In addition to choosing an execution mode, you can choose which model (or provider) a task should use, depending on what you’re trying to accomplish. Verdent orchestrates models from multiple AI providers (Claude, GPT-5, Gemini) within a single workflow. Each specialized agent can leverage the optimal model for its specific task. Available Models: Learn more: Configuration Settings

---

​

Workspaces

A workspace in Verdent is an isolated working environment within a project. It’s an advanced capability designed to solve a real problem: when multiple tasks need to change code in parallel, changes can easily conflict. Workspaces keep those changes separated, so you can move faster without making a mess.

​

Workspace Types

• Base Workspace
  Your primary working environment on the branch you choose. It’s typically kept clean and stable, and serves as the reference point for integrating completed work.
• Additional Workspaces
  Create multiple workspaces from the Base Workspace. Each workspace is isolated, with its own set of code changes, so you can work on different tasks (or different solutions) in parallel without interfering with each other.

​

Why Workspaces Matter

​

Workspace Management

---

​

Parallel Execution

Verdent’s defining feature is the ability to run multiple AI agents simultaneously, each in its own isolated workspace.

​

How Parallel Execution Works

Each workspace:

• Has its own complete copy of the codebase
• Operates with isolated context
• Cannot interfere with other workspaces
• Produces reviewable, rebaseable changes

​

When to Use Parallel Execution (Pyro)

---

​

Git Worktree Integration

Verdent Workspaces are built on top of Git worktree.
You don’t need to understand Git worktree to use Workspaces, but if you want to know the underlying mechanism, this section explains the basics.

​

What is a Git Worktree?

A Git worktree is a Git feature that lets a single repository have multiple working directories at the same time. In practice, this means:

• Shared Git history: all worktrees share the same commit history, branches, and tags
• Separate working state: each worktree has its own working directory state (files, uncommitted changes)
• Branch-per-worktree: a worktree is typically attached to its own branch
• Native Git feature: supported by standard Git tooling and works with all Git hosts

Verdent uses these properties to implement Workspace isolation, so parallel work can happen safely without mixing changes.

​

Prerequisites

Workspaces require Git 2.20+ to be installed on your system.
See Git Installation if you need to install or upgrade Git.

---

​

FAQs

What happens if two agents modify the same file?

If two agents run in the same workspace and edit the same file, the result is not deterministic; later writes may overwrite earlier ones. Verdent does not guarantee safe conflict handling inside a single workspace.If you expect two agents might touch the same file, run them in separate workspaces instead. Each workspace is isolated, so both sets of changes are preserved independently. You can then review the results and decide what to keep (for example, merge one workspace and discard the other, or manually combine them).

How many parallel agents can I run?

Verdent doesn’t impose a hard limit. Practical limits depend on:

• System resources: Each agent consumes memory and CPU
• API rate limits: Credit consumption scales with active agents
• Git worktree limits: Git handles many worktrees efficiently

Most users run 2-4 parallel agents effectively.

Do workspaces share node_modules and other dependencies?

No, each workspace is a complete copy of the working directory. You may need to install dependencies (npm install, pip install, etc.) in each new workspace. Some users configure shared caches to speed up dependency installation.

What's the difference between a task and a workspace?

• Task: Running an agent to perform work. Multiple tasks run in the same workspace and operate on the same files.
• Workspace: An isolated working environment (Base Workspace or New Workspace) where code changes happen.

For parallel code changes that shouldn’t interfere, use separate workspaces.

Do tasks share context with each other?

Tasks share the same codebase and files, but each task maintains its own conversation context. Changes made by one task are visible to other tasks in the same workspace.

Does Verdent work with non-git repositories?

Yes. If your project doesn’t have Git initialized, Verdent creates its own Git repository for tracking changes and enabling workspace isolation. The worktree feature requires Git, but Verdent handles the setup automatically.

What happens if I delete a workspace with uncommitted changes?

Uncommitted changes are lost. Before deleting a workspace, review changes and rebase any work you want to keep.

How do I discard changes from a task I don't want?

Use the Discard Changes feature in the Source Control tab, or delete files directly in the Explorer tab.

---

​

See Also