Workflow

Create a session, review its changes, then merge locally or publish a review request. See Keybindings for shortcuts by view.

Programmatic integrations can also track desired outcomes and explicit attempts through the Task API. Tasks use existing session workers; they do not add terminal controls or automatically complete sessions.

Interface Layout🔗

Use Tab and Shift+Tab to move between tabs:

• Projects: Choose a repository; view activity, usage, and installed agent CLIs.
• Sessions: Create and manage work in merge-queue, active, and archive groups. Press p to switch projects without leaving this tab.
• Settings: Configure appearance, model defaults, and launch commands.

Selected rows, options, and tabs use contrasting background colors. Selected session rows retain their status, size, and warning colors, with bold emphasis on the title. Other selected controls use bold labels. With NO_COLOR, selections use bold reverse video without a selector glyph.

Session chat titles and their [size] prefixes keep the bold, in-progress highlight in every status.

Agentty restores your last list tab on startup. Session chat shows [size] before the title, with green added-line and red removed-line totals on its right. A linked review request appears below the title. The composer’s bottom border shows the active-work timer alongside how long ago the session started, such as Timer: 2m 0s · Started 4m ago, and keeps them visible when you switch focus to the chat. In narrow terminals, the footer omits the session age to keep the timer visible. The composer shows agent/model [reasoning], response style, speed when supported, and permissions. Its border separates the input from the transcript without an extra horizontal rule. A fixed blank row above the composer stays clear while scrolling. While viewing an active session, the inactive composer collapses to its borders, hiding the empty input row. Press Enter to activate a reply when available. On every page, the help row sits directly above the bottom status bar without a blank row between them. Archived sessions hide the composer and keep the frozen active-work timer and session age above the navigation and continuation controls. The session returns to transcript view if it is archived while you are typing; unsent drafts, partial answers, and their attached images are discarded. The footer shows the active directory, branch, and ahead/behind counts. Up to eight session agent turns can execute at once; additional turns wait for capacity while their sessions remain responsive.

Projects and Discovery🔗

Agentty opens the repository you launch it from. Outside a repository, use the Projects tab to choose or add one. Saved projects load from the database; Agentty checks their folders only when you open them. Unavailable projects remain in your history and show an error when opened.

Launch directories outside repositories stay out of the project catalog. Older projects saved as repository subdirectories remain selectable in Projects and retain their existing sessions and settings.

A compact, content-sized startup popup offers once to discover repositories in your home directory, with the home path highlighted and Yes/No choices. No is selected by default. Accepting permits one scan; Agentty remembers either choice and never scans automatically on later launches. Scanning may trigger operating-system folder-access prompts. On short terminals, the explanation is clipped to keep the choices visible.

In Projects, press a to add a repository root by path, or d to discover within a folder you choose. Paths can be absolute, relative to the current project, or start with ~. Scans search up to five levels and 200 repositories, skip hidden folders and Agentty session worktrees, and do not follow directory symlinks. Inaccessible folders may be skipped. Press Esc to cancel. Select results with Space, then press Enter to save only the selected repositories.

Resource Usage🔗

Processes, CPU, and Memory cover the tracked agent and its descendants, refreshed about every two seconds. CPU can exceed 100%; resident memory may count shared pages more than once. Detached processes and Agentty itself are excluded. -- means no current measurement is available.

Host CPU temp measures the whole host, including other workloads. Sensor support varies by hardware and OS. Readings refresh at most every ten seconds and expire after twenty seconds if a sensor stalls.

Project Sync🔗

New worktrees start from the local active base branch. Press s from a list tab first if you need remote changes. Sync runs in the background; you can navigate and continue existing isolated work. Creating or starting sessions, merging, and rebasing against that project's base checkout require a retry after sync finishes. Existing merge work has priority. Repeated sync requests for one project are combined; other projects wait in order.

Progress and completion appear in the top status bar. A red [merge conflict] label on a session means its committed branch conflicts with its base. A failed conflict check leaves the result unknown.

For a linked GitHub pull request, the Sessions list adds a green [ready] label when GitHub reports the open, non-draft request has a clean merge state. Repository rules determine which checks and conversations block merging; resolved comments do not hide the label. The background forge refresh updates it every minute. A failed refresh keeps the last known label until the next successful update.

Session Lifecycle🔗

New sessions open the composer while their workspace is prepared. Submit immediately; the prompt waits for setup. If setup fails, press s from session view to retry. Prompts and images whose turns never began survive restart. Review the transcript before retrying a turn interrupted during dispatch.

Startup restores interrupted rebases to Review. Storage or Git cleanup failures must be resolved before startup can finish; a missing worktree alone does not block recovery.

Typical Transitions🔗

flowchart TD
  Draft --> InProgress
  InProgress --> Question
  Question --> InProgress
  InProgress --> Review
  Review --> AgentReview
  AgentReview --> Review
  Review --> Rebasing
  Rebasing --> Review
  Review --> Queued
  Queued --> Merging
  Merging --> Done
  Review --> Merged
  Merged -->|Manual target sync| Done
  Review --> Canceled

Active Turns and the Message Queue🔗

Press Enter during InProgress or Rebasing to queue a message. Messages, session sync (r), and publishing (p) run in submission order after the active work. Queued actions appear below the active status in execution order. Each item has a single-line preview; long messages are shortened to fit the panel. Repeated r presses queue only one sync. Publishing is also available during rebase.

During InProgress, Ctrl+C removes the newest queued message. With no messages left, it stops the active turn and cancels queued branch actions. Rebase cannot be interrupted this way. Queued chat survives project switching, but not an Agentty restart.

Changing provider or model waits for current work, saves the selection, then discards pending messages and actions. Resubmit them after switching. A failed save keeps the old selection and queue.

While composing, press Tab to focus and scroll chat; press it again to return. From chat focus, d previews changes and q returns to the list, preserving the draft. These controls also work while answering questions. Shift+Tab cycles permission modes without changing your draft.

In Diff mode, add file, line, or range comments and press s to submit them together with the existing draft and images. Finished comments survive leaving Diff mode and clear when the next turn starts. Read-only sessions cannot submit comments. See Diff Mode for editing and preview controls.

Focused Review🔗

Agentty automatically reviews a changed diff when an eligible session enters Review. Unchanged diffs and stopped turns skip automatic review. Press f to show the review or request one manually. While a review is running, f brings its progress into view without starting another review. A conflict-free sync keeps the running review and its progress visible.

Reviews use the diff and saved conversation, respecting accepted decisions. They inspect files and history and may browse, but recommend checks rather than run them. Progress shows the review profile and completed stages. Results remain visible across navigation until the next prompt.

Every completed review verifies candidate findings against relevant source, including single-batch reviews. Findings include source locations when their cited code matches the captured diff; deletion findings can cite the source before the change. Findings without matched primary evidence are marked unanchored. Supporting references remain unverified and are disclosed on each finding with primary evidence. Coverage reports processed and unfinished files and discloses unresolved file identities; processing a file does not guarantee that every defect was found.

Large reviews batch complete files and hunks where possible. Independent boundary checks receive a shared view of all changes and initial findings alongside the original fragments. Condensed cross-file context is disclosed. Each attempt has a 128-call budget and a 30-minute wall-clock deadline shared by all phases. A Partial result preserves findings and identifies unfinished checks; an empty suggestions list does not mean the review completed. Press f and confirm regeneration to resume completed calls for unchanged inputs, including after restart. Completed reviews regenerate from scratch; changed inputs or an accepted sync require fresh evidence. Summarized history is disclosed.

Reviews use criteria for the changed file types and test code. Add project criteria in .agentty/review-rules.json in the session worktree:

{
  "rules": [
    {
      "path_prefix": "src/api/",
      "extensions": ["rs"],
      "instructions": "Check authorization before accessing tenant data."
    }
  ]
}

Both filters must match when supplied; omit either to match all paths or extensions. Use relative path prefixes and extensions without dots. Renames match both old and new paths. Criteria add to the standard review policy, including for tests and deletions. Invalid configuration stops the review with an error. The file is limited to 64 KiB. Matching rules are included once with their filters. Selected criteria must fit within 8,000 rendered bytes, leaving room for source and history; shorten instructions or narrow the review scope if they exceed this limit. Final verification uses criteria from all original changed files, including when its input is summarized. Regenerate a review to use changed criteria.

Use /apply to have the agent verify suggestions and apply those that remain valid. Permission modes can automate this for up to three iterations.

Session Output Markdown🔗

Chat supports headings, lists, quotes, code blocks, and tables. Pasted indentation is preserved; tabs use four-column stops.

Mermaid code blocks render simple flowcharts, entity relationships, and sequence diagrams. Flowcharts support TD, TB, and LR; labels over 32 characters are truncated. Complex styling and grouping are simplified; unsupported, too large, or too wide diagrams remain readable as code. Markdown file previews use the same renderer.

Forking a Review Session🔗

Press F in a root Review or AgentReview session to confirm a fork. It receives a new worktree from the source commit and a copy of the saved conversation. Uncommitted changes are not copied. Publishing, review state, usage, and timing start independently. Stacked children cannot be forked.

Commit and Merge Behavior🔗

After a successful file-changing turn, Agentty creates or updates one evolving commit with a message generated from the cumulative changes. The project's Fast model and coauthor setting apply. Reverting all changes removes the empty session commit.

Large diffs use bounded file excerpts with explicit omission markers, avoiding a chain of model summaries. If the agent rejects the input, generation falls back to bounded changed filenames, recent chat history, and the existing message. Primary generation, fallback, and protocol repairs share one eight-call budget. Exhaustion or fallback failure stops auto-commit and leaves the worktree intact. Repeated hook diagnostics ignore changing build progress, durations, and process IDs when detecting stalled assistance.

An index lock is retried for up to five seconds. A persistent lock produces [Commit Error]; Agentty does not remove it. Wait for active Git operations to finish. Only the repository owner should remove a confirmed stale lock.

If pre-commit configuration exists but its hook is missing, session creation warns you. Continue with Enter or cancel with Esc / q; install the hook with prek install or pre-commit install. Commits without the configured hook show [Commit Warning]. Installed hook failures stop commits.

For an unlinked session, m queues a local squash merge using the session commit message. The target checkout must be clean. A failed rebase or merge returns the session to Review. Linked pull requests and merge requests must merge through their forge; see Review Request Sync.

Session sync (r) rebases onto the stored local base for unpublished sessions or the remote base after fetching for published sessions. Conflict assistance uses the existing agent conversation. Agentty stages repairs, runs the installed pre-commit hook, and continues the rebase. Hook failures allow up to three repair attempts before aborting with [Sync Error] and suppressing the push. The focused review stays visible after a rebase without conflicts. A conflict clears it before assistance changes the session files.

[Main Checkout Warning] means tracked changes in the main checkout changed during a turn and remain dirty. Inspect them before continuing. Unchanged pre-existing changes and clean branch movement do not trigger it. Bare-repository projects have no main checkout to inspect.

Continuing a Terminal Session🔗

Press c on Done or Canceled to confirm a new continuation draft. It uses the merged commit or saved conversation as context and leaves the original session unchanged.

Session Types🔗

Press a on Sessions:

• Regular: The first Enter submits work.
• Draft: Each Enter stages a message; s starts the bundle and creates its worktree from the base branch at that time.
• Stacked: Create a draft based on a parent session, up to five levels below a root.
• Append to stack [Preview]: Move an independent review-ready session below an eligible parent and sync it onto that branch. Sessions with children or linked review requests cannot be moved.
• Harness [Preview]: A regular session run by Agentty's built-in agent loop. It appears only when Agentty starts with --experimental-harness; see Harness Sessions.

Unavailable session types stay visible in readable muted text.

The legacy orchestrator session type is retired. Existing controllers and children remain independent sessions with their transcripts and workspaces intact. Campaign plans, reports, and pending follow-up instructions are saved in the controller history; pending campaign work is stopped. Former controllers and research sessions retain read-only permissions. For completed or canceled sessions, d is available only when an archived diff is stored.

Start stacked drafts from parent to child. Each needs a review-ready parent and an idle stack. Parents can receive replies and sync while materialized children are idle. Completing a parent turn or syncing it automatically rebases review-ready descendants. A parent merge retargets children to its base and keeps their own changes; failed child syncs show [Sync Error]. Canceling a parent also cancels all nonterminal descendants.

Branch Publish Flow🔗

Press p to publish a GitHub pull request or GitLab merge request. During a turn or rebase, publishing waits in the session queue.

1. Keep the default branch name or enter a custom one. A custom name must not already exist remotely. After publishing, the remote branch name is fixed.
2. Agentty pushes with a force-with-lease check, then creates or refreshes an open review request. Stacked children target their parent's review branch.
3. The forge URL appears in chat. Later completed turns automatically push to the same branch when no chat or sync is queued. If the remote already has the current commit, Agentty reports that the branch is already up to date. Failed pushes remain retryable with p.

Review-request titles stay stable unless the primary objective changes. Description updates preserve existing content and append new details. Agentty checks for concurrent remote edits before updating, but an edit after that check can still race.

Addressing Review Comments🔗

Open linked comments with c. Select actionable threads with Space, then press Enter to have the agent evaluate them in one turn. Resolved threads and standalone comments are read-only; outdated unresolved threads remain actionable without current line context. While the session is working, syncing, or publishing, the batch joins the same queue as chat messages, sync, and review-request creation. Its waiting row becomes a resolving indicator when the turn starts. If clarification is pending, the batch waits for your answers even when no other work is queued. Only one review-comment batch can wait at a time.

Review targets survive clarification and restart. After a successful commit and push, Agentty replies to each selected thread and resolves only those reported as fixed. Threads needing no change receive an explanation and stay open. An addressed thread becomes actionable again when a reviewer follows up.

[Review Comments Warning] reports failures. Failed or incomplete batches remain pending for the next session turn. Review turns finish their push and thread updates before queued edits begin. Automatic and manual pushes retry saved replies when the fix commit still matches the branch tip. If the branch has changed, continue the session to re-evaluate the pending comments before resolving them. Interrupted replies can resume without duplicating a reply already posted, including when a later automatic commit fails. Stopping a review turn also stops its pending push and thread updates; unfinished updates remain available for retry. A follow-up waiting for an earlier push can be stopped without waiting for that push to finish.

Publishing requires both Git credentials and an authenticated forge CLI: gh for GitHub or glab for GitLab. See Forge Authentication.

Review Request Sync🔗

Published review-ready sessions refresh forge status in the background:

A remote merge moves the session to read-only Merged, keeping its transcript and diff in Active. Manually sync its local target branch with list-mode s to move it to Done, clean up the worktree, and retarget stacked children. Failed syncs or syncing another branch leave it unchanged. Follow workflow warnings and retry if archival or child restacking fails.

If parent and child requests have both merged, syncing the parent's local target also completes the child. Closing an unmerged request cancels its editable session.

Clarification Interaction Loop🔗

In Question, answer each question; Agentty sends the answers together as a follow-up turn.

Use j / k or arrow keys to choose an option, then Enter. Move beyond the options to type a free-text answer; a blank answer means no answer. Type @ to insert a repository path.

Ctrl+C from the answer input ends the turn without replying. q outside free-text input returns to the list and preserves progress. Reopening resumes the unanswered questions. See Question Input for editing controls.

Prompt Input Extras🔗

Paste a clipboard image with Ctrl+V, Ctrl+Shift+V, or Alt+V. From a draft session, these also open the composer. Each attached image appears as [Image #n]; typing that text manually does not attach a file. While the image is read, the composer footer shows Pasting image... and you can keep typing; the image lands where you pasted it. Enter and prompt-history navigation wait until the paste finishes. Unsupported clipboard backends show an inline error; Wayland image reads use wl-paste when available.

Use Ctrl+Z to undo and Ctrl+Y or Ctrl+Shift+Z to redo. On macOS, use Ctrl+Z; your terminal may consume Cmd+Z. Prompt-history navigation preserves attached images.

Type @ to look up repository files. Unstarted stacked drafts use the nearest available ancestor worktree. See Prompt Input for completion and multiline editing.

Provider failures show a short error and captured output where available.

During a session turn, reported tool and skill invocations appear immediately in the output, in first-seen order. Each row updates as the call completes, fails, or is interrupted. Each compact row shows its status and an inline command or argument preview, shortened to fit the pane. Successful output stays hidden; failed calls show reported nonzero exit codes and up to two output lines. Codex, Claude, Gemini, and Antigravity supply these details where available. Live rows disappear when the turn ends. Skill names require explicit provider reporting.

Responses from these providers, including commit and rebase recovery assistance, include a usage footer when tool activity was observed. Tools lists invocation counts and failed or interrupted calls; Skills lists explicit Claude skill invocations. Footers remain attached to their responses in saved history, including failed recovery attempts. Reading a skill file does not establish invocation. Providers without activity reporting and older saved responses have no footer. Detailed previews are not saved in footers.

Session Sizes🔗

Sizes reflect changed lines and refresh after each turn:

Slash Commands🔗

Type / in the composer. From session view, / opens a fresh composer, replacing any saved draft. The picker supports fuzzy matching.

/apply requires a completed focused review. /mode selects:

• Auto Edit: Standard editing permissions. Codex has full command access; Claude can retry commands outside its sandbox. Commands are not necessarily confined to the worktree.
• Auto Edit + Auto Address Comments: The same permissions, plus automatic verification and application of focused-review suggestions. Stops when none remain or after three application turns. A new prompt or mode selection resets that limit.
• Read Only: Prevents filesystem writes during chat turns. Switch modes when edits are needed.

Shift+Tab cycles these modes while composing. See Agents & Models for speed costs and automatic model compatibility changes.

/style affects following user turns: Concise retains essential results, caveats, and verification; Balanced adds useful context; Detailed explains decisions and trade-offs thoroughly. Explicit prompt instructions take precedence. Style never changes permissions, safety requirements, or required output fields. The prompt input shows the selected style, including Balanced. On narrow terminals, the header preserves change totals, and the prompt keeps the style and permission indicators visible by shortening less important fields.

/personality reads .agents/agents/*/agent.md from the session worktree, excluding global definitions. Choose None (default) to clear it. File edits apply on the next turn; missing or invalid definitions fall back without stopping work and show a notice.

Agentty refines session titles from the overall goal using the Fast model. Draft titles update as messages are staged; committed work uses the commit title. Failed refinement leaves the provisional title in place.

Settings Scope🔗

The highlighted row is the selected setting. Move the selection with j / k, then press Enter to open or edit the setting.

Global settings control the theme. Project settings include model, reasoning, speed and style defaults, commit trailers, and launch configurations. Defaults affect new sessions; use slash commands to change an existing one. See Backend Defaults for Smart, Fast, and Review roles.

Launch Configurations is a command list: add with a, edit with e or Enter, delete with d, and reorder with J / K. Enter saves an edit; Esc cancels it. When Agentty runs in tmux, session-view o runs a configured command in the worktree or opens a selector if several commands exist.

Telemetry🔗

Telemetry is enabled by default and sends events to the Agentty PostHog project at https://us.i.posthog.com. Release builds bundle its public, write-only project token; debug builds, including tests, send nothing. Set AGENTTY_TELEMETRY_ENABLED=0 before launching Agentty to disable it; unset or 1 keeps it enabled, and any other value disables it.

AGENTTY_TELEMETRY_ENABLED=0 agentty

Every event includes app_source (cli), app_version, and install_method (npm, sh, cargo, or unknown).

Session types are regular, draft, stacked, and fork. agent identifies the selected provider; model is its supported model identifier. Turn events use the selection captured when the turn was queued.

Each event carries a random installation ID that Agentty creates on the first launch with telemetry enabled and stores in its database, so events from one Agentty root share an ID. Events set $process_person_profile=false. PostHog receives the request's source IP address and derives an approximate location from it. Agentty does not send error messages, stack traces, project paths, session IDs, or prompts. Session-start events count metadata reservations even if workspace preparation later fails. Turn-start events count messages that begin execution, including queued messages, rather than messages discarded before execution. Queued messages discarded by cancellation do not produce turn-interruption events. Failed turns do not produce turn-finish events. The install method is inferred from the npm package path, the shell install receipt, or Cargo install metadata. It is unknown when no signal is available. These values describe launches, not installation counts; metadata left behind after replacing a binary can report an older method.

Session Traces🔗

Session traces are separate from PostHog analytics and disabled by default. Pass a complete OTLP HTTP/protobuf traces endpoint to enable them, including in debug builds:

agentty --otlp-endpoint http://localhost:4318/v1/traces

Agentty uses the supplied traces path without appending /v1/traces. Endpoint environment variables cannot enable tracing or override this argument. For authenticated endpoints, set OTEL_EXPORTER_OTLP_TRACES_HEADERS, falling back to OTEL_EXPORTER_OTLP_HEADERS.

Each turn has a separate trace correlated by session and operation identifiers. Spans measure queue and capacity waits, workspace and context preparation, agent startup and attempts, response validation, persistence, and post-processing. A turn queued behind earlier work starts its trace when submitted; agentty.queue.wait_ms on the root span records that wait. Utility calls inherit their initiating context and record their agentty.purpose, such as commit message; work started after its parent finishes uses a linked trace. Provider operations appear beneath agent.attempt, including tool calls and supported response, reasoning, compaction, checkpoint, and subagent phases:

Operation categories and outcomes are exported by default without their content. Timing comes from observed lifecycle events; when only a completion arrives, a reported duration can reconstruct an interval within the attempt. agentty.timing.source is lifecycle for paired events, provider for reconstructed intervals, and completion for observations without a start or duration. Available operations depend on the provider and CLI version; they do not necessarily represent individual model requests. First activity is not a time-to-first-token measurement. Harness sessions run in process, so their invoke_agent, chat <model>, and execute_tool <tool> spans nest beneath agent.run and time each model request exactly.

Traces contain execution identifiers, provider/model selections, token counts, bounded outcomes, and available tool names, call identifiers, executable basenames, exit codes, and output byte counts. Command arguments, tool output, and project paths are excluded by default.

Add --otlp-capture-content alongside --otlp-endpoint to export tool commands, arguments, and results as previews of at most 4 KiB per attribute. Longer values keep their beginning and end around an omitted-byte count, so failure summaries at the end of command output stay visible. Separate stdout and stderr are included when present in Gemini's raw output; Codex supplies combined output. Original output sizes and truncation flags distinguish previews from complete results. Oversized structured arguments and results use the text attributes agentty.tool.input.preview and agentty.tool.output.preview instead of incomplete JSON in gen_ai.tool.call.arguments or gen_ai.tool.call.result. Complete structured values, including their redaction replacements, remain valid JSON. Exact output sizes still require walking the values, but metadata-only tracing does not serialize them. Larger payloads are not retained by tracing. Values containing common credential markers or URL credentials are replaced entirely with [REDACTED] before export, but arbitrary secrets and project paths may still appear. Enable this option only for content you intend to send to the configured receiver. Turn prompts, transcripts, reasoning, and subagent prompts remain excluded.

Content previews are supported for Codex command, MCP, and dynamic-tool items, Claude tool messages, and Gemini ACP tool input/output. Antigravity exports tool identities; its input/output fields are not captured. Missing fields are omitted; tool categories and titles are not treated as provider-reported tool names. All observed spans are sampled while enabled. Export is asynchronous and best effort: a full queue or unavailable receiver may lose spans. Agentty reports a coalesced diagnostic summary after restoring the terminal and limits final export flushing to three seconds.

Auto-Update🔗

Agentty checks the npm registry at startup and hourly. For global npm, Bun, and pnpm installs, it updates through the original package manager when exactly one manager's global installation matches the running binary. The status bar reports progress and asks you to restart after success.

If the installer cannot be identified, or an update fails, rerun your original installation command. Cargo, shell, local, and npx installs require manual updates. See Installation for update commands.

agentty --no-update

This disables automatic Agentty installation while retaining update checks and hints. See Backend Selection for agent CLI refresh. Use agentty --help for launch options and agentty --version for the installed version.

Data Location🔗

Agentty keeps its database, logs, and worktrees in its data root, normally ~/.agentty/. Worktrees are removed when sessions finish, are canceled, or are deleted. Set AGENTTY_ROOT to use another root; each root allows one running Agentty instance.

Continuing long sessions🔗

Follow-ups preserve the active goal and accepted decisions unless you cancel or replace them. A status question does not cancel work. Long sessions use opening and recent context with access to full history; the saved conversation remains intact.

Agents reuse successful checks while their inputs remain unchanged and still run repository-required checks.