Skip to main content

​
Git integration

Last updated: 2025-11-28

​
Overview

KanbanAI’s Git module provides repository-level operations for both project repositories and per-Attempt worktrees. It emits git.* events so the UI and WebSocket layer can react to changes without tight coupling.

​
Status and diff

  • The Git module exposes helpers and endpoints to inspect repository state:
    • GET /attempts/:id/git/status – returns the current branch, staged/unstaged files, and summary for the Attempt’s worktree.
    • GET /attempts/:id/git/file – fetches file content for display in diff or editor views.
  • In the UI:
    • The Changes dialog uses these endpoints to show a structured diff of what the agent (or you) have changed inside the Attempt worktree.

​
Commit and push from the UI

  • Attempt-scoped Git endpoints allow you to commit and push directly from KanbanAI:
    • POST /attempts/:id/git/commit – create a commit in the Attempt’s worktree using the provided message.
    • POST /attempts/:id/git/push – push the Attempt branch to the preferred remote.
  • The Commit dialog:
    • Shows a summary of changes.
    • Lets you type a commit message.
    • Calls the Attempt Git endpoints under the hood.
  • Whenever commits or pushes occur, the Git module emits events such as:
    • git.commit.created
    • git.status.changed
    • git.push.completed
    • These feed into WebSocket broadcasts so the UI stays up to date.

​
Branch and merge helpers

  • For projects with long-lived base branches (e.g. main), KanbanAI provides merge helpers so Attempt branches can be rebased/merged before opening a PR:
    • mergeBranchIntoBaseForProject performs a merge into the configured base branch and publishes git.merge.completed.
  • In the UI, this is surfaced as a merge/refresh flow in the Attempt panel and PR dialog, helping you:
    • Ensure your Attempt branch is up to date.
    • Resolve conflicts in the Attempt worktree before creating a PR.

​
Open in editor

  • The Editor module integrates tightly with Git:
    • POST /attempts/:id/open-editor opens your preferred editor at the Attempt’s worktree path.
    • Editor detection and environment preparation are handled by the server (see dev/server-editor.md).
    • The editor can be configured via Settings:
      • Manual entry of editor executable path.
      • File browser integration – browse the filesystem to select editor executables.
      • Real-time validation – the executable path is validated to ensure it exists and is executable.
  • During this flow:
    • The server emits editor.open.requested, editor.open.succeeded, or editor.open.failed.
    • The UI surfaces success/failure state so you know whether the editor launch worked.
    • When no editor is configured, the feature is disabled and users see a clear message.

​
Auto-commit and automation

  • Auto-commit is driven by Git listeners reacting to Attempts:
    • On attempt.completed with status succeeded, the listener checks project settings:
      • If autoCommitOnFinish is enabled, it publishes attempt.autocommit.requested with worktree metadata.
    • A second listener handles attempt.autocommit.requested by calling performAutoCommit, which:
      • Builds a commit from the latest Attempt output.
      • Optionally pushes the branch when autoPushOnAutocommit is enabled.
  • This behavior is controlled per project via the Repository defaults settings panel and the underlying core/projects/settings service.

​
Worktrees management

KanbanAI provides a dedicated Worktrees management interface to view, sync, and clean up Git worktrees:
  • Worktrees page (/projects/:projectId/worktrees):
    • Lists all tracked worktrees (created by Attempts) with their status, branch, and disk usage.
    • Shows orphaned worktrees (found on disk but not tracked in the database).
    • Shows stale entries (tracked in the database but missing on disk).
    • Provides a summary of total worktrees, active attempts, and disk usage.
  • Worktree operations:
    • Sync – Discovers new orphaned and stale worktrees by scanning the filesystem and database.
    • Delete tracked worktree – Remove a worktree from disk and/or database, with options to:
      • Force delete even if the associated Attempt is still active.
      • Delete only from disk while keeping the database record.
      • Delete the local and/or remote Git branch.
    • Delete orphaned worktree – Clean up worktrees found on disk but not tracked in the database.
    • Delete stale entry – Remove database records for worktrees that no longer exist on disk.
  • Worktree status:
    • active – Attempt is in progress or completed but not yet cleaned up.
    • orphaned – Worktree exists on disk but is not tracked in the database.
    • stale – Database entry exists but the worktree directory is missing from disk.
    • locked – Worktree is locked by another Git operation.