Sessions

DAIV records every agent execution in a Session. A session is one agent thread — a persistent conversation context tied to a repository and ref. Every way you can trigger DAIV (webhooks, the Jobs API, the MCP endpoint, scheduled jobs, or a chat conversation you type yourself) produces a session, and every time the agent runs against that thread produces a Run inside it.

Navigate to Dashboard > Sessions (/dashboard/sessions/) to see the unified list. Clicking any session opens its detail page — the transcript, run timeline, and timing and usage for every execution.

What you can see

Admins see all sessions across every repository. Regular users see their own sessions, sessions matched to their git platform username (from webhook payloads), and sessions from Scheduled Jobs they subscribe to. The same scoping applies to the detail page, live updates, and retries.

Sessions and Runs

A Session groups all runs that share the same agent thread:

Session — the thread. Has a repository, ref, origin (how it was first triggered), title, and an optional link to an issue or merge request, schedule, or user.
Run — one agent execution inside that session. A session can have many runs: retries, follow-up chat turns, and FIFO-queued API submissions all add new runs to the same session.

A chat conversation is a session where the origin is Chat; each turn you send creates a new Run. A webhook event (issue or MR) creates a session tied to the issue or merge request; the single agent invocation is its first Run.

Origin types

Each session is tagged with the origin that created it:

Origin	Source	Example
Chat	Dashboard session workspace	You type a prompt and stream a reply
API Run	Jobs API `POST /api/jobs`	A CI pipeline or script submits a prompt
MCP Run	MCP Endpoint `submit_job` tool	Claude Code or Cursor delegates a task
Scheduled Run	Scheduled Jobs cron dispatch	A weekly dependency audit fires on Monday
UI Run	Dashboard run composer (see below)	You start a run from Dashboard > Sessions
Issue Webhook	GitLab/GitHub issue event	An issue is labelled `daiv`
MR/PR Webhook	GitLab/GitHub merge request event	A reviewer mentions `@daiv` on a merge request

Sessions list

The sessions list shows all sessions in reverse chronological order. Each row displays:

Status indicator — colour-coded dot (queued, pending, running, successful, failed) reflecting the latest run's state
Title — the session title (generated automatically from the first prompt or issue/MR subject)
Repository — which repository the agent operates on
Origin badge — the session's origin (see above)
Timing and usage — when the session was last active, and the total tokens and cost across all its runs

Queued runs

API and MCP runs that continue a thread already in flight don't start immediately. The new run is created in the Queued state and released in FIFO order once the prior run on that thread finishes.

Filtering

Use the filter controls at the top of the list to narrow results:

Filter	Description
Status	Queued, Pending, Running, Successful, or Failed
Origin type	Chat, API Run, MCP Run, Scheduled Run, UI Run, Issue Webhook, or MR/PR Webhook
Repository	Search and select a specific repository
Date range	From / To date pickers
Schedule	Pre-applied when navigating from a scheduled job's run count
Batch	Pre-applied when viewing a multi-repo submission group (one prompt submitted across several repositories shares a batch ID)
Merge request	Pre-applied when arriving from the view sessions link in a merge request description. Always paired with a repository, since IIDs are per-project; clearing the repository clears it too

Filters are combined with AND logic and reflected in the URL query string, so filtered views can be bookmarked or shared.

Live updates

Sessions with in-flight runs (Queued, Pending, or Running) update automatically via server-sent events. The status dot and timing update in real time without a page refresh.

Session detail

Click any session to see its full detail page, which includes:

Origin and status badges
Context — repository, branch/ref, linked schedule or issue/MR (as a clickable link), the agent model and thinking level, and the sandbox environment. Admins viewing another user's session also see the owning user.
Transcript — for chat-origin sessions, the full conversation transcript streams live during active runs and is replayed on return visits and mid-run refreshes — reopening the session rejoins the live stream and replays any events it missed (a fresh page load from the start of the run; an automatic reconnect only the events since it dropped).

For in-flight sessions the detail page updates in real time until the run completes.

Artifacts

A run's final message is a paragraph of text, and the agent's workspace is thrown away when the run ends. Tasks whose deliverable is a document — a dependency audit, a code-quality report, a changelog draft, a chart — need somewhere else to put it. That is what artifacts are for.

The agent has a publish_artifact tool: it writes the file to its scratchpad (/workspace/tmp/...), publishes it, and gets back a URL that it includes in its final response. DAIV copies the file out of the sandbox into its own storage and attaches it to the run, so it stays available after the sandbox is gone and without committing anything to the repository.

Published files appear inline in the transcript, as part of the turn that published them: adjacent publish_artifact calls in one turn group into a single Artifacts card, one row per file. Each row shows the title (linking to the viewer page, /dashboard/sessions/<thread_id>/artifacts/<id>/, opened in a new tab), a kind pill, the file size, and a download icon. A publish still in progress shows "Publishing…"; a publish that failed shows its path with a red × and the error message in red — in the same card as any files that did publish. Reloading the page renders the same rows, though publishes from consecutive model steps can land in separate cards. After a session's transcript expires, its artifacts still show on the session page, one card per run, below the expired notice.

What the viewer shows depends on the file type:

File type	Viewer
Markdown (`.md`)	Rendered server-side, sanitized, in the DAIV shell; Copy source copies the raw Markdown
HTML (`.html`)	Rendered inside a sandboxed frame — inline CSS and scripts run, but in an opaque origin with no access to DAIV cookies, storage or pages. Fetch/XHR and form posts are blocked; scripts, styles, images and fonts may still load over HTTPS. Full screen expands the frame
Images (`.png`, `.svg`, `.jpg`, `.gif`, `.webp`)	Displayed inline on a checkerboard, so transparency shows; click to open at full size
Text, CSV, JSON, XML, YAML, logs	Shown as preformatted text; Copy source copies it
Anything else (`.pdf`, archives, …)	Download only

Markdown and text files over 1 MiB are not previewed; the viewer offers the download instead.

The viewer's header shows the artifact's kind, its repository, and a link back to the session run that produced it. Open raw serves the file as-is under the same sandbox policy, so opening an HTML report in its own tab is as safe as the embedded frame. Whoever can open the session can open its artifacts.

Navigate to Dashboard > Artifacts (/dashboard/artifacts/) for every artifact you can see across all sessions — your own sessions, plus sessions on repositories you can read (admins see every artifact) — newest first, grouped by date (Today, Yesterday, Previous 7 days, Previous 30 days, then by month), 25 per page. Search by title or filename, and filter by kind (All, Markdown, HTML, Image, Text, or File) and repository. Each row links to the viewer, back to the session and run that produced it, and to a download. The viewer's breadcrumb links back to this list.

Artifacts are also listed in the Jobs API and MCP job-status responses, with absolute viewer and download URLs, so a CI pipeline or an editor assistant can hand the report to a person.

Limits and storage

A file is capped at DAIV_ARTIFACT_MAX_BYTES (default 10 MiB) and a run at DAIV_ARTIFACTS_PER_RUN_MAX files (default 20). Files live in Django's default file storage under MEDIA_ROOT (/home/daiv/data/media in the containers), which the app and worker containers must share through one volume — see the deployment guide. Deleting a run deletes its artifacts and their files.

Chat sessions

Chat is the interactive dashboard workspace where you converse with the agent in real time. Go to Dashboard > Sessions and click New session (/dashboard/sessions/new/) to open the empty workspace.

Before the composer appears, pick a repository in the hero picker. Each session is bound to a repository and a ref:

Selecting a repository defaults the ref to its default branch; you can switch to any other branch.
If the chosen ref already has an open merge/pull request, the workspace surfaces it.
The ref is the branch the work is based on: when the agent opens a new merge/pull request, that ref is its target branch. If it has been deleted from the remote by the time the agent publishes, the request targets the default branch instead.
The new merge/pull request is assigned to you, when your DAIV account is linked to the git platform through OAuth login.

Once a repository is selected, the prompt box appears and you can type your first message. The session gets its own URL (/dashboard/sessions/<thread_id>/) so you can bookmark it or share it with teammates who have access.

A session targets one repository and ref

The repository and ref are fixed for the life of the session. To work against a different repository or branch, start a new session.

As the agent works, the workspace streams updates live:

Assistant text and reasoning — replies render as Markdown; thinking/reasoning is shown in collapsible segments.
Tool calls — each tool call appears as an expandable card with its status (running, done, error), arguments, and result.
Todos — when the agent plans with a todo list, the side rail shows the list with a done/total count.
Files changed — files the agent reads or edits are collected in the rail; click one to jump to the tool call that touched it.

While a run is streaming you can press Stop to cancel it server-side. Refreshing the page or losing the connection does not stop the run — reopening the session rejoins the live stream. Only one run can be in flight per session at a time.

Model and sandbox environment

Each session pins three choices, set in the hero before your first message and then locked for the rest of the session:

Choice	What it controls	Default
Agent model	Which configured LLM the agent runs on	The admin-configured system default
Thinking level	Reasoning effort: Minimal, Low, Medium, High, or Extra high	The admin-configured default (if any)
Sandbox environment	The named Sandbox Environment the agent's commands run in	Auto — resolved per repository

These selections are fixed at session creation. To use a different model, effort level, or sandbox environment, start a new session.

Merge request awareness

When the agent commits changes, DAIV creates or updates a merge/pull request on the session's ref. The workspace shows an MR/PR pill that links to it and flags drafts. A pre-existing open request for the ref is detected and shown even before the agent runs.

The request itself links back to the session that produced it — see Linking back to sessions, which applies to every origin, not just chat.

Expired state

Session state lives in the agent checkpointer and can expire. Opening an expired session shows an "expired" notice; start a fresh session to continue.

Answering a question

When the agent hits a request that's genuinely ambiguous or a decision that's yours to make, it stops and asks instead of guessing. The run ends in the amber Needs input status, and the last turn renders as a card with 1 to 4 questions, each with:

Option buttons — click one to select it; a multi-select question is marked "Pick any that apply", and clicking toggles an option on or off alongside the others
A free-text field — type your own answer if none of the options fit, or if the question has no options at all

Answer sends all of your answers as a single message, one line per question; any question you leave blank is sent as "No preference". Skip declines the whole card and tells the agent to use its best judgment. Either way the agent carries on with reasonable defaults for what you didn't answer, states the assumptions it made, and doesn't ask the same questions again. Both start a new run on the same thread that picks up where the agent left off, and you can also just type a reply in the composer.

The card is only interactive on the session's last turn, and only while no run is in flight — once answered it stays visible but goes inert (options disabled, free-text field and buttons hidden), keeps the options your answer picked highlighted, even after a reload, and your answer shows as the next message. This isn't chat-only: the same card renders on a webhook or job session's transcript wherever a run ended on a question.

For job runs (a dashboard job submission, the Jobs API or MCP) and scheduled runs, DAIV also sends a notification listing the questions, so you know the run is waiting on you. Chat runs don't notify, and webhook runs rely on the question comment on the issue or merge/pull request, which mentions you.

Linking back to sessions

This applies to every session origin — chat, webhooks, scheduled and API runs alike — wherever the agent commits.

When DAIV opens a merge/pull request, its description carries a view sessions link. It resolves to the Sessions list filtered to that request, so it covers every session that worked on it — the one that opened it and each later one that addressed a review comment — and keeps working as more are added. A thread that produced several requests cannot tell which one the reader came from, so the link falls back to the producing session's transcript rather than guessing; the same fallback applies before any request is known.

Every commit DAIV makes also carries the producing session as a git trailer:

Text Only
1	`DAIV-Session: https://daiv.example.com/dashboard/sessions/<thread_id>/`

Unlike the description, the trailer is per-commit and append-only: it survives a rewritten description, reaches requests DAIV merely adopts (whose description is left untouched), and travels with the commit when it is squashed or cherry-picked. It joins any trailer block the commit message already ends with, so Co-authored-by and Closes keep working.

Admins can turn both off for the whole instance (Settings > Agent > Link sessions from merge requests) or per repository with session_link: false in .daiv.yml.

Starting a background run from the dashboard

You can launch an agent background run without typing in the chat workspace. Click Start a run on the Sessions page (or open Dashboard > Runs > New) to reach the run composer.

The composer accepts:

Prompt — what you want the agent to do
Repositories — one or more repositories. Submitting one prompt across multiple repositories creates a batch: each repository runs as an independent session, and after submission you land on the batch-filtered Sessions list.
Ref — the starting branch each run reads from, and the target branch of any merge/pull request it opens (defaults to the repository's default branch)
Sandbox environment — the named sandbox environment the run executes in
Agent model and thinking level — per-run overrides (leave empty to inherit the repo defaults)
Notifications are automatic: DAIV notifies on notify-worthy outcomes (found-issues, needs-attention, needs-input, failed). To silence a run, pass muted via the Jobs API or MCP endpoint; for scheduled runs, use the schedule's Mute toggle.

Runs started this way are tagged with the UI Run origin. A single-repository submission takes you straight to the session detail page; a multi-repository submission takes you to the batch-filtered list.

Retrying a run

Any finished, non-webhook, non-chat run is retryable. Open the session detail page, find the run in the timeline, and click Retry to open the run composer pre-filled with the original run's prompt, repository, ref, and agent model/thinking level. Adjust anything before submitting — the retry is a fresh run appended to the same session.

Result retention

Run records are permanent, but the underlying task result (which holds the full output and traceback) is subject to the task backend's retention policy. When the task result is pruned, the run still shows a denormalized summary and error message captured at completion time, along with the token usage and cost figures — these survive pruning.

How it works

A Session is created at the point of dispatch — when a webhook callback, API view, MCP tool, or schedule dispatcher enqueues a job, or when you send your first message in a new chat workspace. The Run record stores the trigger type, prompt, and a link to the background task result; the session holds the shared thread context.

sequenceDiagram
    participant Source as Trigger Source
    participant Handler as Callback / API / Dispatcher
    participant DB as Database
    participant Worker as Job Worker

    Source->>Handler: Event (webhook, API call, cron tick, chat prompt)
    Handler->>DB: Upsert Session (thread_id → repo, ref, origin)
    Handler->>Worker: Enqueue job task
    Handler->>DB: Create Run (status: Pending)
    Worker->>Worker: Execute agent
    Worker->>DB: Update task result (Running → Successful/Failed)
    Worker->>DB: Sync Run (status, timing, result, usage)

The Run model denormalizes key fields (status, timestamps, result summary, error message, token usage, cost) from the linked task result. This ensures the run record remains useful even after the task result row is pruned by the retention policy.

Legacy URLs

Old bookmarks to /dashboard/activity/<id>/ and /dashboard/chat/<thread_id>/ redirect permanently to the corresponding Sessions URLs — no broken links.

Sandbox Environments

Configure the named environments the agent's commands run in, and how Auto resolution picks one.

Sandbox Environments
Scheduled Jobs

Recurring agent runs — each dispatch creates a session per repository.

Scheduled Jobs
Jobs API

Submit runs programmatically; each job creates or continues a session.

Jobs API
Notifications

Know the moment a run finishes, via the in-app bell, email, or Rocket Chat.

Notifications