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

Every project in Taskeract is backed by a remote repository on GitHub, GitLab, or Bitbucket. You must connect at least one account in Settings > Accounts before you can add projects — the Clone, Import, and Create buttons are disabled until an account is connected. There are three ways to add a project:

• Clone Repository — browse and clone an existing repository from a connected account.
• Import Folder — select a local folder and walk through the import wizard. If the folder already has a remote matching a connected account, it is imported directly. Otherwise, the wizard creates a new repository on your hosting provider and pushes the code. Available from File > Import Folder (Ctrl+O / Cmd+O).
• Create New — create a fresh repository from scratch. Taskeract creates the repo on your hosting provider, initializes a local clone, and registers the project.

Both the import and create wizards let you choose an account, workspace, repository name, visibility, branch strategy (single or dev + prod), and optional startup/init commands.

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 are stored in the app and synced to all worktrees automatically, and an inline editor for .env files. Non-env files can be imported and exported via file picker.
• Git — set the development and production branch names, choose how session branches are integrated (pull request or direct merge), and configure version file detection and tag prefix for release promotions. See Branch Promotion for details.
• 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 should be stored in the app and synced to all active session worktrees. This is useful for gitignored files like .env, local configuration, and secrets. Configure them in the Worktree tab.

File contents are stored inside Taskeract (not on the project root). When a session is created, matching files are written into the new worktree from the app's database. After that, a background file watcher monitors all worktrees and automatically propagates changes — if you edit .env in one worktree, the change is saved to the app and synced to all other worktrees instantly.

For non-env files, use the Import button to load a file from disk and Export to save it back out. Each pattern row shows the file size and when it was last updated.

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, which immediately syncs to all active worktrees.

Comments and blank lines in the original file are preserved 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. You can choose to remove just the project reference or also delete the project files from 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, Issues: Read/Write, and Workflows: Read/Write repository permissions. The Workflows permission is needed to push changes to GitHub Actions workflow files. If your repository doesn't use GitHub Actions, you can skip it. To create repositories from within Taskeract, also add Administration: Read/Write. For classic tokens, enable the repo and workflow scopes.
• 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. To create repositories from within Taskeract, also enable Repositories: Admin.
• 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.