Sessions and Review

A session is one agent conversation on a task. Use it to direct work, inspect changes, and give precise feedback before you merge or ship. Concurrent sessions share the same task environment, so give each writer explicit file ownership.

Quick path

1. Start a session with a scoped prompt.
2. Watch chat and tool activity; answer clarification or permission requests.
3. Inspect the diff, run required checks, and send focused feedback until the change is ready.

Start a parallel session

You need a task with an environment and at least one agent profile compatible with that environment's executor.

On desktop:

1. Open the task.
2. Select + in a non-sidebar panel group.
3. Select Agents > New Agent.
4. Choose a compatible profile and enter the initial prompt.
5. Choose its starting context.
6. Select Start Agent. Kandev opens the new agent tab.

The New Session dialog does not accept a session name. Rename the session from its tab menu after it is created.

The empty-panel watermark has the same New Agent action. On mobile, open the Sessions picker and select New session.

The profile picker shows only profiles compatible with the task executor. If none are available, use the link in the dialog to configure an executor or agent profile. See Agents and profiles.

Choose starting context

Handoff from an existing session opens the same dialog with Blank context and an empty prompt. Select a session summary when you need earlier discussion. Summarization requires a working summarize-session utility agent. Review generated summaries: they can omit constraints or decisions.

Prompts support pasted, dropped, or selected attachments. A prompt can contain at most 10 files, with a limit of 10 MiB per file and 20 MiB in total. The prompt itself is required.

Manage session state

Right-click an agent tab on desktop to manage it. Available actions depend on its current state.

Stopping a session is not deletion. Resume needs the executor's session record. A removed worktree, expired remote environment, restarted executor, removed profile, or missing runtime record can require a fresh session.

When a turn, startup, or resume fails:

• For a supported ACP provider's classified temporary capacity, overload, or rate-limit error in an interactive task session with a concrete agent profile, Kandev records a failed turn and keeps the same runtime available when it can confirm that runtime is still usable. It retries only when it can establish that the prompt produced no assistant output or tool activity; otherwise, it does not replay the prompt. You can send another message or choose a supported model in the same session, and retry feedback reports only attempts that started. Office and automation tasks, dynamic routes, utility sessions, and passthrough sessions keep their existing failure handling.
• When startup or resume fails, or Kandev detects an unusable runtime, it adds one recovery entry to the selected session's chat. Select Resume to restore the saved conversation, or expand Technical details to inspect the failure.
• If the first task launch fails before the provider accepts the submitted prompt, select Start fresh session to retry that prompt in the same task session. Kandev restores the original text and available file-backed attachments after the provider is ready, and records one user message. It does not replay an accepted prompt or earlier conversation. If an original attachment is unavailable, Kandev leaves the failed session and warning in place; reattach the file in Chat before you continue.
• Restore read-only workspace does not send the pending prompt or dismiss its startup warning. The warning is resolved only after the provider confirms readiness for the matching recovery attempt.
• For failures that require manual startup or runtime recovery, the current unresolved failure replaces the blocked message composer with one recovery card. Automatic resume and workspace-restore failures appear in that card, with separate causes in Technical details, rather than a second session banner. Older entries keep their message and technical details without stale controls.
• In Kanban preview, selecting Plan keeps the recovery card below the Plan content, in the composer area.
• Repeated delivery of the same failure does not add another entry.
• History loading and new messages keep the normal chat scroll behavior.

For eligible failed Auggie ACP task sessions, the recovery card explains that Resume keeps the same conversation and skips saved mode and model overrides for that attempt. A success notice reports the provider-confirmed model name or ID when available. If the provider does not confirm a model, the notice makes no model claim. The notice confirms that the previous conversation was preserved, that saved selections remain unchanged for future launches, and that the restored permission mode may differ. A recovered failure remains in chat history with a Resolved label. A manually dismissed failure is labeled Dismissed and does not report a successful recovery. The matching failure remains Resolved even when a separate success notice is missing from the loaded chat. A later failure keeps its own recovery controls.

Interruption continuation

Interrupted conversation continuation is supported by default for eligible transient Cursor ACP failures. It can continue the unfinished request in the same saved conversation after output or completed foreground tools. Kandev sends a hidden internal continue instruction, preserves the transcript, and keeps previous results. It does not resend the original request or create a replacement conversation automatically.

Recovery shares the existing five-attempt budget and paced backoff. One notice shows waiting, reconnecting, or continuing, with Cancel available while the continued turn runs. Cancellation returns control to Chat when the ACP runtime is still usable; normal recovery actions remain available if it is not. An exhaustion message reports attempts that actually started; a refused recovery does not claim retries ran. Pending, unknown, failed, cancelled, malformed, or conflicting tool outcomes prevent automatic continuation. So do subagents, background work, unresolved, denied or cancelled permissions, and overlapping work after a turn handoff. If the runtime remains usable, send a follow-up in the same conversation. If it is unavailable, use the manual recovery actions. Missing saved identity and unsupported agents also require manual recovery. New human work takes priority. Backend restart retires the old automatic notice without launching a continuation or interrupting adopted live work.

No exactly-once execution guarantee is implied.

Restore read-only workspace makes the existing files available for inspection without claiming that the agent resumed. The session entry remains visible until the session resumes successfully. Kandev uses stacked touch-sized actions on phones. A failure in another session remains in that session's history.

If automatic resume restores the workspace in read-only mode, select Resume session in the notice to continue the saved conversation. The action stays visible while Recovery details is collapsed. Resume does not resend an interrupted instruction; send your next instruction after recovery succeeds. If a recovery card is already shown in Chat, use its Resume action.

The recovery card places the recommended action first and shows every available alternative as an individual button, including Restore read-only workspace and Start fresh session when eligible. Buttons wrap on desktop and stack at touch size on phones. Runtime installation failures offer Retry; provider quota failures show reset guidance, while Archive and Delete remain in the task menu. Restoring the workspace does not restart the agent. Expand Technical details for wrapped, bounded diagnostics; Copy details copies the same redacted text you see. When a workspace pane can identify the same failure and its visible recovery entry, View recovery opens Chat and focuses the recovery card. Independent workspace failures retain their own retry.

Failures during task or workspace preparation appear as one task error strip below the task header and above the session and Plan tabs. The strip remains visible when you switch sessions or tabs and disappears only after task recovery succeeds. Select Show details to open the available guarded actions in a desktop dialog or phone drawer.

If Kandev cannot prove that the native conversation is available, it keeps the session blocked and shows Continue from saved context when that action is safe. This action starts a new native conversation from bounded Kandev history. It does not restore private harness state, running tools, or old provider paths. This option applies to other recovery paths. Automatic restart recovery does not replace missing or unverified native state with a new conversation. Kandev does not resend a prompt when its outcome is uncertain. Resolve the recovery notice before sending new work.

When a compatible agentctl process survives a backend restart, Kandev first checks its delivery identity and durable cursor, then replays committed events before it accepts new work. This delivery recovery is automatic and separate from the executor setting that controls whether the agent process survives. If the delivery evidence is missing or inconsistent, Kandev keeps the session blocked and preserves Stop and the available recovery action.

If delivery is interrupted and the prompt outcome is uncertain, the recovery card shows Retry connection and Stop. Retry connection reconnects the original stream and replays committed output from its durable cursor. It does not resend the prompt or start a replacement conversation. Legacy streams use bounded intake and can show the same uncertain state when their missing output cannot be replayed.

After a backend restart, Kandev uses durable evidence to verify the saved owner and native conversation. If they match, Kandev restores the same task session when its agentctl process has terminated. It does not send another prompt, add a user message, or create a new turn. Send your next message when the composer is ready. If queued messages remain, restoration turns Auto-run off and keeps those messages. You can turn Auto-run on when you want them to run.

If the saved prompt record is missing, Retry connection checks the retained delivery record. Kandev restores it only when one saved user message matches one retained record. The original message stays in the conversation with a blocked delivery label. Retry does not send that message again, and the prompt outcome stays unknown. If the original agent process cannot be verified, Kandev keeps the session blocked and shows the reason. Record repair alone does not allow continuation.

Automatic restoration stays blocked when Kandev cannot verify the saved owner, native conversation, generation, or journal. A missing native conversation, unknown or changed owner, or locked or corrupt journal does not start a replacement conversation. The session keeps its safe recovery controls, such as Stop, while other eligible sessions can recover independently.

Stop remains available while Retry is pending. The card reports a failed Stop request or an unconfirmed cancellation. Retry reconnects and reconciles the saved delivery state; it does not create a new instruction.

Agentctl saves output in a journal on the executor's disk until the backend confirms that it saved the output. The journal also operates while the backend is connected. During a disconnect, the journal grows as the agent produces output. After reconnection, Kandev replays the output and acknowledges saved records, including when the agent has no new output.

The journal has no default 256 MiB stream limit or 2 GiB total limit. Unacknowledged output does not expire after a week or another fixed interval. The agent can continue independent work while usable disk space remains. Requests that need the Kandev backend, such as backend tools, can wait or fail during the outage.

Memory buffers and replay batches remain bounded. Agentctl reserves disk space for control and recovery records. If usable space approaches that reserve, agentctl blocks new prompts and requests cancellation of the affected turn. Committed output remains available for replay. A failed cancellation does not prove that the agent stopped. The journal never discards unacknowledged output to make room.

Backend delivery cleanup preserves saved conversation output on desktop and phones. It removes redundant transport payloads after safe projection and settlement. If an ACK was lost after cleanup, Retry connection uses the persisted cursor without resending the prompt. Uncertain work remains protected. Stop and the existing recovery actions remain available. See delivery retention operations for expiry, deletion, and rollback limits.

Kandev can replace the local agent runtime while the backend and browser connection stay active. This restores runtime service only. A session with an uncertain prompt outcome remains blocked until a safe recovery action or the next backend restart restores it. Runtime replacement does not resend that prompt or resolve its external effects.

Stopping a turn does not itself run the next queued message. If pending rows remain, Kandev sets their session's Auto-run switch to OFF. Expand the queue and turn Auto-run ON when you want FIFO processing to continue.

The expanded queue also lets you pause or discard stale work. Its compact header places the Auto-run and Auto-merge pills beside the queue count. Remove is available for every visible pending row, including messages from users, peer agents, workflows, and server actions; Clear all removes all visible pending rows in that session. Only user-origin rows remain editable. A message already reserved for delivery is hidden from the queue and cannot be cancelled with these controls.

Use Auto-run for queue processing:

• The setting belongs to the session and survives an empty queue, reload, and backend restart.
• A pending clarification or another lifecycle guard can hold the queue while Auto-run is on.

Auto-merge folds later compatible messages. It follows the install-wide setting until you change the session's pill. That change creates a session override that stays active for the session's lifetime.

Send while a session resumes

You can write and send the next prompt while an existing session is starting or resuming when its queue identity is ready. Kandev stores the prompt in the session queue, clears the composer after admission, and shows the normal queued-message indicator. The prompt runs when the session becomes ready and Auto-run is ON.

If Auto-run is OFF, the prompt remains pending until you turn Auto-run ON in the queue controls. If resume fails, the accepted prompt stays in the queue with the session and is available after a later successful recovery. Environment preparation without a usable session queue does not enable Send.

When you queue a prompt, Kandev records a submission identity before it reports success. The browser waits up to 10 seconds for a prompt without attachments and 30 seconds when attachments are included. If the connection result is uncertain, it checks the queue and recent conversation, then retries the same submission once. The server uses the identity to prevent duplicate entries.

A full queue, invalid content or attachment, identity conflict, or unavailable session shows a Message not sent error and keeps the draft and attachments. If delivery remains uncertain, Kandev shows Message send status unknown and keeps them for inspection. A confirmed admission clears only the submitted draft; a failed queue refresh does not turn an accepted admission into a failure.

Every row has Send Now for priority delivery:

• It sends the row immediately when the session can accept a prompt.
• For an active turn, it waits for backend cancellation acknowledgement. A handoff already in progress cannot be replaced; a conflict leaves the rows pending for retry.
• After a successful send, Auto-run turns on. Kandev sends that row first, then drains the remaining rows as separate FIFO turns.
• The toolbar's Cancel stops the active turn and sends no queued prompt. It turns Auto-run off for the backlog and can complete the workflow step or move the task to review.

A CLI-passthrough profile displays the agent's native terminal interface in a PTY. It still belongs to the task, but it does not provide Kandev's structured chat messages and tool-call presentation.

View active conversations in Threads

Use Threads to read active task conversations side by side without opening each task. Open it from the workspace view control or navigation, or go to /threads.

Threads shows one conversation tile for each task with an active primary agent session. The tile header shows the task status, workflow context, and any explicit permission or question that needs your attention. A normal waiting state does not mean that the agent asked a question.

On desktop, use the session tabs in a tile to switch between any existing session for that task. On a phone, tap the session control and choose a session from the bottom sheet. You can reply in the selected conversation without leaving Threads.

Choose a layout and composer visibility

1. Open View settings beside the saved view name. On a phone or touch tablet, tap the view name first, then View settings.
2. Under Display, choose Columns for full-height chats or Grid for two rows. Layout choices are kept inside View settings.
3. Optionally enable Auto-hide composer and adjust Maximum chats.
4. Changes preview immediately. Use Save to update the view, Save as to create another view, or Discard to restore its saved settings.

Save or discard changes in View settings before switching saved views. The view picker keeps your draft intact until you choose one of those actions.

Defaults are Columns, auto-hide off, and five total chats. Grid uses that same chat limit across both rows; increase Maximum chats if you want more chats. Each conversation scrolls independently, and the deck scrolls sideways when needed. Short windows temporarily show Columns with an explanation in Display; Grid returns when there is enough height, without changing the saved choice.

With auto-hide enabled on a mouse or trackpad, the whole composer and its controls hide when idle. Only the existing CI popover remains, when available. Hover over a chat or focus its tile with the keyboard to reveal the composer. The composer slides and fades in or out; reduced-motion settings make the change immediate. CI stays available throughout. The normal Cancel control remains available in the composer while an agent runs.

Typing, attachments, focused menus, and pending send/upload/cancellation operations keep the composer open. Questions, permissions, and recovery actions remain visible without hovering. Hide composer preserves an unsent draft and returns focus to the tile; press Enter or move the pointer out and back in to reopen it. Hiding does not cancel plugin operations.

Navigate on a phone

Phones show one conversation at a time, even when Grid is saved. On phones and touch tablets, the composer stays visible; the saved auto-hide preference still applies when you return to a mouse or trackpad layout.

On a phone, each conversation fills the screen width. The topbar shows your position beside the view name; small decks also show page dots. Position follows your swipe, even while the next conversation is loading. Swipe sideways, or tap the task title to choose a thread from a bottom sheet. The picker also shows task status, workflow, and step. Tap the view name below Threads at the top to change views. Use the separate topbar menu button for Quick Chat, Quick Terminal, and system status.

If a warning appears beside the view name on a phone, open the view picker to retry the failed saved-view update or dismiss the warning.

Open or manage a task

Select Open task in a tile when you need the complete task workbench. To link directly to a task and session, use a Threads URL with taskId and sessionId query parameters.

To manage the task without leaving Threads, select Task actions (the three dots beside Open task). On desktop, you can also right-click the task header; conversation text and editors keep their normal context menus. The menu offers Priority, Move to, Change workflow..., supported Link choices, Archive, and Delete, according to availability.

Choose Change workflow... to select a workflow and destination step, review the entry preview, and optionally map fixed workflow profiles for this task. On a phone, the form uses a full-height sheet with a scrollable body. Actions apply to the task whose menu you opened, even if its selected session changes. Canceling a form or confirmation leaves the task unchanged. See archive and deletion behavior for confirmation preferences and cleanup consequences.

Once you confirm Archive, its conversation disappears immediately while cleanup continues. With archive confirmation disabled, choosing Archive is enough. If the request fails, the task returns when your current filters and chat limit allow, without taking focus from the thread you are using.

If an action or view filter removes your current thread, Threads selects the next remaining thread, otherwise the previous one. If neither survives from the previous view, it selects the first thread in the new view. The empty view appears only when no threads remain. Your workspace and view settings stay in place.

Use the workbench

Desktop panel groups can host agent chat, files, terminals, Changes, the task plan, previews, and GitHub pull-request detail. Use + to add a panel. Mobile exposes sessions, files, terminal, and changes through task navigation and sheets. On a phone, the hamburger opens the same app menu from Home, listings, and the workbench. Tap the task title and chevron to switch tasks; the picker opens as an inset bottom card. Tap the Kanban, Threads, or List title dropdown for view options, search, filters, and display settings. The app menu uses Home for all listing modes, with Quick Chat and Quick terminal directly below it. Its collapsible Tasks section contains saved views, filters, and task actions; the adjacent + creates a task even when the section is collapsed. Automations and Integrations start collapsed; expand their headings to browse automations or connected providers. Integrations includes settings even before a provider is connected. Utilities follows these sections, with Settings before Stats. The current-session control shows the active agent's icon and name.

In multi-select view filters, selected options appear first when search is empty. Workflow-step options keep their workflow headings. Typing a search filters and ranks the matching options as usual.

The phone menu groups plugin controls in one Plugins section. When both workspace and task controls are available, Workspace and Task labels distinguish them. Optional System metrics appear after navigation, before Utilities, when the app status bar is disabled.

Press Cmd+Shift+F on macOS or Ctrl+Shift+F elsewhere to search the contents of every file in the active task workspace. Results are grouped by repository and show the repository-relative path, line number, and matching line; selecting one opens that repository's file at the match. Content search includes tracked files and untracked files that are not ignored. Use Cmd/Ctrl+Shift+K when you want to search only file names and paths across all repositories in the active task. The palette keeps Commands, Files, and Contents visible as compact tabs beside the search field while an active task workbench is open; elsewhere the palette remains command-only and leaves the workspace-search shortcuts untouched. Click a mode or press Tab / Shift+Tab to switch without clearing your query or moving focus from the search field. File matches are grouped by repository. Hover a mode to see its direct shortcut.

Open Settings > Preferences > Keyboard Shortcuts to customize these bindings.

In the Integrations group, click Unbound beside an integration, press a key combination, then select Save changes. The shortcut opens its Kandev dashboard from any app page; Sentry opens its connection settings. Active plugin links in the Integrations navigation group also appear here. These personal shortcuts start unassigned and follow your user settings across devices. Use the row's Reset action and save to remove a binding. Conflict indicators identify combinations shared with other actions; existing Kandev shortcuts take precedence. On a phone, recording a combination requires an attached keyboard. Tab and Shift+Tab remain available for moving keyboard focus, including while recording an integration shortcut. Ctrl/Cmd+Shift+P remains reserved for the command panel.

Open Settings > Preferences > Layouts to configure reusable desktop workbench profiles. Select a tab in a built-in layout to reveal its nearby edit controls, arrange or remove tabs and splits, then use the floating Save changes control. Kandev keeps the built-in row visible, marks it Customized, and stores your override without requiring a duplicate. Choose Reset beside a customized built-in to restore its original definition.

When you save a custom default, Kandev reapplies its split proportions to new and reset desktop tasks and scales them to the available workbench.

PR Details is a reusable Layouts panel whose visibility follows the active task's review association. Without a linked GitHub pull request or GitLab merge request, the tab stays hidden, even when the selected layout includes it. Once a review is linked, Kandev adds PR Details as an inactive tab: beside Agent for the built-in Default, or in the group and tab position you configured in the Layouts editor. Closing that tab prevents it from reappearing automatically in the same session. Changing the default applies to task environments without a saved task-specific layout and Reset Layout, not a layout already saved for a task. Removing Terminal from the Default layout also prevents Kandev from creating its initial user shell.

Each desktop split's + menu lists a linked review only while that exact review panel is missing from the live layout. Select a missing review there to open it in the split whose + you used. To move an open review to another split, drag its Dockview tab. Use Layouts only to change the default placement for new or reset task layouts.

All panels for a task point at the same task environment. In a multi-repository task, check the repository label before editing, committing, or reviewing. A preview also requires the application to listen on a reachable interface and expose a forwarded port.

When the repository defines a dev script, the desktop header shows a dev server control. Starting it runs the script in the task workspace, opens the browser preview, and opens a read-only Dev Server panel with the script's output. While the script runs, the same control becomes Stop dev server preview and terminates the process and its children. Kandev also stops a running dev script when its task is archived or deleted, so a preview cannot outlive the task that started it. A script that detaches itself from Kandev, for example by daemonizing or calling setsid, escapes that cleanup and must be stopped by hand.

Structured shell-command activity keeps the command, working directory, status, and output size in the chat row. Expand Output to fetch the transcript; Kandev continues refreshing an open, running command and stops when it reaches a terminal state. The disclosure separates standard output and errors, reports truncation and the exit code when known, and offers Retry when the transcript request fails. Historical command transcripts are loaded only when opened, which keeps long conversations responsive without discarding the stored output.

The ring in the chat-input toolbar shows the active session's context-window use when the agent reports a trustworthy window size. Open it to see used and total tokens; it focuses on the active session's context window. The hover also shows a session compaction count inferred from observed drops in used tokens. ACP does not report compaction events, so missing samples or provider resets can make the count approximate. For account-wide provider usage, install the Provider Usage plugin, which adds a provider pill to the session top bar and can add a compact display to the global status surface. That surface is off by default and follows the portable Show status bar preference under Settings > Preferences > Appearance > Status Bar; saving applies without a restart. The session top-bar pill remains available on its own when the preference is off. When it is on, the plugin can also appear in the desktop/tablet bottom bar or phone Status drawer. Configure the plugin under Settings > Plugins > Provider Usage. Kandev hides the context ring rather than presenting impossible data when reported use exceeds the reported window.

Render math in Markdown

Shared Markdown reading surfaces render common LaTeX formulas with KaTeX. Use single dollar signs for inline math and double dollar signs for a display formula:

Energy: $E = mc^2$

$$
\frac{a}{b}
$$

A standalone display can also use one line, such as $$a^2 + b^2 = c^2$$. Escape a dollar sign when you need literal currency text, such as \$100. Text such as $100 and $200 remains plain text.

Formulas use the existing chat or file-preview reading area. Wide display formulas scroll inside their own region on a phone, so the page keeps its normal width. This rendering applies to agent chat, Markdown file previews, task documents and plans, comments, pull-request and work-item descriptions, release notes, changelog entries, walkthroughs, findings, and queued messages.

Control chat animations

Open Settings > Preferences > Appearance and change Chat animations. The setting is on by default and controls incoming text, new chat items, and smooth scrolling on this device. Choose Save changes to keep the choice across reloads, or Reset to discard the preview.

Your device's reduced-motion preference disables these effects even when the switch is on. Turning chat animations off keeps content visible immediately and leaves the session's auto-scroll preference unchanged. Scroll up to read history without being pulled back by incoming content. Rich-output chart animations have their own Appearance setting.

Select Jump to latest above the composer to return to the newest message, including agent replies. The action appears only when newer content is below the transcript. It does not change the session's auto-scroll preference.

Inspect changes

Open + > Changes on desktop. A repository-less task has no Git state, so Kandev closes this panel automatically.

Symbolic links have a link icon beside their filename in workspace Staged and Unstaged rows, including untracked links. Opening a readable link shows Symlink beside its path in the file editor. These indicators are also visible on phones. In Files, symbolic links use a link icon in place of the usual file or folder icon. Each Changes row identifies the entry in that change layer; a deleted link keeps its marker. Opening and saving files follows the existing behavior.

Changes are grouped by repository and then by state:

• PR Changes for the linked pull-request comparison;
• Unstaged working-tree changes;
• Staged changes selected for the next commit;
• Commits on the task branch.

Focus a Changes row control. Press Arrow Up or Arrow Down to move between rows. Press Home to move to the first row. Press End to move to the last row. On an inline commit file row, press Enter or Space to open its diff.

From this panel you can stage or unstage files, discard working-tree changes, commit, amend, reset or revert commits, pull, rebase, merge, push, force-push, rename the task branch, choose a base branch, and create or open a pull request or merge request. Operations apply to the selected repository. Discarding a file is permanent, and history-changing operations can lose work or invalidate review; read Git operations before using them.

Kandev lists changed files before it finishes loading their diffs. Select a listed file to open its diff while it loads; the panel fills in the details automatically, without another file edit. If the diff cannot be loaded, Kandev shows Diff is unavailable.

While the first status check runs, the panel shows Checking changed files... and waits before showing an empty state. If status cannot be refreshed, select Retry; when earlier status exists, Kandev keeps those rows and shows Refresh failed. Showing last observed changes. The clean empty state appears only after a complete status check finds no changed files; pull-request changes and commits remain available when workspace status fails.

On phones and touch devices, working-tree rows give filenames the main space. Tap a filename to open its diff, or tap the row's Show more actions menu to stage or unstage, edit, or discard that file. The menu shows the full path, and discarding still requires confirmation. In list view, the folder appears below the filename; long filenames wrap.

In Commits, each row starts collapsed. Select a row to inspect its files inline; the saved flat or tree Changes layout applies to this list. Select the icon labeled Open commit to open the historical commit detail. Its flat file index can be collapsed independently of the file sections, and selecting an index entry opens that file's diff. These controls also work on phones.

Changes-panel Git operations use Kandev's control path, not the agent's shell. They can work when a restricted agent mode blocks shell writes to Git metadata. If the error says that .git/index.lock already exists or is held, stop other Git operations and inspect the lock before retrying. Remove a stale lock only after you confirm that no Git process owns it. The Changes panel uses the same worktree, so it does not bypass an active lock. If the agent cannot create .git/index.lock because of its permission mode, use the Changes panel. Read Git operations before you change the agent mode.

For a linked fork pull request, the Changes header shows the exact comparison target, such as upstream/widget:main. Kandev keeps this target separate from origin, the checked-out branch, and the push remote. Desktop hover details and the mobile touch drawer show the same target.

If Kandev cannot materialize that exact target, the Changes panel shows a comparison warning and hides numeric diff, commit, and ahead/behind totals. It does not use a same-named origin branch as a substitute. Check the executor's Git access and refresh the session after the target becomes available.

Open a file in its external repository

When Kandev has unambiguous repository context, file toolbars in Changes, Review, built-in viewers and editors, and their mobile layouts show Open file in GitHub, Open file in GitLab, or Open file in Azure DevOps. The action opens the provider page in a new browser tab. GitLab links support both gitlab.com and configured self-managed hosts.

The link uses the published source branch from a linked pull or merge request for that repository when available; otherwise it uses the task repository's base branch. Added or untracked files do not show the action until they exist on a published source branch. Deleted files open their base-branch version, while renamed files open the new path on a published source branch or the previous path on the base branch.

Kandev hides the action instead of guessing when a repository is local-only, unsupported, incompletely configured, or ambiguous. If a colleague cannot open the resulting page, check their permissions on the external repository; opening a link does not change provider access.

Review a diff

Select Review in the Changes header. Kandev builds a repository-aware file list by merging available uncommitted, cumulative committed, and linked-PR files. Initialized direct and nested Git submodules appear under their task-workspace scopes, so a submodule's README.md remains distinct from the parent repository's README.md. When a path occurs in more than one source within the same repository, the uncommitted version wins deduplication.

Review compares each submodule with the gitlink commit recorded by its parent and marks the submodule boundaries in the file hierarchy and diff headers. If a declared submodule is unavailable or uninitialized, Kandev keeps the parent's gitlink change visible instead of hiding the only available evidence. Pull requests for submodule repositories remain separate repository workflows; Review does not create or coordinate them.

When a task has multiple linked pull requests, use the PR selector in the Changes diff header or Review toolbar to inspect one PR revision at a time. The selection is scoped to that task for the current app session. Switching PRs replaces only the remote PR contribution; uncommitted and committed sources keep their normal precedence. Selecting a file from a specific PR row opens that exact PR revision, even when a sibling PR changes the same path.

When several pull requests are linked to a task, hover the PR control in the desktop top bar or tap the PR status chip on mobile to open the tabbed CI surface. Right-click the top-bar PR control on desktop to open Edit and remove a selected association. Each PR tab also has a Remove from task button. Removing a tab only detaches that Kandev task association; it does not close or modify the GitHub pull request, its branch or commits, the task repositories, or sibling PR associations. Explicitly linking that PR again restores the association.

Task rows and Kanban cards also let you remove an association. Open the menu, select Edit, then select Remove owner/repo #number from task. On a phone, open row actions or the card dots, then make the same selections. This action removes only that association. It does not change the GitHub pull request, its branch, or commits.

An automatic-merge error shows Retry in the selected PR tab on desktop and mobile. This action requests one new evaluation for that pull request. Kandev applies all current readiness rules before it sends another merge request. Other automation and state-loading errors show Refresh. Refresh loads the current state and does not authorize a merge.

During review you can:

• filter files and switch between unified and split diffs;
• enable word wrap, copy a diff, expand unchanged lines, or preview Markdown;
• open a file in the workbench editor or an external editor;
• mark files reviewed;
• discard a file or revert a supported diff block after confirmation;
• attach a pending comment to a changed line.

Reviewed state is stored per session. Kandev also stores the diff hash: if the file changes after you review it, the file becomes stale and unreviewed. By default, manually scrolling past a file marks it reviewed; file-selection jumps in Review do not. Use the review toolbar to disable Auto-mark reviewed on scroll. Review does not embed walkthrough steps in its diff list; follow a saved walkthrough from its launcher and file editor.

Whole-file feedback: Select Comment on file in a file header, or in its file actions menu on a phone. Add feedback without selecting lines, including for deleted, renamed, or non-text files. Saved comments appear above the diff, where you can edit or delete them. File comments join line comments in Fix comments and the chat composer.

Pending line and file comments are scoped to the current review session but persist only in that browser's sessionStorage; they are not synced to the backend or another browser. Select Fix comments to send the accumulated file, line, source, and comment context to the agent. If the agent is busy, normal session queuing applies.

While delivery is pending, Fix comments is disabled and your notes remain available. After acknowledgement, Kandev removes only unchanged submitted notes and closes Review if no pending review notes remain. Notes you edit or add while waiting stay available for your next send.

If sending fails or the connection is unavailable, Kandev shows an error and preserves your notes so you can retry. A connection error or timeout can leave delivery uncertain; Kandev does not resend automatically. Inspect the conversation before resending to see whether your feedback already arrived.

You can still close Review while waiting. Reopen the current diff before sending old feedback: a valid line number can still refer to different code after a rewrite.

Generate a walkthrough

Select Walkthrough from Changes or Review. Kandev sends the built-in changes-walkthrough prompt to the active session. If the agent is actively generating, the request queues; if it is idle, it starts a new turn immediately. A running Claude Code session that is only waiting on recognized background work also starts immediately when the high-risk Claude background prompt handoff experiment is enabled; the default behavior queues it. The agent must have task MCP and must call show_walkthrough_kandev with an ordered list of file and line anchors.

When the agent publishes the walkthrough:

1. Open the fixed walkthrough launcher.
2. Use Previous and Next to move through its steps.
3. Kandev opens and highlights the referenced file range. On mobile, the explanation appears in a bottom sheet.
4. Add feedback as pending context, or select Run to send that step's explanation, anchor, and your feedback to the active agent.
5. Close the walkthrough to keep it, or select Discard and confirm to delete it.

A task stores one walkthrough. Publishing another replaces the current one. Kandev validates that each step has text, a file, and a positive line range, but it does not verify that the file exists or that the explanation matches current code. Anchors can drift as files change, and a PR-only file may be available only in the review diff. A walkthrough is an explanation, not test or review evidence.

Commit and open a change request

The commit dialog commits staged changes by default. Enter a title and optional body. Stage all changes before committing is off by default; enable it only after checking every unstaged file. Utility agents can propose commit text, but you remain responsible for the result.

If a commit fails, the dialog keeps your title, body, repository and Stage all choice for correction and retry. You can dismiss and reopen it for the same repository without losing that draft. A successful commit clears the submitted draft; edits made while it was pending remain available. Drafts are local to the current session and environment and do not survive reloads. In a multi-repository commit, completed Git writes remain completed even if another repository fails.

The creation dialog requires a title, defaults it from the task title, accepts an optional body, and creates a draft by default. Kandev first runs git push --set-upstream origin HEAD, then selects the provider from the repository's origin:

• GitHub uses gh pr create and requires an installed, authenticated GitHub CLI.
• GitLab uses glab mr create when available or the matching workspace connection's token through GitLab REST. It supports gitlab.com and configured self-managed HTTPS or SSH remotes, resolves an omitted target from the project default, and attempts to link the resulting MR back to the task repository.
• Azure Repos uses az repos pr create and requires Azure CLI, the azure-devops extension, and either az login or AZURE_DEVOPS_EXT_PAT.
• Other Git hosts do not have a built-in creation path. Use that host's tooling from the terminal.

GitHub has the complete in-app PR review path. A linked PR detail panel shows checks, reviews, comments, conflicts, and merge readiness. It can add PR feedback to agent context, submit an approval when allowed, ask an agent to address conflicts, and merge using a method allowed by the repository. On an open PR, use the reviews list to re-request a reviewer whose review was dismissed. On a phone, open Review from the task bottom navigation to reach the same PR detail. GitHub permissions and repository policy remain authoritative; merge is enabled only when required checks, review state, and mergeability are ready.

GitLab has a provider-specific linked-MR panel. It shows overview and branch state, approvals and pipeline rollup, files, commits, reviewers, assignees, labels, and threaded discussions. It can add selected feedback to agent context, reply or resolve discussions, approve or unapprove, update people and labels, toggle MR notifications, merge, refresh, and unlink. GitLab permissions and project policy remain authoritative. See Integrations for linking and watch limits.

GitLab MR automation

The GitLab MR topbar control has an Automation group with the same two action controls as GitHub's:

• Auto-fix CI and address comments sends the agent a new or changed failing pipeline job or unresolved discussion note once the pipeline settles, and stops after 10 repair rounds for that MR. Disable and re-enable it to reset the limit.
• Auto-merge when ready merges only after the pipeline passes, unresolved discussions are cleared, and GitLab's own merge-readiness check agrees.

Below that, open Review follow-up for the same three notification switches GitHub uses. Every switch above belongs to one merge request: a task with several linked MRs shows an Automation group per MR, each labelled with its MR number, and turning a switch on for one leaves the others alone.

• Your review is requested wakes the agent when the workspace's connected GitLab account is newly added as a reviewer on the MR. Staying assigned across MR updates does not re-fire it; being removed and re-added (for example, for a re-review after changes) does.
• MR merged and MR closed without merging independently wake the agent when review work ends.

Lifecycle messages only report the observed event and canonical MR URL, and Kandev delivers them through the same task-session queue as GitHub's. The repair prompt comes from the built-in mr-auto-fix saved prompt and can be overridden for the task. Hovering the MR control in the desktop top bar (a single linked MR only) opens a preview with the pipeline pass rate, approval status, and unresolved-discussion count without opening the dropdown; touch surfaces skip the preview and tap straight to the dropdown. A linked MR also shows a status badge on the task's Kanban card, next to any linked pull-request badge. See Integrations.

Confidentiality: redaction is heuristic, a secret Gist is accessible to anyone with its URL, and the snapshot is rendered through a third-party service. Inspect the preview and do not share material that must remain private.

Completion checklist

Before moving a task to done:

1. Inspect unstaged, staged, committed, and PR changes for every repository.
2. Check untracked files and confirm the branch and comparison base.
3. Run the repository's required tests, lint, build, or validation commands in the task environment.
4. Resolve or explicitly defer review comments and stale files.
5. Review generated commit, PR, summary, and walkthrough text.
6. Check linked CI and provider review requirements.
7. Keep required human approval outside the agent loop.

Troubleshooting

• New Agent has no profiles: create a profile compatible with the task executor. A profile for another executor is intentionally hidden.
• Summary or generated text fails: configure the corresponding utility agent with an enabled ACP profile in Settings > Utility Agents. Repair any stale or disabled profile binding before retrying.
• Resume fails: start fresh when the executor no longer has resumable session state, then supply a summary or copy the relevant context.
• Delivery outcome is uncertain: use Retry connection on the session card. It reconnects to the accepted work and does not send the prompt again. A Stop request can remain unconfirmed while the original process is unreachable, so wait for Kandev to receive terminal evidence before sending the same work again.
• A peer message never arrives: check the target session state and ID. Running sessions queue messages; failed or cancelled sessions reject them. Expand the queue chip and check Auto-run: turn it ON for normal FIFO processing, use a row's Send Now for targeted priority, or remove stale work. For a full queue, remove or clear pending rows before retrying; an admin can also review the install-wide limit under Settings > Preferences > Task Behavior > Runtime.
• Changes is empty: select the correct repository and comparison, then confirm the agent wrote inside the materialized task path.
• Review marks became stale: the underlying diff changed. Re-review the new hash before marking the file complete.
• Walkthrough does not appear: confirm an active task-MCP session exists and that the saved changes-walkthrough prompt was not removed or made invalid.
• PR creation fails before opening a PR: fix push authentication, install or authenticate the provider CLI, and verify the remote host is supported.
• GitHub automation does nothing: confirm the PR is linked, automation is enabled, a session is available, checks have finished, and the 10-round cap has not been reached.
• Share is unavailable: wait until the session leaves CREATED/STARTING and configure GitHub Gist access. CLI-passthrough conversations do not have the structured snapshot used by this feature.

Related: Use Kandev, Tasks and workflows, Coordination, and Developer tools.

Agent tab close behavior

On desktop, the X on a deletable Agent tab deletes the session after confirmation by default. In Settings > Preferences > Task Behavior > Conversation, choose Hide panel when the X should only remove that panel. The conversation remains available from + > Agents, where selecting it reopens the panel.

Hidden panels remain hidden when you reload the same browser tab. They are local to that browser tab and task environment. Mobile Sessions controls continue to use the existing Delete action.