Tools
& Features

Git History Viewer

Taskeract includes a full git history viewer for browsing your repository's commit graph. Open it from Jump Mode (Mod+G then \) or from the session context. Pressing \ again returns you to the session you were working in (or the welcome page if none was active).

Commit Graph

The left panel shows a visual commit graph with branch and merge lines, author info, timestamps, and commit messages. Navigate with j/k, search with /, and select a commit to view its details.

Commit Detail

The right panel shows the selected commit's metadata in a compact header — the first line of the commit message, hash, and timestamp. Press z or click the chevron to expand the full message, author, and parent links. Below the header are two tabs:

• Changes — lists all files modified in the selected commit with color-coded status indicators (added, modified, deleted, renamed). Select a file to view its syntax-highlighted diff. Navigate diff hunks with ,/..
• File Tree — browse the repository's complete file tree at the selected commit. Expand directories, select files to view their full content with syntax highlighting.

Keyboard Navigation

Both tabs support full vim-style keyboard navigation:

• j/k to move the cursor (prefix with count, e.g. 5j).
• gg/G to jump to the first/last row.
• % to jump to the matching bracket (in code/diff views).
• v to enter visual selection mode.
• y or Space to copy selected lines to the clipboard.
• Tab to switch between the file list and content viewer.
• h to go back to the file list.
• ,/. to jump between diff hunks (Changes tab).
• h/l to switch between Changes and File Tree tabs.
• Enter to toggle blame view for the selected file.
• Backspace to toggle file history for the selected file.
• z to toggle the commit message between a single-line summary and the full expanded view.

Blame View

Press Enter on any file to open a line-by-line blame view showing which commit last modified each line, along with the author and date. Adjacent hunks from different commits are color-coded with alternating intensity for easy visual separation.

The blame view has its own vim-style keyboard navigation that operates on the code side only (blame annotations are not included in selections or copies):

• j/k to move the cursor through lines (prefix with count, e.g. 5j).
• gg/G to jump to the first/last line.
• % to jump to the matching bracket.
• v to enter visual selection mode.
• y or Space to copy selected code lines to the clipboard.
• Click a commit hash to navigate to that commit in the graph.
• Enter or Esc to close the blame view and return to the file list.

File Tree

The File Tree tab shows the full repository tree at the selected commit. Dot-prefixed directories (e.g. .github, .vscode) are collapsed by default. Press Backspace on a file to view its commit history in the graph.

Resizable Panels

Both the graph/detail split and the file list/content split can be resized by dragging. Positions are persisted in your config.yaml and restored on next launch.

Terminal & Logs

Embedded Agent Terminals

Agent sessions run inside embedded terminal emulators with full PTY support. This means you get the same experience as running agents in your regular terminal — colors, cursor movement, TUI rendering, and interactive prompts all work as expected. Scrollback is preserved per session and restored instantly when switching between tabs.

History Tab

Terminal sessions have a History tab that captures every line of terminal output as ANSI-stripped, timestamped text. Unlike the live terminal view, the History tab preserves content that would otherwise be lost to screen clears, progress bar overwrites, and TUI redraws. History is persisted to disk, so it survives application restarts and is available even after a session's PTY has been killed.

The History tab supports the same vim-style keybindings as the Changes and Logs views: j/k to navigate, v for visual selection, and y or Space to yank selected lines to the clipboard.

Shell Access

Each session has a terminal icon that opens a shell in the session's worktree (or the project path if it's not a git repository). There's also a terminal icon on the project itself to open a shell in the project folder.

Logs View

For projects with startup commands configured, the Logs tab shows their output. Logs can be viewed per command (separate tabs) or combined into a single stream. You can navigate the logs using the keyboard and copy items to the clipboard.

When a command fails to start or exits unexpectedly, the failure appears as a highlighted line in the logs. An error badge also appears in the session header — clicking it jumps straight to the failed command's output. Clearing the logs dismisses the badge.

System Tray

Taskeract places an icon in your system tray so you can monitor session status at a glance, even when the app is in the background.

Status Dots

The tray icon shows a colored dot overlay when sessions need attention:

• Yellow dot — a session is waiting for a permission response.
• Green dot — a session has completed its task.
• No dot — all sessions are either idle or actively working.

If both conditions exist simultaneously, the yellow (permission) dot takes priority.

Tray Interaction

Left-click the tray icon to bring the Taskeract window to focus. Right-click to access the context menu with Show Taskeract and Quit. On Linux with AppIndicator, left-click may show the context menu instead — use the Show Taskeract menu item as a fallback.

Close to Tray

When the Close to tray option is enabled in Settings > Appearance, closing the window hides Taskeract to the system tray instead of quitting. The app continues running in the background and can be reopened by clicking the tray icon. Use Quit from the tray menu to exit completely.

When Web Remote is active, close-to-tray is enabled automatically so that closing the window doesn't disconnect remote clients.

Tray Options

The tray icon style (color, black, or white) and whether the tray icon is shown at all can be configured in Settings > Appearance.

Web Remote

Web Remote lets you access Taskeract from another device on your local network using a web browser. Monitor sessions, review changes, and interact with your agents from a tablet or second computer without installing anything.

Getting Started

Open Settings > Remote and toggle Web Remote Access on. Taskeract generates login credentials automatically and starts a local server. The settings panel shows the URL, username, and password — open the URL in a browser on any device connected to the same network and sign in.

Credentials

A username and password are generated for you the first time you enable Web Remote. You can change them in the Remote settings at any time. Toggle Web Remote off and back on for new credentials to take effect.

One Device at a Time

Only one browser can be connected at a time. If you open the Web Remote on a new device, the previous device is disconnected automatically. This makes it easy to switch between devices — just open the URL wherever you are.

Background Behavior

While Web Remote is active, Taskeract keeps running in the background when you close the window. The system tray icon stays active so you can reopen the window at any time. These overrides apply automatically and your saved preferences are restored when you turn off Web Remote.

Requirements

The port is configurable in the Remote settings (default: 9800). Both devices must be on the same local network.

Notifications

Taskeract can send desktop notifications when agents need attention or finish working. This is useful when you're multitasking and don't have the app in the foreground.

Notification Events

Notifications are triggered by the same state changes that drive the system tray status dots:

• Permission needed — an agent is waiting for you to approve or deny a tool call, file write, or command execution.
• Task completed — an agent has finished its work and the session is ready for your review.

Notifications include the session title so you know which session needs attention. If you're already viewing the session that triggered the event, no notification is sent.

Configuration

Notifications are enabled by default. You can toggle them in Settings > Privacy, where there is a master toggle and individual toggles for each event type. See the Notifications section in the Configuration guide for the config.yaml reference.

Themes

Taskeract supports VS Code-compatible color themes, giving you access to thousands of community-created themes. Themes control the colors of the entire application — backgrounds, borders, text, syntax highlighting, the terminal, and semantic UI elements like success/error indicators.

Built-in Themes

Taskeract ships with two built-in themes:

• Taskeract Dark — the default dark theme with cyan accents, designed for extended coding sessions.
• Taskeract Light — a clean light theme for bright environments.

Theme Picker

Open Settings (from the application menu or Mod+,) and navigate to the Theme tab. You'll see built-in themes and any installed themes grouped by extension, each with color swatches showing background, accent, and semantic colors. Click any theme to apply it immediately. The active theme is highlighted with a badge.

Theme Browser

The Theme Browser is a full-screen view for discovering and installing themes from the Open VSX registry — a vendor-neutral marketplace for VS Code extensions.

From the Theme tab in Settings, click "Browse and install themes from the registry". This closes Settings and opens the Theme Browser in the main content area. You can also open it from Taskeract menu > Theme Browser (macOS) or the application menu on other platforms.

Type in the search bar to find themes by name, publisher, or description. Click any result to see its full detail — extension icon, publisher info, version, download count, rating, license, repository link, and the full README with screenshots. After installation, the detail panel lists the extension's theme variants with individual Apply buttons.

Installing & Uninstalling

Select an extension in the Theme Browser and click Install. Taskeract downloads the VSIX package, extracts the theme files, and saves them locally. To remove an extension, click Uninstall in either the Theme Browser or the Theme Picker in Settings. If the active theme belongs to the extension being removed, Taskeract reverts to the default dark theme.

Feedback & Privacy

Send Feedback

To send feedback, open the Help menu (macOS) or the Taskeract menu (Windows/Linux) and select Send Feedback. This opens a quick survey where you can share suggestions, report issues, or tell us what you think. Responses are associated with your account so we can follow up if needed. The feedback option works regardless of your telemetry preference.

You can also submit feedback from the web. Sign in to your account and look for the Send feedback link on your dashboard. Choose a category (bug report, feature request, or general feedback) and describe the issue. All submissions are reviewed by the development team.

Privacy Settings

Open Settings > Privacy to control what data Taskeract shares:

• Send usage data — when enabled (the default), Taskeract sends usage events like session creation and error reports to help improve the product. No code, prompts, or file paths are ever collected. Turn this off to stop sending usage analytics. App open/close and feedback events are always sent.
• Diagnostic mode — records your UI interactions in depth for diagnostic review. This should remain off unless Taskeract support asks you to enable it to help diagnose a specific problem. In preview and beta builds, diagnostic mode is always on and the toggle is disabled.

Both settings persist in your config.yaml and take effect immediately.

Updates

Windows & macOS (DMG)

Taskeract checks for updates automatically. When a new version is available, a notification appears in the bottom-right corner of the app. Click Update to download and install it — Taskeract restarts automatically when the installation is complete.

macOS (Homebrew)

If you installed via Homebrew, updates are managed through Homebrew instead. The in-app notification does not appear for Homebrew installations.

brew upgrade taskeract

Linux

On Linux, updates are handled by your package manager. There is no in-app updater. If you installed via APT or DNF and haven't set up the Taskeract repository yet, follow the installation instructions first.

# Debian / Ubuntu
sudo apt update && sudo apt upgrade taskeract

# Fedora / RHEL
sudo dnf upgrade taskeract

# Arch Linux (AUR)
yay -Syu taskeract-bin