Git
Workflows

Git Integration

Taskeract has a comprehensive built-in git workflow. Review changes, push branches, create pull requests, rebase, and merge — all without leaving the app.

Changes View

The Changes tab shows all files modified in the session's worktree as a file tree with color-coded status indicators. Select any file to view a syntax-highlighted diff with line numbers. Use vim-style keyboard navigation (j/k, gg/G, %) to browse changes, v for visual selection mode, and y or Space to copy selected lines to the clipboard.

Push & Integration

Push the session's branch directly from within Taskeract. When you're ready to integrate, two modes are available:

• Pull Request (default) — create pull requests on GitHub, GitLab, or Bitbucket against the base branch without switching to a browser. Once a PR exists, Taskeract displays a badge linking to it and automatically refreshes its status in the background.
• Merge & Push — merge the session branch directly into the base branch and push to the remote. The session branch is cleaned up automatically. This is useful for teams that prefer a simpler workflow without pull requests.

The integration mode is configured per-project in the Git tab of Project Properties.

Local Repositories Without a Remote

For repositories that don't have a remote origin, the Push button is hidden and the integration action becomes Merge to <branch>, which merges the session branch into the base branch locally without attempting to push. Rebase and merge-from-base actions also work against the local base branch. This makes Taskeract fully usable with local-only repositories.

Agent-Assisted PRs & Merges

When you ask your agent to "create a PR" or "merge this work," it opens the dialog with the title and description already filled in based on the work it did. This happens automatically — no setup required. The agent has the best context about what changed and why, so the pre-filled content is typically more descriptive than what you'd write by hand.

If you open the PR dialog yourself instead, an Auto-fill from commits button generates a title and description from your branch's commit history. For a single commit, the commit message becomes the title; for multiple commits, the session title is used with a bulleted list of commit messages as the description.

Base Branch

Each session has a base branch that determines where changes are measured from and where pull requests target. It defaults to the project's configured development branch (or auto-detected from remote or local branches: develop, dev, main, master in priority order). Click the base branch indicator to open a branch picker showing all remote branches and any local-only branches. Selecting a different base fetches the latest remote refs (when available) and resets the session branch to the new base. This is only allowed before any commits have been made on the session branch.

Rebase & Merge

Keep session branches up to date with the base branch using the built-in rebase or merge actions. When commits from the base branch are available, a badge shows how many commits behind the session is, with options to rebase or merge.

Background Sync

Taskeract periodically fetches from the remote in the background (when one exists) so your git status and PR information stay current. When a fetch completes, the changes view refreshes automatically. If your machine goes offline, background sync pauses automatically to save battery and an Offline indicator appears at the bottom of the sidebar. Sync resumes when connectivity returns.

Worktree Isolation

Each session operates in its own git worktree, which is a lightweight checkout of your repository. This means multiple agents can work on the same project simultaneously without interfering with each other or your working directory. Branches can be renamed directly from the session header.

PR Review

Review pull requests from GitHub, GitLab, and Bitbucket without leaving the app. Leave inline comments, track feedback as a checklist, and approve or request changes.

Pull Requests in the Sidebar

Projects using the Pull Request integration mode show a Pull Requests section in the sidebar when there are open PRs. Click any PR to open it in the review view. PRs that already have a session are shown under their session instead.

Starting a Session from a PR

Hover over a PR in the sidebar and click + to start a session on that PR's branch. Pick an agent and Taskeract creates the session with the branch already checked out. The PR moves from the pull request list into the session list, and a Review tab appears in the session alongside the terminal, logs, changes, and history tabs.

Review Tab

The Review tab gives you the full review experience inside a session — file list, diff, and checklist side by side. You can leave comments, track threads, and work with your agent without switching windows.

Thread Bar

While working in the terminal or other tabs, click the comment icon in the session header to open the thread bar. It shows all review threads in a side panel so you can keep an eye on feedback without leaving what you're doing. When the thread bar is open on the terminal tab, each comment has a Paste to agent button that sends the comment text straight into the terminal.

Layout

The review view has three resizable panes:

• File List (left) — changed files with status icons and line counts. Click a file to view its diff.
• Diff Viewer (center) — the selected file's diff with syntax highlighting. A collapsible description panel sits above the diff; press d to toggle it and drag the divider to resize it. Hover over a line and click + to add a comment. Comment threads appear inline below the lines they reference.
• Review Checklist (right) — all comment threads as a to-do list grouped by file, with a progress bar and filter tabs. Click an item to jump to it in the diff.

Drag the dividers between panes to resize them. Positions are saved automatically.

Inline Comments

Hover over any line in the diff and click the + icon to write an inline comment. Press Ctrl+Enter to post or Escape to cancel. The comment appears immediately below that line.

Thread Workflow

Each comment thread has three states:

• Open — feedback has been left and needs the developer's attention.
• Ready for Review — the developer has addressed the feedback and is waiting for the reviewer to verify.
• Completed — the reviewer has signed off. The thread is resolved on GitHub/GitLab/Bitbucket and collapses in the diff.

A thread is only resolved on the provider when the reviewer signs off, so feedback is never dismissed prematurely.

Actions

What you can do depends on whether you're the PR author or a reviewer:

• Reply — add a follow-up comment to any thread.
• Mark Ready (PR author) — signal that you've addressed the feedback.
• Sign Off (reviewer) — approve the change and resolve the thread.
• Reject (reviewer) — reopen a "Ready" thread with a comment about what still needs work.
• Resolve (reviewer) — resolve an open thread directly.

Approving a PR

The header shows the PR number, title, branches, diff stats, reviewers, and CI status. Two buttons let you submit a formal review:

• Approve — submit an approving review.
• Request Changes — write a summary and submit a "changes requested" review.

An Open in Browser link is available if you need to visit the PR on GitHub, GitLab, or Bitbucket directly.

Staying Up to Date

Taskeract automatically refreshes threads, PR details, and CI status while the review view is open. A manual Refresh button is also available in the header.

Agent Access to Review Threads

When a session is connected to a pull request, your agent can read and interact with review threads directly. Ask your agent to “check the review feedback” or “address the review comments” and it will see every thread — status, file locations, diff context, and the full conversation — so it can work through the feedback without you having to copy and paste anything.

Agents can also create new inline comments on specific lines, reply to existing threads, and resolve threads when feedback has been addressed. For example, you can ask your agent to “add a review comment on line 42 of src/main.rs” or “resolve the thread about the naming convention.” All changes are reflected on your forge (GitHub, GitLab, or Bitbucket) and in Taskeract’s Review tab.

Issue Tracking

Taskeract integrates with popular issue trackers so you can browse issues, start sessions linked to tickets, and give your agents direct access to issue details.

Supported Trackers

• GitHub Issues — uses your existing GitHub account token.
• GitLab Issues — uses your existing GitLab account token.
• Jira — requires an Atlassian API token (from id.atlassian.com).
• Linear — requires an API key (from linear.app/settings).
• Trello — requires an API key and user token (from trello.com/power-ups/admin).
• Taiga — requires a username and password (exchanged for an auth token on save).

Enabling Issue Tracking

Open Project Properties > Issues. Select your tracker type and provide any project-specific configuration (e.g. Jira project key, Linear team key, Trello board ID, or Taiga project ID). For GitHub and GitLab, the tracker uses your existing forge token automatically. For external trackers (Jira, Linear, Trello, Taiga), add your credentials in Settings > Accounts first, then select which account to use from the Account dropdown. If you have only one matching account, it is selected automatically.

Browsing Issues

With issue tracking enabled, an Issues view is available. Click a project name in the sidebar or use Jump Mode (;) to open it.

The header shows a row of status filter pills. For trackers with rich workflow statuses — Jira, Linear, Trello, and Taiga — the pills reflect the platform's actual statuses (e.g., "To Do", "In Progress", "In Review", "Done"). For GitHub and GitLab, the pills show Open and Closed. Click a pill to filter issues to that status. A Mine toggle filters the list to only issues assigned to you.

Status Groups

Trackers like Jira can have many workflow statuses, making the pill bar unwieldy. Status groups let you define named subsets of statuses so you can quickly switch between different views — for example, a "Dev" group with just the statuses you care about and a "QA" group with testing statuses.

Define status groups in Project Properties > Issues. When at least one group is defined, a group selector appears before the status pills in the Issues view. Click it to switch groups or select All to see every status. Each group can contain up to 9 statuses (matching the jump dialog's 1–9 keys). Your selected group is remembered per project. If you haven't chosen one yet, the group marked as default is used.

Status groups are stored in .tact/project.yaml and synced to team members via the config orphan branch.

The view shows issues with their ID, title, labels, assignees, and status. The active status pill shows how many issues are loaded, with a + suffix when more pages are available. Each issue includes a body preview and comment count so you can scan what issues are about and how active they are without opening them. Use the sort dropdown to order by updated or created date. The list loads more issues automatically as you scroll. Click any issue to see its full description and comments in a resizable detail panel. Use j/k to navigate (with numeric prefix, e.g. 5j), gg/G to jump to the first/last issue, Enter to select, Escape to close, / to filter, and s to start or go to a session. The search field includes a clear button when text is entered.

Starting a Session from an Issue

Hover over any issue to reveal an action button next to the issue ID. If no session exists, a + button starts a new session linked to that issue. The session's branch is automatically named after the issue (e.g. feature/42 or feature/PROJ-123), and the issue is auto-assigned to you on the tracker. If a session already exists, an external-link icon appears instead, letting you jump directly to that session. You can also press s on a focused issue to start or go to a session without using the mouse.

Linking an Existing Session to an Issue

You don't have to start a session from the Issues view to connect it to a ticket. When issue tracking is configured for a project, every session without an issue shows a dimmed ticket icon in the header. Click it to pick an open issue from your tracker and link it to the session. Once linked, the session behaves the same as one created from an issue — the sidebar toggle and agent access to issue details are both available.

Issue Sidebar in Sessions

When a session is linked to an issue, the ticket icon in the session header lights up. Click it to toggle an issue detail sidebar alongside your work. The sidebar shows the issue title, state, labels, description, and comments. Drag the sidebar edge to resize it — your preferred width is saved automatically. A Paste to agent button on each comment lets you send content directly to the terminal.

Agent Access to Issue Details

When a session is connected to an issue, your agent can read the issue details directly. Ask your agent to “check the issue” or “look at the ticket” and it will see the issue description, labels, and comments so it can understand the requirements without you having to copy and paste anything.