Help

How to install Pyloxa, connect your agents, run your first plan and fix common problems. Features marked Pro need the trial, the Pro preview or Pro; everything else is in the free version.

For Pyloxa 0.2.0 and later · Last updated: November 21, 2026

Install and update

What you need

Pyloxa doesn’t charge for AI usage: the CLIs use your own subscription or API key.

Download and install

  1. Download Pyloxa-Setup-<version>.exe from the latest release.
  2. Optional: check the file. In PowerShell, run Get-FileHash .\Pyloxa-Setup-<version>.exe -Algorithm SHA256 and compare the result with the SHA-256 in the release notes.
  3. Run the installer. It installs for your Windows user only (no administrator rights), shows the license agreement, lets you choose the folder, and adds Start menu and desktop shortcuts.

“Windows protected your PC”

The installer is not code-signed yet, so Microsoft Defender SmartScreen may stop it with “Windows protected your PC” and “Unknown publisher”. Choose More info, then Run anyway. If you want to be sure the file is the one we published, compare its SHA-256 first (see above). If your antivirus blocks the installer or the app, see Antivirus blocks Pyloxa or a CLI.

Updates

The setup guide

The first time you open Pyloxa, the setup guide walks you through ten steps. Use Next and Back, or Skip the setup guide; you can reopen it any time from Settings → General settings → Reopen the setup guide.

  1. Welcome: how Pyloxa differs from opening several sessions yourself: the brain splits a request into tasks and hands them to agents from different vendors by your rules, Pyloxa runs the tests itself, takeovers when quota runs out wait for your OK, and agents never touch your folder, with merging and pushing left to you. You can also pick the interface language here. If an agent is already ready to take work, this page offers Start the test drive.
  2. Environment check: git (required) and Node.js (optional). If one is missing or too old, copy the winget command shown or open the official download page, then choose Check again.
  3. Install agents: one card per CLI. Install {name} shows the exact command first and then runs the CLI’s official npm package (npm install -g …) at the latest version Pyloxa has verified. This needs Node.js. If a CLI is installed but not found, restart Pyloxa.
  4. Sign-in and keys: whether each CLI is Ready. Sign in in a terminal with the command shown (for example claude auth login or codex login), or use an API key. See Connect your agents. Once at least one agent is ready, Start the test drive also appears at the top.
  5. Choose the brain: the agent that plans the work. See The brain.
  6. Division of work: which agent gets which type of task. You can change this later on the Workflow page.
  7. Work habits: worktree mode, brain review, cross-testing, concise replies, dispatch mode, what to do when no rule matches, how results are accepted, and notifications and updates.
  8. Skills: the skills each CLI can already see. See Skills.
  9. Open a project: choose a git repository with at least one commit, then approve its verification commands.
  10. First task: how a task runs, and the option to try it on a sample project first.

After the guide, a Getting started checklist stays in the window until you close it: connect an agent, choose the brain, open a project, approve verification commands, accept your first result, look at Skills, and merge a result or open a PR. Short tips appear the first time you reach each part of the app; turn them off or show them again in Settings → General settings.

Connect your agents

Go to Settings → Agents and workflow → Agent Connections. Each CLI shows its version, compatibility, sign-in state, how it is billed and whether it is Ready, Can’t dispatch or Out of quota. Choose Re-detect after installing or signing in.

Subscriptions (Claude Code and Codex CLI)

Sign in with the CLI’s own command in a terminal: claude auth login for Claude Code, codex login for Codex CLI. Pyloxa checks sign-in only with the CLI’s own status command and starts the CLI as you would. It never reads, copies or sends your tokens or credential files.

API keys

Gemini CLI (experimental)

Gemini CLI works only with your own paid Gemini API key; Google account sign-in and Google subscriptions are not supported. Pyloxa runs it with its own separate settings folder. It can take tasks such as writing and documentation, but it can’t be the brain or test another agent’s work.

CLI versions

Pyloxa tests each CLI version it supports. The connection card shows one of three states:

When a newer CLI version is out, the card shows it with Update to {version} (the latest version Pyloxa has verified), Copy command and the CLI’s official release notes. If a CLI updated itself, a banner tells you which version you are on now.

Your first plan

Send a request

Open a project and describe what you want in the message box. Under Send to, choose To the brain to have it planned, or Directly to {name} to give one agent a single task without a plan. Type / to insert a prompt template; the free version keeps up to five templates, Pro Pro any number.

The brain

The brain is one of your agents. It answers questions, splits a request into phases and tasks, and can review results. Choose it in Settings → Agents and workflow → Agents & Brain, where you can also set Brain model and Brain reasoning effort; they apply only to the brain, not to the agents doing the tasks. The brain can’t change your settings. Gemini CLI can’t be the brain. A backup brain that takes over when the main one is unavailable is Pro.

Approve the plan

Routing and dispatch modes

Settings → Agents and workflow → Workflow holds the rules. Under Division of work, the assignment table says which agent does each type of task, with fallbacks used only when an agent fails (for example when it runs out of quota). Rule simulation shows where a task would go without calling any agent. Dispatch mode sets how plans start:

How much runs at once

Checks, brain review and cross-testing

An agent saying it is done isn’t enough. Pyloxa checks each result itself.

Verification commands and gates

Brain review

On the Workflow page under Checks, Brain review can be off (default), review tasks without check commands, or review all tasks. The brain reads the result without changing it and accepts it, asks for changes or asks you; its verdict is labelled as an AI judgment. The brain never reviews its own task: a backup brain Pro does it, or the task waits for you.

Cross-testing

Workflows

Settings → Agents and workflow → Workflow shows how work moves through five stages: Planning, Phases, Division of work, Checks and Delivery. Choose a stage to jump to its settings.

Agent Teams Pro

Agent Teams is experimental. It lets the agents in one plan talk to each other: share tasks, report progress, ask questions and send messages, with the brain or you as the lead.

Test drive and the verification card

Try it on a sample project

In the setup guide’s last step, or on the welcome screen when you have no projects yet, choose Start the test drive. If you’re already signed in to an agent, steps 1 (Welcome) and 4 (Sign-in and keys) of the setup guide offer it too. Starting from an early step finishes the setup guide with the defaults: the default brain and division of work, with the Getting started checklist in the sidebar listing what’s left. You can reopen the setup guide from Settings → General settings any time. Pyloxa creates a small sample repository in its data folder with a planted bug and a ready-made plan, so the brain uses no quota. A guide walks you through approving the plan, the agent’s fix, Pyloxa running node --test, a cross-test by a second agent if you have one, accepting the result and the verification card. The preview estimates how much it will use. It needs git and Node.js, and it is free; automatic cross-testing in it needs Pro, otherwise you start the test by hand. Delete the sample folder when you are done.

The verification card

When a plan has finished, Verification card on the plan card summarises every result: ✅ passed the commands Pyloxa ran, ⚠️ no command verification, ❌ a check failed, ⏳ not finished. For each result it shows who built it, the cross-test outcome and tests added, the commands run and how it was accepted. Use Copy Markdown, or when you create a PR, choose to append the card to the description.

Shared memory

Shared memory is one store on your computer that every agent receives as background when it works: rules, preferences, decisions, facts and pitfalls. It is in the free version. Open it in Settings → Agents and workflow → Shared memory.

Skills

Settings → Agents and workflow → Skills shows every skill and which CLIs can see it.

Background running

These are in the free version, in Settings → General settings → Background running.

Usage and quota

The usage meter

When an agent runs out of quota

Scheduling, task center and notifications

Back up and move your settings

Settings → General settings → Backup and transfer, in the free version. There is no cloud sync; you move the file yourself.

Pro account, trial and Pro preview

The free version needs no account. The trial, the Pro preview and Pro need you to sign in; the account is used only for licensing and never sees your projects or code. See the privacy policy for what the account keeps.

Sign in

Pro preview and trial

Two computers

Staying online

When the trial, preview or Pro ends

Pyloxa goes back to the free version. Running tasks finish first, and no data, files or settings are deleted. Pro settings are paused and marked Needs Pro, paused; they come back as soon as you are on Pro again.

Where your data is, and uninstalling

FolderWhat’s in it
%APPDATA%\PyloxaSettings, history and the database (pyloxa.sqlite3), encrypted API keys and license (secrets.json), backups of skills and memory, and test-drive samples
%LOCALAPPDATA%\Pyloxa\worktreesThe git worktrees where agents work
Your repositoriesTask branches named pyloxa/…, and anything you merged

Pyloxa sends nothing from these folders to us. To uninstall, quit Pyloxa from the tray icon first (closing the window may leave it running), then uninstall it from Windows Settings → Apps like any other app. Uninstalling keeps both folders so that a reinstall picks up where you left off. To remove everything:

  1. Delete %APPDATA%\Pyloxa and %LOCALAPPDATA%\Pyloxa.
  2. In each repository you used, run git worktree prune, and delete the pyloxa/… branches you don’t need.
  3. If you used Sync to CLIs, remove Pyloxa’s marked block from AGENTS.md and the CLI memory files. The CLIs themselves, and skills synced to them, stay installed.
  4. If you signed in, delete your account on the account page, or ask us at support@pyloxa.com.

Troubleshooting

Windows warns about the installer

See “Windows protected your PC”.

Antivirus blocks Pyloxa or a CLI

Because the app isn’t code-signed yet, some antivirus programs quarantine the installer, block Pyloxa from starting, or block the CLIs it starts. Signs: the installer disappears, a CLI shows as not installed although it works in your terminal, or a task fails with “Couldn’t start claude” (or codex, gemini).

A CLI shows “Can’t dispatch”

A task stopped with an error

Sign-in or license problems

The folder can’t be opened as a project

Pyloxa needs a git repository with at least one commit. Run git init and make a first commit, then open the folder again.

Report a problem

Free and Pro at a glance

FeatureFreePro
Plans, routing rules, worktrees, verification commands, gates, brain reviewYesYes
Workflow templates and your own plan stagesYesYes
Shared memory, test drive, verification card, background running, usage meter, settings backupYesYes
Projects running at onceOneSeveral, with the Task Center
Tasks at once in a planTwoNo per-plan limit
Dispatch modeSuggest then ask, or follow settings onlyAlso auto within limits
When quota runs outYou confirm each takeoverAutomatic fallback
Cross-testingWhen you askAutomatic, with send-back for a fix
BrainOneUp to three backup brains
Saved workflows, version history and describing a workflow in a sentenceImported workflows are keptYes
Agent Teams (experimental)—Yes
Scheduled plans, project priority and quota sharesWaiting work resumes after the resetYes
Usage report exportUsage per runAcross projects, Markdown or CSV
NotificationsWindows desktopAlso Telegram, Discord, webhook
SkillsList and viewLibrary, sync, per-project assignment
Dispatch packsReads .pyloxa/ in a repositoryImport and export, including your workflows
Prompt templatesUp to fiveAny number

This page is in English and Traditional Chinese. The other languages of this site will follow. Can’t find an answer? Write to support@pyloxa.com.