Overview

agentty is an ADE (Agentic Development Environment) for structured, controllable AI-assisted software development. This project is built using agentty itself, including the docs and docs-site you are reading.

It runs AI coding agents in dedicated AI sessions.

What Agentty Provides🔗

When you start a session, Agentty does the operational heavy lifting for workflow safety:

  • Spawns a clean worktree branch for every live session.
  • Runs agent-driven edits in isolation from your base branch.
  • Keeps terminal output, diffs, and generated changes in one reviewable stream.
  • Keeps already-published session branches synced after later completed turns.

Typical Flow🔗

  1. Open a repository and start agentty.
  2. Press a for a regular session or Shift+A for a draft session.
  3. For regular sessions, type the first prompt and press Enter to start immediately.
  4. For draft sessions, stage one or more draft messages, then press s to start the bundle.
  5. Let the agent modify files in its worktree.
  6. Review the diff (d) and decide to apply or discard.

Worktree Isolation🔗

Every session runs in its own git worktree, created automatically when the live session starts:

  • The worktree branch is named wt/<hash>, where <hash> is derived from the session ID.
  • The branch is based on whichever branch was active when you launched agentty.
  • Regular sessions create the worktree as soon as you start the first prompt. Draft sessions delay worktree creation until you press s to start the staged bundle.
  • All agent edits happen inside the worktree, keeping your base branch untouched until you explicitly merge.
  • If worktree creation fails (e.g., git is not installed or permissions are insufficient), session creation fails atomically and displays an error.

Worktrees are stored under ~/.agentty/wt/ and are cleaned up automatically when a session reaches Done or Canceled, or when you delete a session.

Auto-Update🔗

Agentty checks npmjs for newer versions at startup and automatically installs updates in the background. Progress is shown in the status bar. The new version takes effect on next launch. Use --no-update to disable automatic updates.

Key Concepts🔗

ConceptDescription
AgentAn external AI CLI backend (Gemini, Claude, or Codex) that performs coding work. See Agents & Models.
SessionAn isolated unit of work: one prompt, one worktree branch, one reviewable diff. See Workflow and Keybindings.
ProjectA git repository registered in Agentty. Select between projects with the Projects tab.
Diff viewPress d in a review-state session to see exactly what the agent changed.

Next Steps🔗

  • Installation — install Agentty and run it for the first time.
  • Agents & Models — configure backends and choose models.
  • Workflow — learn the interface layout and session lifecycle.
  • Keybindings — learn the keyboard shortcuts for each view.