Windows & WSL Installation

Step-by-step guide for installing and configuring aitasks on Windows via the Windows Subsystem for Linux (WSL).

Prerequisites

• Windows 10 version 2004+ or Windows 11
• Administrator access (for WSL installation)

Install WSL

aitasks runs inside WSL (Windows Subsystem for Linux). If you don’t have WSL installed:

1. Open PowerShell as Administrator
2. Run:

   wsl --install
   

3. Restart your computer when prompted
4. On first launch, create a Unix username and password

For detailed instructions, see the official WSL installation guide.

Important: All subsequent commands in this guide should be run from within the WSL shell (not PowerShell or CMD).

To open a WSL shell: search for “WSL” in the Windows search box, or type wsl in PowerShell.

Install aitasks

The simplest install — works on any WSL distro (Ubuntu, Debian, and others):

cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/beyondeye/aitasks/main/install.sh | bash
ait setup

ait setup automatically detects WSL and installs dependencies via apt. It also installs a modern Python (3.11) user-scoped via uv into ~/.aitask/python/ if your system Python is too old.

If you already have the global ait shim installed (from a previous project), you can skip the curl step and just run ait setup in the new project directory.

After setup completes, see Authentication with Your Git Remote to configure GitHub access for task locking, sync, and issue integration.

Alternative: native .deb package

If you prefer your distro’s package manager (Ubuntu 22.04+ / Debian 12+), install the official .deb. See the Linux guide — .deb section for the full walkthrough; the short version (with GitHub CLI installed):

gh release download --repo beyondeye/aitasks --pattern '*.deb'
sudo apt install ./aitasks_*.deb
ait setup

Upgrade

Framework upgrades are per-project. Inside any project that already has aitasks set up, run:

ait upgrade latest

Install Coding Agents

All supported coding agents must be installed from within WSL to work with aitasks. Each agent’s Linux install path applies; install whichever ones you plan to use.

Most of these agents require Node.js, so install it first (skip if already present):

# Install Node.js (required by Claude Code, Codex CLI, OpenCode, and other Node-based agents)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Then install one or more agents:

# Claude Code — see https://docs.anthropic.com/en/docs/claude-code/overview
npm install -g @anthropic-ai/claude-code

# Codex CLI — see https://github.com/openai/codex
npm install -g @openai/codex

# OpenCode — see https://opencode.ai
npm install -g opencode-ai

Run ait setup in your project after installing — it auto-detects which agents are present and configures only the ones it finds.

Terminal Options

VS Code with WSL Extension

If you prefer an IDE-based workflow:

1. Install the WSL extension in VS Code
2. Open VS Code and connect to WSL (click the green icon in the bottom-left corner, or run code . from your WSL shell)
3. Use VS Code’s integrated terminal for running ait commands and Claude Code

Default WSL Terminal

The default WSL terminal (Windows Terminal) supports tabs and is fully functional for all aitasks features including ait board.

Known Issues

• Legacy console: The old Windows Console Host (conhost.exe) has limited TUI support. Use Windows Terminal or VS Code’s integrated terminal instead.

Next: Terminal Setup