Usage
Guide

Projects

A project is a reference to a local git repository. The project list lives in the sidebar and gives you quick access to all your repositories.

Creating a Project

Click Add Project in the sidebar, then select the root directory of any git repository. The project name defaults to the folder name but can be changed.

Project Options

Right-click a project in the sidebar to access its options:

• Rename the project.
• Toggle the Web App option to enable per-session subdomains.
• Add startup commands that run when a new session starts.

Web App Toggle

When enabled, each agent session in the project is assigned its own subdomain under the project's .tact domain. Within each session you can start and stop the application using the startup commands you've configured, then access it from that subdomain in your web browser. You also gain access to logs for those commands directly in the session.

Agents

Agents are the AI coding tools that Taskeract orchestrates. Each agent runs in its own isolated environment.

Supported Agents

• Claude Code — Anthropic's CLI coding agent.
• OpenAI Codex CLI — OpenAI's terminal-based coding agent.
• Google Gemini CLI — Google's CLI coding agent.
• OpenCode — Open-source terminal coding agent.

Configuring Agents

Agents are detected automatically during the setup wizard. Taskeract scans your PATH for supported agent binaries and configures any that are found.

Agent Display

Each agent is shown with a configurable color and display letter in the session list. This makes it easy to tell which agent is running at a glance. See Configuration > Agent Display for customization options.

Sessions

A session is a running instance of an agent working inside a project. Each session gets its own git worktree, providing full isolation from your main branch.

Creating a Session

Select a project, then click New Session. Choose an agent and optionally provide an initial prompt. Taskeract creates a git worktree, launches the agent, and begins streaming output.

If the project is not in a git repository, worktree isolation is not available and you will be limited to a single session.

Streaming Output

Agent output is displayed in real time in the message view. You can scroll through the output, copy text, and send follow-up prompts to the agent.

Resuming Sessions

Sessions persist across application restarts. Reopen a session from the session list to see its full history. If the agent supports resumption, Taskeract uses it to continue where you left off. Otherwise, the context is repopulated from the message history.

Permissions

Some agents request permission before performing certain actions (e.g., writing files, running commands). Taskeract surfaces these permission requests in the UI so you can approve or deny them.

Git Integration

Taskeract includes a built-in changes view for reviewing modifications made by agents.

Changes View

The changes view shows all files modified in the session's worktree. Click any changed file to view a side-by-side diff so you can review exactly what the agent modified. The message input is available at the bottom so you can easily copy content from the diff and direct the agent to make adjustments. When you're happy with the changes, ask the agent to commit.

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.

Terminal & Logs

Terminal Access

Each session has a terminal icon that opens a terminal 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 terminal in the project folder.

Logs View

For web app projects, the logs view shows log output for all commands run when the session's state is changed to running. You can navigate the logs using the keyboard and copy items to the message input at the bottom to discuss with the agent.

Log Modes

Toggle between Compact and Verbose log modes. Compact mode shows only agent messages, while verbose mode includes internal tool calls and metadata.

Keyboard Shortcuts

Taskeract supports configurable keyboard shortcuts for common actions. The default modifier key is Cmd on macOS and Ctrl on Linux. Both the shortcuts and the modifier key can be customized in Configuration > Keybindings. Below are the default bindings.

Global Shortcuts

In jump mode, press 1, 2, or 3 to jump to the Chat, Logs, or Changes tabs. Letters A–Z are assigned to sessions so you can quickly swap between them.

Changes View Shortcuts

Mod refers to Cmd on macOS and Ctrl on Linux. The modifier key itself can be changed in Configuration > Keybindings.