Quick Start

Learn how to add a project, create your first task, and launch an AI coding agent session in Verun — step by step.

Walk through the core workflow: add a project, create a task, and run your first AI agent session.

Adding a Project

Open Verun and click Add Project. Enter a name for your project, then select a git repository on your machine.

Your project must be a git repository. If your directory is not a git repo, initialize it first:

git init
git add .
git commit -m "initial commit"

Click Detect to let Claude analyze your project automatically. It scans your repo for .env files, detects which ports your app uses, and generates the setup and start configuration for you. This is the fastest way to get started.

Configure manually

If you prefer to set things up yourself, fill in the fields directly:

Field	What it does
Setup hook	Runs when a new worktree is created — use it to copy `.env` files, install dependencies, etc. The `$VERUN_REPO_PATH` variable points to your main repo root.
Destroy hook	Runs when a task is deleted — use it for any cleanup.
Start command	The dev server command to run inside each worktree (e.g. `pnpm dev`).
Auto-start	When enabled, the start command runs automatically whenever a new task is created.

A typical setup for a Node.js project looks like this:

Setup hook:    cp "$VERUN_REPO_PATH/.env" .env && pnpm install
Start command: pnpm dev
Auto-start:    on

Creating a Task

Each task automatically creates an isolated git worktree with a unique branch name. The setup commands from your .verun.json run automatically so each agent starts ready to work.

Task 1: "Refactor auth module"
  ├── Branch: sleepy-capybara-472
  ├── Worktree: .verun/worktrees/sleepy-capybara-472/
  ├── Ports: 10001-10010
  └── Status: Running

Task 2: "Add dark mode"
  ├── Branch: brave-penguin-891
  ├── Worktree: .verun/worktrees/brave-penguin-891/
  ├── Ports: 10011-10020
  └── Status: Generating

To create a task:

Select your project from the sidebar.
Click New Task.
Select a base branch to fork from.
Select a harness/agent provider to start with. Verun supports Claude Code, Codex, Open Code, Gemini CLI, and Cursor.
Verun creates an isolated worktree and branch automatically.

Agent Sessions

You can run multiple sessions per task. Sessions are resumable — close your laptop and pick up exactly where you left off. Each session talks directly to the CLI agent running inside the task's isolated worktree.

To start a session:

Open a task from the task list.
Select the Session tab.
Choose an agent provider from the list (Claude Code, Codex, Open Code, Gemini CLI, or Cursor).
Set the trust level for tool approvals.
The agent starts inside the isolated worktree and begins working immediately.

You can fork any session from any message to explore a different approach, or start a fresh session within the same task at any time.

Reviewing Changes

Open the Diff tab inside any task to see a side-by-side diff of all working-tree changes. You can also browse individual commits from the Commits panel. Syntax-highlighted diffs let you review what the agent changed, and clicking any line opens the file in the built-in editor at that exact position.

Git Workflow

Use the Git panel inside a task to stage files, write a commit message, and commit. Push to your remote and open a pull request directly from Verun — no terminal required. The PR creation flow pre-fills the title and body from the agent's session history. After merging, close the task and Verun removes the worktree.

Next Steps

Configuration — Set up .verun.json for your project.
Tool Approval — Choose a trust level for agent sessions.
Parallel Agents — Run multiple agents simultaneously.