Workflow

This page covers the Agentty interface layout, session lifecycle, session sizes, slash commands, and data location.

For keyboard shortcuts by view, see Keybindings.

Interface Layout🔗

Agentty organizes its interface into six primary tabs. Press Tab to move forward or Shift+Tab to move backward:

• Projects: Select between projects (git repositories) in a dashboard view with an activity heatmap, work-pace metrics, token usage, and a project table showing names, branches, session counts, last-opened dates, and paths. Detected agent CLIs and their versions are listed here too.
• Sessions: List, create, and manage agent sessions for the active project. Rows show a size marker prefix (for example [XL]), the current agent/model with its reasoning level, and a live active-work Timer column. The list shows only populated merge queue, active, and archive groups. When there are no sessions, it prompts you to press a to start one. Press p to open a project switcher popup that lists registered projects in most-recently-opened order and switches the active project without leaving the Sessions view.
• Inbox: Read-only list of open GitHub pull requests or GitLab merge requests that request your review in the active project, including drafts. Press s to refresh and Enter to open a read-only detail page with the description and comment threads.
• Issues: Open GitHub issues assigned to the user authenticated with gh in the active project repository. The table labels the non-empty result group Assigned to you. Press s to refresh, use j / k to move through the first 100 results, and press Enter to load a read-only detail page with base metadata and the description. Comments are not loaded in this iteration. Install the GitHub CLI and run gh auth login to enable this tab.
• Settings: Configure the color theme, default reasoning level, smart/fast/review model defaults, the optional Last used model as default mode, the session commit coauthor trailer, and Launch Configurations for the active project.

On startup, Agentty restores the last active list tab. If no tab has been saved yet but an active project is already persisted, Agentty opens on Sessions so you can resume project work without first selecting the project again.

In session chat view, the status-colored session title renders in a header row above the output panel, with a metadata row showing the size bucket, +added / -deleted line totals, the cumulative active-work timer, the current model, the effective reasoning level, and token usage. A linked pull-request or merge-request URL appears in the header when present. Press c on a linked review request to open its comments in a split page: comments and inline threads appear on the left, while the selected thread's metadata, attached current-diff context, and conversation appear on the right. In Review, AgentReview, or Question, press a to send the selected actionable comment to the active session agent or A to send every actionable comment. The timer ticks only while the session is actively working. A linked terminal session keeps C available for starting a continuation draft. File-level comments show an explicit no-line-context message instead of a synthetic code anchor. Each session stores the project reasoning default when it is created, so later default changes affect new sessions without relabeling existing ones.

The top status bar shows the current version and update status, and rotates short page-scoped FYI: messages once per minute in the Sessions list and session chat view.

The footer shows the active directory and branch. When the current branch tracks an upstream, the branch badge renders local -> remote. Inside a session, the footer switches to the session directory and shows the session branch's ahead/behind counts relative to its base branch, plus a second segment for the published remote branch when one exists.

New session worktrees start from the local active base branch. If local main is behind origin/main, the session branch still starts from local main; run list-mode sync (s) first when you want a new session to include remote-only commits.

If list-mode sync stops on rebase conflicts, the sync popup stays in its loading state and changes to a conflict-resolution message listing the conflicted files being handed to the assist agent.

Session Lifecycle🔗

Session statuses:

The shortcuts available in each state are listed in Keybindings.

When a session enters Review, Agentty starts focused review in the background. While it is running, AgentReview keeps the review-oriented shortcuts available; pressing r starts session sync immediately and cancels pending focused-review output so stale review text cannot reappear after the rebase begins.

Typical Transitions🔗

%%{init: { "flowchart": { "curve": "linear" } } }%%
flowchart TB
  classDef auxiliary stroke-dasharray: 4 2,stroke-width: 1.5px;
  classDef terminal stroke-width: 1.5px;

  subgraph start["Session Setup"]
    direction LR
    new_regular["Draft"]
    new_draft["Draft<br/>staging"]
    stacked_draft["Stacked<br/>draft"]
  end

  subgraph active["Active Turn"]
    direction LR
    in_progress["InProgress"]
    question["Question"]
  end

  subgraph finish["Review & Finish"]
    direction LR
    review["Review"]
    agent_review["AgentReview"]
    rebasing["Rebasing"]
    queued["Queued"]
    merging["Merging"]
    merged["Merged"]
    done["Done"]
    canceled["Canceled"]
  end

  new_regular -->|submit first prompt| in_progress
  new_draft -->|stage more drafts| new_draft
  new_draft -->|start staged bundle| in_progress
  new_draft -->|cancel from session list| canceled
  stacked_draft -->|stage more drafts| stacked_draft
  stacked_draft -->|start staged bundle<br/>when parent review-ready| in_progress
  stacked_draft -->|parent merged| new_draft
  stacked_draft -->|parent canceled| canceled
  stacked_draft -->|cancel from session list| canceled

  in_progress -->|turn completes| review
  in_progress -->|needs clarification| question
  in_progress -->|stop current turn| review
  in_progress -->|queue sync| rebasing
  in_progress -->|cancel from session list| canceled
  question -->|submit clarifications| in_progress
  question -->|Ctrl+C end turn| review

  review -->|generate focused review| agent_review
  review -->|create stacked draft| stacked_draft
  review -->|fork session| review
  agent_review -->|review ready| review
  agent_review -->|sync cancels review| rebasing
  review -->|sync| rebasing
  rebasing -->|sync complete| review
  review -->|queue merge| queued
  queued --> merging
  merging --> done
  review -->|cancel| canceled
  review -->|forge reports merge| merged
  merged -->|manual target sync| done

  class agent_review,rebasing auxiliary
  class done,canceled terminal

Active Turns and the Message Queue🔗

While a session is InProgress, an animated loader row shows transient provider thought and tool-status text; the transcript itself updates only after the final turn result is parsed and persisted.

Pressing Enter during a running turn or session sync opens the composer and queues the message inline with a queued › prefix below the transcript messages and workflow notices that preceded it. Queued messages dispatch one-by-one as new turns after the active turn or sync finishes. During InProgress, each Ctrl+c press retracts the most recently queued message (LIFO) without interrupting the running turn; once the queue is empty, the next Ctrl+c stops the current turn and returns the session to Review. Rebasing keeps cancellation unavailable while still accepting queued messages. The queue is in-memory only and is discarded if agentty restarts.

While the composer is open, Tab moves focus to the chat transcript above it so the conversation can be scrolled with j / k, g / G, and Ctrl+D / Ctrl+U without losing the typed draft. While that chat transcript is focused, d opens the diff preview for the session, and leaving it returns to the composer with the draft intact. Pressing q returns to the sessions list and saves the complete composer; reopening the session restores the typed draft with input focus. Pressing Tab again returns focus to the composer. The same focus toggle, d diff preview, and q preservation flow are available while answering clarification questions. Long transcripts show a slim scrollbar on the right side of the output panel to indicate the current position.

Pressing r during a running turn queues session sync on the same session worker. The session stays InProgress while the active turn runs, then moves to Rebasing when the queued sync command starts. The existing worker must accept the request; Agentty never creates a second worker from an InProgress status just to start sync. If sync arrives while Agentty is draining queued chat, the active chat turn finishes before sync runs, and sync runs before the remaining queued messages. Agentty shows a [Sync] notice below the active turn while the rebase is queued, and repeated r presses keep the single queued rebase instead of adding duplicates. Session sync reserves branch-publish ownership before it queues or starts, and retains that ownership through its post-rebase push. A completed turn or subsequent sync therefore cannot start a competing published-branch auto-push.

Focused Review🔗

When a session enters Review, Agentty starts generating a focused review in the background and temporarily shows AgentReview. Press f to append the cached review into the session output, or to see a loading message while generation is still running. The appended review stays visible across diff mode, question mode, session switching, project switching, and background session metadata refreshes, and is cleared when you submit the next prompt. Focused review includes the saved user and agent chat history for context. It uses inspection-only context: it may read files, search, inspect git history, and browse when needed, but it recommends verification commands instead of running checks itself. The review treats explicit decisions, accepted tradeoffs, and explanations in the chat as constraints, and only reopens a resolved suggestion when the current diff contradicts the resolution or inspection finds a new significant risk. Project Impact renders concise bullets directly beneath its heading. Suggestions uses the same compact spacing and formats its bullets as [Severity]: Issue details, using [High] or [Medium] when follow-up work is needed. Empty Suggestions output does not offer the /apply action. A turn stopped with Ctrl+c does not start a focused review automatically; press f for a manual one.

Session Output Markdown🔗

Session output renders common Markdown blocks in agent answers and persisted user messages, including headings, lists, block quotes, code fences, and pipe tables. Tables are aligned to the output panel width so compact comparison data stays readable in the terminal transcript. Leading horizontal whitespace in pasted prompts is preserved after submission, including nested indentation in multiline text. Tabs render at four-column tab stops. Transcript messages and workflow notices use one empty line between messages, regardless of padding stored with the message content.

Complete ```mermaid fenced blocks in session output render as Unicode diagrams. Simple graph/flowchart diagrams with TD, TB, or LR direction are supported, including edges that span multiple layers and compact two-node LR feedback loops. Common node shapes (stadium, subroutine, cylinder, hexagon, and more) draw as rectangle or rounded boxes, & groups fan out into one edge per pair, subgraphs are flattened into the surrounding graph, and styling statements such as style, classDef, linkStyle, click, and :::class tags are skipped. Solid, dotted, thick, long, and bidirectional edges render with optional labels in the -->|label|, -- label -->, -.label.->, and ==label==> forms. A reverse arrow such as A <-- B counts as an edge from B to A, so it places B on the earlier layer and joins any cycle in that direction. Invisible ~~~ links affect node layout without drawing a connector. Node and edge labels longer than the 32-character label limit are truncated with a trailing ellipsis, and HTML line-break labels degrade to the first renderable label line instead of preventing the graph preview. erDiagram entity-relationship diagrams render entities as boxes, relationships as lines labeled with the relationship name, and crow's-foot cardinalities as compact end markers — 1 (exactly one), ? (zero or one), * (zero or more), and + (one or more). Entity attribute blocks are omitted from the diagram. Simple sequenceDiagram participant and message lines render as lifelines with arrowed message rows; actor lines join as participants, notes, activations, autonumbering, and alt/opt/loop-style blocks are skipped, lifeline spacing adapts to the widest message label, self-messages render as a compact loop on their lifeline, and participant or message labels longer than the 32-character label limit are truncated with a trailing ellipsis instead of preventing the diagram preview. Unsupported diagram types, cyclic layouts, double-width label glyphs, incomplete blocks, and diagrams wider than the panel keep the plain fenced-code presentation. Session turn prompts tell agents about this supported diagram subset, so agents include a diagram when it explains a flow, process, or relationship better than prose. The prompts also instruct agents to place Mermaid only in the assistant answer as an unindented ```mermaid fenced block, because plain code fences or indented blocks stay in the fenced-code presentation.

Forking a Review Session🔗

Pressing F in a root Review or AgentReview session opens a confirmation, then creates a new independent Review session from the source session branch. The fork receives a fresh worktree branch and a copy of the durable transcript history as it existed at fork time. Stacked child sessions hide F because their branch remains tied to the parent stack workflow. Provider-native conversation IDs, focused-review cache, published branch state, linked review-request metadata, stack parent links, active-work timing, and token usage are reset on the fork so future replies and publishing are tracked separately from the source session.

Commit and Merge Behavior🔗

After each successful turn with file changes, Agentty keeps the session branch at one evolving commit: it regenerates the commit message from the cumulative session diff using the project's Default Fast Model, applies the Coauthored by Agentty setting, amends HEAD, and refreshes the session title from the commit text. If a later turn reverts every change, the empty session commit is dropped. Commit and merge notices appear as transient status rows rather than persisted transcript messages.

When a project contains .pre-commit-config.yaml or .pre-commit-config.yml, Agentty checks for an executable Git pre-commit hook when you press a. A missing hook opens a warning before the session-type selector. Press Enter to continue to the selector or Esc / q to cancel, and install the hook with prek install or pre-commit install when practical. This advisory will become an error in a future Agentty release.

For now, Agentty still creates the session and runs the normal Git commit command. If a commit succeeds without the configured hook, the session output records a [Commit Warning] with the installation commands. Later commits do not repeat an unchanged warning in the same session. Installed hooks remain enabled and their failures still stop the commit.

When a session without a linked review request merges, Agentty reuses the session branch HEAD commit message for the final squash commit on the base branch. Merging requires a clean main checkout and returns the session to Review if the preparatory rebase or squash-merge fails. After a pull request or merge request is linked, Agentty hides m and rejects local merge queueing; merge through the forge, and background review-request sync moves the session to read-only Merged when that remote merge completes. The session remains in Active until a successful manual main sync moves it to Done.

When a session syncs (r), Agentty rebases the session branch: published sessions fetch first and rebase onto the remote base ref, unpublished sessions rebase onto the stored local base branch. In InProgress, the sync request is queued behind the running turn before the session enters Rebasing. If the rebase stops on conflicts, Agentty asks the existing agent session to resolve only the conflicted files, then stages the edits and continues the rebase itself. The completed conversation and summary remain in their existing order while the rebase or merge status animates below them.

During normal turns, the agent prompt names the session worktree as the only writable root. After a turn, if Agentty detects that the main checkout's tracked-file status changed and remains dirty, it appends a [Main Checkout Warning] notice to the transcript. Clean HEAD movement, such as another session landing on the base branch, and unchanged pre-existing tracked changes do not emit this warning. Projects backed by a bare repository have no main working checkout, so this main-checkout dirty-state guard is skipped there.

Continuing a Done Session🔗

Pressing C on a Done session opens a confirmation, then creates a brand-new draft session with a continuation message staged from the merged commit hash (or the saved summary when the hash is unavailable). Canceled sessions remain terminal and read-only.

Draft and Stacked Sessions🔗

From the Sessions tab, press a to choose between Regular, Draft, and Stacked session creation:

• Regular starts the agent immediately on the first Enter.
• Draft stages each Enter as one ordered draft message and starts only after you press s. The worktree is created at that start step, so the branch is based on the base branch at launch time. From a draft session view, Ctrl+V, Ctrl+Shift+V, or Alt+V opens the draft composer and pastes one clipboard image into the next staged draft.
• Stacked creates a draft below the selected parent session, with its future branch based on the parent session branch. Only one stacking level is available.

Stacked drafts show s start only when the parent is in Review or AgentReview and no stack member is running, queued, syncing, merging, or waiting on a question. While a materialized child is linked, the parent keeps Enter replies, m merge queueing, and r sync but hides slash commands. Syncing the parent (or completing a parent turn) rebases review-ready children onto the refreshed parent branch automatically. When the parent merges, children are retargeted onto the parent's base branch and review-ready children are synced with git rebase --onto so they keep only their own commits. If an automatic child sync cannot start or complete, the affected child session shows a [Sync Error] notice with the failure. When the parent is canceled, its stacked child is canceled too.

Branch Publish Flow🔗

In Review and AgentReview, p opens a publish popup for the linked forge review request:

• Leave the field empty to keep the default branch target, or type a custom remote branch name. After the first publish, the popup is locked to that same remote branch.
• Agentty publishes with git push --force-with-lease, then creates or refreshes the linked review request. After confirmation, the popup closes and publishing continues in the background while session chat remains interactive. Inline progress is replaced only after the forge URL is ready, including across intermediate session refreshes. It becomes a one-line [Review Request] Created PR URL or [Review Request] Created MR URL transcript notice recorded at that point in session history, or failure details when the task finishes; p stays hidden while that publish is active. Later turns do not move or reconstruct the creation notice. GitHub projects publish pull requests; GitLab projects publish merge requests. Manual publishing and completed-turn auto-push share one per-session branch-operation lock, so whichever starts later waits instead of force-pushing the same branch concurrently.
• Stacked child review requests target the parent review branch while the parent link is active.
• When no review request is linked yet, only an open request for the same branch is reused; merged or closed requests are left alone.
• After the first publish, later completed turns push the same remote branch automatically in the background when no chat message or sync is already queued, and update the review request title and description from the latest session commit message when they differ. Failed background pushes keep the manual p flow available for retry.
• Agent-driven review-comment turns report one structured outcome for each supplied inline thread. After Agentty commits the work and successfully pushes an already published branch, it posts the agent's concise reply and resolves only allowlisted threads reported as fixed. Threads reported as no_change_needed, unknown thread IDs, blank replies, resolved threads, and outdated threads remain open. Reply or resolution failures produce a [Review Comments Warning] transcript notice and do not block the successful branch push.

Publishing needs regular Git authentication (credential helper or PAT for HTTPS remotes, SSH key for SSH remotes) plus the forge CLI for the repository remote: authenticated gh for GitHub and authenticated glab for GitLab. See Forge Authentication for setup steps.

Review Request Sync🔗

After a branch has been published, Agentty refreshes review-request status in the background for Review and AgentReview sessions. The session list shows forge indicators next to the status label:

When background refresh detects that the review request was merged, the session moves to read-only Merged and remains in the Active group. Transcript and diff inspection stay available, while replies, session sync, merge, publishing, commands, and new follow-up tasks are disabled. Agentty does not archive or clean up the session during background refresh or startup.

After the user manually syncs the review request's local target branch, Agentty moves the session to Done, archives it, cleans up its worktree in the background, and persists restack work for any stacked children. A failed sync or a sync of another branch leaves the session and its stack unchanged. Interrupted child restacks can resume after restart. If restack intent or archival cannot be persisted, the sync popup lists the session that remains in Merged so the user can inspect its workflow warning and retry safely. A closed request still moves an editable session to Canceled.

Clarification Interaction Loop🔗

If an agent emits structured clarification questions, the session moves to Question status. You answer each question in sequence, and Agentty sends one consolidated follow-up message back to the session.

Questions may include predefined answer options shown as a numbered list; use j/k or Up/Down to navigate and Enter to send the highlighted choice. Moving past the list edges switches to the free-text input. Sending a blank free-text answer stores no answer. Ctrl+C while the answer input is focused ends the clarification turn and returns the session to Review without sending a reply; it is ignored while chat output is focused. q (outside free-text input) returns to the sessions list with the Question state kept for later; answers already submitted are saved, and reopening the session resumes at the next unanswered question.

Prompt Input Extras🔗

In prompt input, Ctrl+V, Ctrl+Shift+V, and Alt+V paste one clipboard image into the current draft or reply as an inline [Image #n] token; from a draft session view, the same shortcuts first open the composer and then paste the image. The referenced local images are sent to the agent with the prompt. The clipboard source can be a copied PNG file, raw image data, or PNG path text from the host clipboard backend. Wayland reads use wl-paste when it is available; missing or unsupported clipboard backends report an inline paste error. Draft image files are removed when the composer is canceled, after a submitted turn finishes, and when a session is deleted or canceled.

All editable inputs use the same character movement, word movement and deletion, line-editing, paste, Ctrl+Z undo, and Ctrl+Y / Ctrl+Shift+Z redo behavior. Prompt and clarification inputs extend that shared editor with multiline movement and their own completion or option actions. Undoing prompt text also recomputes slash-command and @ lookup state; deleted image metadata remains available while undo history can restore its [Image #n] placeholder. Typing the same placeholder text manually does not attach the deleted image, and Agentty removes archived image files after their restoring edit falls out of bounded undo history. Attachment identity follows the exact placeholder occurrence, so duplicate lookalike text cannot substitute for the pasted token. Moving through prompt history with Up and Down preserves the attachment membership of the captured draft.

On macOS, use Ctrl+Z rather than Cmd+Z for input undo. Terminal applications such as Ghostty may consume Cmd+Z before Agentty or a surrounding tmux session receives it.

@ file lookups keep the raw @path/to/file text visible in the composer and transcript; the agent-facing prompt rewrites them to quoted path/to/file tokens.

If an agent command exits with an error, Agentty prints a short failure header followed by captured stdout and stderr sections, with JSONL provider events summarized into readable lines.

Session Sizes🔗

Agentty classifies sessions by the number of changed lines in their diff:

Session size is recalculated after each completed agent turn, persisted to the session record, and rendered as a title prefix in the Sessions list.

Slash Commands🔗

Type these in the prompt input to access special actions. From an editable session view, press / to open a new composer with the leading slash already inserted. This replaces any prompt draft previously saved by returning to the sessions list:

The command picker filters as you type and accepts contains or fuzzy abbreviations such as /o for /model.

/apply requires a completed focused review (f key). /model and /reasoning only offer locally available backends; see Agents & Models.

When the first prompt is submitted, Agentty stores it as the initial title and generates a refined title in the background using the project's Default Fast Model. Draft sessions regenerate the title as more drafts are staged.

Settings Scope🔗

Settings for models, reasoning, commit trailers, and launch configurations are stored per active project; the Theme setting is global. The Settings tab renders these scopes as Global settings and '<project>' settings. Rows with fixed choices open dropdowns; use j / k to move through options and Enter to save the highlighted value.

The Launch Configurations row opens a command-list editor instead of a multiline text field. Use a to add an entry, e or Enter to edit the selected entry, d to delete it, and J / K to reorder entries. Add/edit mode uses a single-line input; Enter saves the command, Esc cancels the input, and the shared word-editing, paste, undo/redo, and cursor shortcuts remain available. Agentty trims commands and drops empty entries when saving. When multiple Launch Configurations entries are configured, pressing o in a session opens a selector popup.

Auto-Update🔗

When Agentty launches, it checks npmjs for a newer version in the background. If a newer version is detected, it automatically runs npm i -g agentty@latest without blocking the UI:

• Updating to vX.Y.Z...: The background npm install is running.
• Updated to vX.Y.Z — restart to use new version: Installation succeeded; relaunch Agentty to use it.
• vX.Y.Z version available update with npm i -g agentty@latest: Automatic installation failed; run the displayed command manually.

To disable automatic updates, launch with --no-update:

agentty --no-update

When --no-update is set, Agentty still checks for newer versions and shows the manual update hint, but does not install automatically.

Run agentty --help to list supported launch options or agentty --version to print the installed Agentty version. Unsupported arguments produce an error instead of launching the TUI.

Data Location🔗

Agentty stores its data in ~/.agentty/ by default. This includes the SQLite database, session logs, and worktree checkouts (under ~/.agentty/wt/).

Per-session worktree folders are removed automatically after a session reaches Done or Canceled, and when a session record is deleted.

You can override this location by setting the AGENTTY_ROOT environment variable:

# Run agentty with a custom root directory
AGENTTY_ROOT=/tmp/agentty-test agentty