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 creates a task, scans your repo for .env files, detects which ports your app uses, and generates the setup and start configuration for you. Hooks are saved automatically when the analysis completes — this is the fastest way to get started.

Configure manually

Fill in the fields directly to configure your project:

Field	What it does
Setup hook	Runs when a new worktree is created — copy `.env` files, install dependencies, etc.
Destroy hook	Runs when a task is deleted — use it for 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.

The following environment variables are injected into all hooks and the start command:

Variable	Value
`$VERUN_REPO_PATH`	Path to your project root (not the worktree)
`$VERUN_PORT_0` – `$VERUN_PORT_9`	10 unique ports allocated to this task

A typical setup for a Node.js project:

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

Creating a Task

Click New Task from your project in the sidebar. Each task automatically creates an isolated git worktree with a unique branch name.

Task 1: "Refactor auth module"
  ├── Branch: fizzbuzz-dragon-472
  ├── Worktree: .verun/worktrees/fizzbuzz-dragon-472/
  ├── Ports: VERUN_PORT_0=10000 … VERUN_PORT_9=10009
  └── Status: Running

Task 2: "Add dark mode"
  ├── Branch: nullpointer-phoenix-891
  ├── Worktree: .verun/worktrees/nullpointer-phoenix-891/
  ├── Ports: VERUN_PORT_0=10010 … VERUN_PORT_9=10019
  └── Status: Generating

In the New Task dialog:

Select a base branch — choose which branch the worktree should fork from.
Select an agent — pick the AI provider to use. Verun shows all installed agents and highlights any that aren't set up yet.
Click Create Task — Verun creates the worktree, runs your setup hook, and opens a session automatically.

Tasks get auto-named after their first agent message. Each task gets 10 dedicated ports (VERUN_PORT_0–9), starting at 10000 + (taskIndex × 10).

Agent Sessions

Sessions appear as tabs in the tab bar at the top of the main area — alongside any open file tabs. Click + in the tab bar to start a new session.

A dropdown appears with your installed agents:

Choose an agent — Claude Code, Codex, OpenCode, Gemini CLI, or Cursor.
Choose a model (optional) — hover an agent to see its model submenu.
The session tab opens and the agent starts in the task's isolated worktree.

You can have multiple session tabs open at once and switch between them freely. Sessions are resumable — close the app and pick up exactly where you left off.

Trust levels

Set the trust level in the message composer toolbar before or after sending:

Level	Behavior
Ask every time	Verun prompts you to approve every tool call the agent makes
Auto-approve safe	Reads and in-worktree edits are auto-approved; destructive shell commands prompt for approval
Full auto	All tool calls are auto-approved — no prompts

You can fork any session from any past message to explore a different approach without losing the original.

Reviewing Changes

Open the Source Control tab in the right panel to see all working-tree changes. Click any file to open a full side-by-side diff in the editor. You can also browse individual commits from the same panel. Clicking any diff line opens the file in the built-in editor at that exact position.

Use the Search tab (Cmd+Shift+F) to search file contents across the entire worktree with regex, case, and word-boundary toggles.

Git Workflow

Use the Git actions bar at the top of the task to commit, push, and open a pull request — all without leaving the app. Verun uses the gh CLI for PR operations and pre-fills the title and body from the agent's session. After merging, archive the task and Verun removes the worktree.

Next Steps

Configuration — Set up .verun.json for your project.
Tool Approval — Understand the three trust levels.
Parallel Agents — Run multiple agents simultaneously.