Projects
& Setup

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

From the welcome screen, click Clone Repository to browse and clone from a connected account, or click Open Folder to select a local git repository. Open Folder is also available from File > Open Folder in the menu bar. The project name defaults to the folder name.

Project Properties

Click a project in the sidebar to open the Project Properties view. It has five tabs:

• General — rename the project, toggle the Web App option, view detected version managers, and remove the project.
• Worktree — configure and edit startup commands, init commands that run once when a worktree is created, copy patterns for files that should be kept in sync across worktrees, and an inline editor for .env files.
• Git — set the development and production branch names, and choose how session branches are integrated (pull request or direct merge).
• Issues — configure issue tracker integration and define status groups. See Issue Tracking for details.
• Deleted — view and manage soft-deleted sessions. View terminal history, restore them, or permanently remove them. See Deleting Sessions for details.

Changes are saved to .tact/project.yaml and silently synced to the remote via a taskeract/config orphan branch so team members can share project settings. See Config Sync below.

Web App Toggle

When enabled, each agent session in the project is assigned its own subdomain under the project's .tact domain. The subdomain uses the session's branch suffix (e.g., swift-falcon.myproject.tact) for easy identification. 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. Startup commands receive PORT and SESSION_URL (e.g., https://swift-falcon.myproject.tact) as environment variables, which is useful for setting options like NEXTAUTH_URL or allowed origins.

Version Managers

Taskeract automatically detects version managers installed on your system and shows them in Project Properties under Detected Tools. Active tools (those with configuration files in the project) inject their environment into session processes automatically.

Supported version managers: mise, direnv, volta, fnm, nvm (including nvm-windows), asdf, pyenv, and rbenv. When multiple managers are detected, they are merged in priority order so that higher-priority tools take precedence. For tools with trust systems (mise and direnv), Taskeract automatically runs mise trust or direnv allow on each worktree it creates so sessions work without manual setup.

Startup Commands

Startup commands run every time you start a session in the project. Configure them in the Worktree tab of Project Properties. Click any command's name or command text to edit it inline — changes are batched and saved with the Save button.

If a startup command fails to launch or exits with a non-zero code, an error badge appears in the session header showing which command failed. Clicking the badge switches to the Logs tab filtered to that command's output so you can see what went wrong.

Init Commands

Init commands run once when a new git worktree is created for a session. Use them for one-time setup steps like installing dependencies or building assets. Configure them in the Worktree tab of Project Properties.

Commands run in the worktree directory with access to detected version manager environments. They execute in the order defined and have access to the project's environment variables. As with startup commands, you can edit any command inline by clicking its name or command text. If an init command fails, the error is surfaced in the session's Logs tab so you can diagnose the problem.

Copy Patterns & File Sync

Copy patterns specify which files and directories should be kept in sync between your project root and all active session worktrees. This is useful for gitignored files like .env, local configuration, and secrets. Configure them in the Worktree tab.

When a session is created, matching files are copied from the project root into the new worktree. After that, a background file watcher monitors all locations and automatically propagates changes in either direction. If you edit .env in one worktree, the change is synced to the project root and all other worktrees instantly.

Env Editor

Copy patterns that match .env files (like .env, .env.local, or .env.production) get an inline editor in the Worktree tab. Click the chevron next to a pattern to expand it. You can:

• Add, edit, and delete environment variables with a visual key-value editor.
• Paste multi-line env content — Taskeract auto-parses KEY=VALUE lines and merges them into the editor, updating existing keys and appending new ones.
• Save changes to disk, which immediately syncs to all active worktrees.

Comments and blank lines in the original file are preserved on disk even though they are not shown in the editor.

Config Sync

Project configuration is stored in .tact/project.yaml. When you save changes, Taskeract silently commits and pushes the configuration to a taskeract/config orphan branch on the remote. When loading a project, Taskeract checks the remote for newer configuration and applies it automatically. This keeps project settings — startup commands, init commands, copy patterns, and branch configuration — in sync across team members without adding files to your main branch.

Cloning & Browsing Repositories

If you have connected accounts in Settings > Accounts, you can browse and clone repositories directly from within Taskeract. The Clone Repository dialog has two modes:

• Browse Repositories — select an account and browse its repositories. Filter by workspace or organization and search by name. Click a repository to clone it.
• Repository URL — paste any HTTPS or SSH git URL to clone it. Taskeract automatically matches the URL to a connected account if one exists.

Cloned repositories are automatically added as projects. The clone directory is configurable in Settings > Accounts.

Removing a Project

To remove a project, click Remove in the General tab of Project Properties. This removes the project from Taskeract but does not delete any files on disk.

Project Groups

When you have many projects, groups help you organize them. Groups are defined in Settings > Groups and assigned to individual projects via the General tab in Project Properties.

• Creating groups — open Settings > Groups and click Add Group. Click a group name to rename it inline. Delete a group with the trash icon; any projects in that group become ungrouped.
• Assigning projects — in Project Properties > General, use the Group dropdown to assign the project to a group or set it to None.
• Filtering the sidebar — enable Group sidebar by project groups in Settings > Groups. A dropdown replaces the static “Projects” header in the sidebar. Select All Projects to see everything, pick a specific group to filter, or choose Ungrouped to see only projects without a group. You can also switch groups from Jump Mode by pressing ` (backtick).

Accounts

Taskeract integrates with GitHub, GitLab, and Bitbucket for creating pull requests, browsing repositories, and cloning projects. It also connects to Jira, Linear, Trello, and Taiga for issue tracking. Manage all accounts in Settings > Accounts.

Connecting an Account

Click Add Token and provide:

• Label (optional) — a friendly name like “Work” or “Personal” to distinguish multiple accounts on the same host.
• Type — GitHub, GitLab, Bitbucket, Jira, Linear, Trello, or Taiga.
• Hostname — the server address (auto-filled for most types).
• Token — a personal access token or credentials with appropriate permissions.

Token Permissions

• GitHub — fine-grained token with Contents: Read/Write, Metadata: Read, Pull requests: Read/Write, and Issues: Read/Write repository permissions.
• GitLab — personal access token with api, read_repository, and write_repository scopes.
• Bitbucket — API token with Account: Read, Workspace membership: Read, Repositories: Read/Write, and Pull requests: Read/Write.
• Jira — API token from id.atlassian.com. Enter your Atlassian email address and the generated token.
• Linear — API key from linear.app/settings > API > Personal API keys.
• Trello — API key from trello.com/power-ups/admin and a user token generated via the authorization URL.
• Taiga — username and password. The password is exchanged for an auth token on save. Supports self-hosted instances.

Multiple Accounts

You can add multiple tokens for the same service — for example, separate GitHub tokens for work and personal accounts. Use labels to tell them apart. When creating a pull request, Taskeract uses the token associated with the project's remote. For issue tracking, select the account to use in Project Properties.

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.
• 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.

How Agents Run

Taskeract launches each agent's CLI binary directly in a real PTY — claude, codex, or opencode. The agent process runs natively with your existing credentials and configuration, exactly as it would in your own terminal.

Taskeract is an orchestration and UX layer — it never intercepts, proxies, or modifies API traffic between the agent and its provider. Your existing subscriptions (Claude Max, Codex Pro, etc.) work as-is with no terms-of-service concerns.