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 six 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), configure workflow-aware branch strategies, reset built-in strategies back to Taskeract's shipped defaults, and manage version file detection and tag prefix for release promotions. When Merge & Push is selected, PR-only strategies are hidden. See Branch Promotion for details.
• Issues — configure issue tracker integration and define status groups. See Issue Tracking for details.
• Skills — search, install, and manage skills.sh agent skills for this project. See Agent Skills below.
• 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. On Team plans, configuration syncs to the remote so all team members share the same 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 inject their environment into sessions automatically.

Supported version managers: mise, direnv, volta, fnm, nvm (including nvm-windows), asdf, pyenv, and rbenv. When multiple managers are detected, they are merged automatically. For tools with trust systems (mise and direnv), Taskeract handles trust configuration on each worktree 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, an error badge appears in the session header — clicking it opens the Logs tab, and Shift-clicking it re-runs all init commands so you can fix the issue and retry without recreating the session.

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.

When a session is created, matching files are synced to the new worktree. Changes propagate across all worktrees automatically — edit .env in one worktree and it syncs to all others 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. On Team plans, saving changes syncs the configuration to the remote so all team members share the same project settings — startup commands, init commands, copy patterns, and branch configuration — without adding files to your main branch. When loading a project, Taskeract checks the remote for newer configuration and applies it automatically.

On Individual plans, project configuration is stored locally. Upgrade to a Team plan to share settings across your team.

Agent Skills

Taskeract integrates with skills.sh by Vercel, a registry of reusable agent skills that extend what your coding agents can do. Skills are managed through the npx skills CLI — Taskeract provides a graphical interface that wraps the CLI for you.

Requirements: Node.js must be installed. The Skills tab checks for npx on load and shows a message if it is not found. Version managers (fnm, nvm, mise) are detected automatically.

Project Skills

Open Project Properties > Skills to manage skills for a specific project:

• Browse & Install — type a search query to find skills from the skills.sh registry. Each result shows the skill name, source repository, and install count. Click Install, choose which agent types to install for (Claude Code, Codex, OpenCode), and confirm.
• Installed Skills — shows the output of npx skills list for the project. Use Refresh to reload, Check Updates to see if newer versions are available, and Update All to upgrade everything.
• Remove — enter the skill name, select the agent type, and click Remove to uninstall a skill.

Global Skills

Open Settings > Skills to manage skills that apply across all projects. The interface is the same as project skills but operates with the --global flag.

Skills Telemetry

The skills.sh CLI sends anonymous usage data by default. You can disable this in Settings > Skills using the Skills Telemetry toggle. When disabled, Taskeract passes DISABLE_TELEMETRY=1 to all skills CLI commands.

Worktree Auto-Install

When a new session creates a git worktree, Taskeract checks for a skills-lock.json file. If present, it automatically runs npx skills install and npx skills update in the background to restore the project's skills. This happens alongside init commands and does not block the session from starting.

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 lets you select an account and browse its repositories. Filter by workspace or organization and search by name. Click a repository to clone it.

Cloned repositories are automatically added as projects. The clone directory is configurable in Settings > Accounts. If you start cloning the wrong repository, click Cancel to stop the download and clean up.

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.