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
- Windows 10 or 11, 64-bit.
- Git for Windows 2.30 or later.
- At least one agent CLI: Claude Code or Codex CLI signed in with your own subscription, or an API key. Gemini CLI is experimental and needs your own Gemini API key.
- Node.js 22 or later, only if you want the setup guide to install the CLIs for you.
- GitHub CLI (
gh), optional, for opening pull requests.
Pyloxa doesn’t charge for AI usage: the CLIs use your own subscription or API key.
Download and install
- Download
Pyloxa-Setup-<version>.exefrom the latest release. - Optional: check the file. In PowerShell, run
Get-FileHash .\Pyloxa-Setup-<version>.exe -Algorithm SHA256and compare the result with the SHA-256 in the release notes. - 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
- Pyloxa checks GitHub for a new version at startup and every 12 hours, and shows a banner with View and download, See what’s new and Skip this version. Turn it off in Settings → General settings → Notifications & updates → Tell me when a new version is out.
- Pyloxa doesn’t update itself yet. To update, download the new installer and run it over the old version. Your projects, settings and history are kept.
- The same check downloads the list of CLI versions Pyloxa has verified (see CLI versions). Turning the check off stops that too.
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.
- 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.
- Environment check: git (required) and Node.js (optional). If one is missing or too old, copy the
wingetcommand shown or open the official download page, then choose Check again. - 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. - Sign-in and keys: whether each CLI is Ready. Sign in in a terminal with the command shown (for example
claude auth loginorcodex 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. - Choose the brain: the agent that plans the work. See The brain.
- Division of work: which agent gets which type of task. You can change this later on the Workflow page.
- 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.
- Skills: the skills each CLI can already see. See Skills.
- Open a project: choose a git repository with at least one commit, then approve its verification commands.
- 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
- Choose Use an API key… on a CLI’s card and paste the key: an Anthropic Console key for Claude Code, an OpenAI Platform key for Codex CLI, or a Google AI Studio key for Gemini CLI. Pyloxa asks you to confirm before switching billing.
- The key is encrypted with Windows’ own secure storage and only its last four characters are shown. Switch back to subscription returns to the CLI’s own sign-in.
- API keys are billed by your provider per use; Pyloxa doesn’t add any charge.
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:
- Verified version: tested with Pyloxa.
- Same series as a verified version: same major and minor version as a tested one.
- Unverified version (supervised mode only): it still runs, but Auto within limits won’t use it.
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
- The plan card lists the phases and tasks and which agent gets each one. Choose Approve and start, Ask the brain to revise, or reply to the brain.
- Once you approve a plan with more than one phase, Phase progress appears above the plan card: each phase’s status (passed, running, waiting for your approval, needs you, cancelled or not started) and which phase the plan is on. Click a phase to jump to it.
- Each task runs in its own git worktree, away from the folder you are editing. Pyloxa never stashes, resets or checks out your working folder. You can switch the plan to One shared worktree for the whole plan, where tasks run one after another and see earlier changes.
- When a task finishes, its checks run (see Checks). Choose Accept result, Retry, Reassign to another agent or Abandon this result, or open the session to see what the agent did.
- When the plan has finished, choose Merge into current branch or Create branch and open PR. Nothing is merged or pushed until you choose.
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:
- Suggest, then ask (default): the brain proposes, you approve the plan.
- Follow settings only: starts right away when every task matches a rule; you still confirm each finished task.
- Auto within limits Pro: the brain chooses among the agents your rules allow and starts without asking, pausing at any limit. Only verified CLI versions are used.
How much runs at once
- Free: up to two tasks at a time in a plan, and one project with work running at a time. A plan for a second project waits in a queue (Approve and queue), or you can choose Do this project first.
- Pro: several projects at once, and no per-plan limit beyond each connection’s own limit.
- Every version: at most two tasks at a time per CLI connection, and one at a time for Claude Code on a subscription.
Checks, brain review and cross-testing
An agent saying it is done isn’t enough. Pyloxa checks each result itself.
Verification commands and gates
- Approve your project’s commands (tests, build, lint) in Settings → Agents and workflow → Verification commands. Pyloxa runs them after each task, along with a check that the changed files are within the plan’s write scope.
- A result is accepted automatically only when at least one check exists, everything passes and no human review is required. When a check fails, the same agent is asked to fix it. Each task gets at most three automatic runs, counting retries, fixes and fallbacks.
- Each phase ends with a gate: its commands run on the combined result. A phase with no gate commands waits for Approve this phase.
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
- Free: on a finished task, choose Have another agent test it. The tester works in its own worktree and may only add tests. Pyloxa re-runs the commands itself, and the command result decides. If a test fails, choose Send back to “{name}” to fix.
- Pro: automatic cross-testing by task type or by the brain’s judgment, a tester per routing rule, per-task choices in the plan, and failed tests sent back for a fix automatically.
- Gemini CLI can’t be a tester.
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.
- Start from a template: Balanced (default), Quick fix, Spec first, Thorough review, or Share the quota. Each shows what will change before it applies, and Undo last template takes it back. In the free version, the Pro parts of a template (auto mode, automatic cross-testing, automatic fallback) are skipped, and the preview says so.
- Plan stages: let the brain decide the stages for each request (default), or Use my stages: up to five, each with a name, who does it, a note for the brain, whether to wait for your approval, and whether it can be skipped.
- My workflows Pro: Save as my workflow keeps the current settings under a name (up to 20). Choose a saved workflow for each project. Without Pro, projects use the global settings and the saved workflows are kept.
- Version history Pro: every save that changes a workflow keeps a version, up to 10 per workflow, dropping the oldest first. Pick two versions to Compare, or Restore this version: the contents are replaced with that version and the name stays the same. Restoring also keeps a version of what you had, and projects using the workflow update with it. Version history stays on this computer and doesn’t travel with exported settings or dispatch packs.
- Describe it Pro: write the workflow you want in a sentence and choose Draft it. The brain reads the project without changing it and proposes settings with its notes and a list of changes, usually within a minute or two. Then apply it globally (it can be undone), save it as one of your workflows, or edit the description and try again.
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.
- Turn it on in Workflow → Phases → Agent Teams (experimental). It is off by default. The setting is fixed into a plan when you approve it.
- With it on, the message box offers a Team approach: let the brain decide, Feature squad (agree on interfaces, then build front end and back end together), Review board (review from several angles, then merge the reports) or Hypothesis debate (investigate causes separately, then fix).
- A member that asks a question waits for your reply in the Team panel (Reply and continue). By default the brain handles members’ questions first, up to eight times per plan.
- Messages are limited per member and per plan, and members can’t start their own sub-agents. With only a Claude subscription, tasks still run one at a time.
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.
- Add memory, search, Pin: always include, archive or delete items. Each item is up to 500 characters, and anything that looks like a secret is rejected. About 3,000 characters are included per task.
- Agents and the brain can propose new items while they work. Proposals wait under Pending for you to accept, edit or discard; you can let a project accept facts and pitfalls automatically. Remember under a reply or result saves it yourself.
- Import from the memory files each CLI already uses, such as
CLAUDE.md,AGENTS.mdandGEMINI.md. Pyloxa only reads them. - Sync to CLIs writes your project rules into a marked block in
AGENTS.md(and links it fromCLAUDE.md) after showing you the changes. Pyloxa never commits them. - Export as Markdown or JSON, and import from a file.
Skills
Settings → Agents and workflow → Skills shows every skill and which CLIs can see it.
- Free: list and view skills, Scan again, and add up to ten folders to scan.
- Pro: one skills library for every CLI: New skill, Sync from Skills library, Fill in missing, edit and remove. Files that would be replaced are backed up first, and skills that loosen permissions or run code need your consent.
- Pro: Skills for this project chooses which skills each project, or each Claude Code or Codex profile, uses.
- When Pyloxa runs Gemini CLI, Gemini can’t see your user-level skills; with an assignment Pro, the chosen skills are brought into each run.
- If Pro ends, the library and synced files stay and the CLIs still read them; assignments are kept but not applied.
Background running
These are in the free version, in Settings → General settings → Background running.
- When you close the window: stay in the tray while work is running (default), always stay in the tray, or quit. The tray icon shows what is running and gets a red dot when something needs you.
- Keep the computer awake while work is running (on by default): stops idle sleep on AC power only. Closing the lid or choosing Sleep still puts the computer to sleep.
- Quitting with work running asks: Quit When Done lets running tasks finish first, Quit Now stops them.
- Next time you open Pyloxa, interrupted tasks are listed with Resume All; the same agent continues from its saved work.
Usage and quota
The usage meter
- The title bar shows how much quota each agent has left, for example “Claude Code 62% left”. Select it to see each window (5 hours, 7 days) and today’s tokens.
- Claude Code on a subscription shows its real quota windows, updated when Pyloxa runs it. The quota is shared with claude.ai and your terminal.
- Codex CLI doesn’t report its subscription quota, so only tokens are shown. API keys and Gemini CLI are billed by use and have no quota windows. Costs shown are the CLI’s own estimates, not a bill.
- Hide it in Settings → Appearance → Layout → Show agent usage in the title bar.
When an agent runs out of quota
- Pyloxa marks the connection as out of quota and sends it no tasks until the reset time. If the reset time is unknown, choose Quota restored on Agent Connections when it is back.
- On the plan card, choose Let {name} take over to have the fallback agent continue from the files already changed, or Retry when the quota resets. Waiting work resumes after the reset.
- Short rate limits are retried automatically after a wait; network or service errors are retried once.
- Pro: Automatic fallback when quota runs out (Workflow → Division of work) hands the task to the rule’s fallback without asking, up to two times per task and only to the same kind of billing.
Scheduling, task center and notifications
- Task Center Pro (sidebar): everything waiting on you across projects, each project’s progress, scheduled plans, and usage and hours, with export to Markdown or CSV.
- Approve and schedule… Pro on the plan card: start at a set time or after the next quota reset. Pyloxa must be open (the tray is enough).
- Quota scheduling for this project… Pro (project menu in the sidebar): project priority and a quota share per connection.
- Backup brains Pro (Agents & Brain): up to three, taking over planning, answers and review when the main brain is out of quota, signed out or failing.
- Notifications to your phone Pro (General settings): send “needs you”, “plan done”, “gate failed” and “out of quota” to your own Telegram bot, Discord channel or webhook. They are sent directly from your computer while Pyloxa is open. Windows desktop notifications are free.
- Dispatch packs Pro (Workflow → rule list): export or import rules, your workflows, skills, conventions and suggested commands as a zip or folder. Importing previews each item and never overwrites your existing rules or workflows: when a workflow has the same name as one of yours but different contents, yours is kept unless you tick it (your version stays in its version history), and you can tick Use in this project. Workflows are written with CLI names and matched to this computer’s profiles on import. What older packs called “workflow and conventions” is now Conventions, which become the project’s shared memory; packs made by 0.1.10 still import. Rules in a repository’s
.pyloxa/folder are read in the free version.
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.
- Export settings… saves a
.pyloxa-settingsfile with the parts you tick: agent profiles, global routing rules, routing and brain preferences, your workflows, prompt templates, global shared memory, the Skills library and interface preferences. Exporting routing rules, preferences or your workflows also includes the agent profiles they use. - It never includes API keys, your license, project settings, which workflow each project uses, workflow version history or paths on this computer. Items that contain secrets are skipped and listed.
- Import settings… shows what will change first; where an item differs, this computer’s version is kept unless you tick it. Your current settings are backed up before anything is applied, and Restore a backup… brings back one of the last five.
- Your workflows are matched by name: identical ones are skipped, and when a name matches but the contents differ, this computer’s workflow is kept unless you tick it; a replaced workflow keeps its previous contents in its version history. You can have up to 20, and any beyond that aren’t imported. Without Pro they are still saved; using one in a project needs Pro.
- On the new computer, you still need to sign in to each CLI or enter API keys, add your project folders, and sign in to your account for Pro.
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
- Settings → General settings → License → Sign in. Your browser opens
account.pyloxa.com: continue with Google or GitHub, or get a six-digit code by email (valid for 10 minutes). Finish within 5 minutes, then return to Pyloxa. - The same verified email address is always the same account.
Pro preview and trial
- Pro preview: signing in gives you the full Pro for free until December 31, 2026 (Taiwan time). Everyone in the preview then gets 14 more days of Pro, until January 14, 2027.
- Trial: when the preview isn’t running, your first sign-in starts a 14-day Pro trial. No card is needed. Each account and each computer gets one trial. The sidebar shows the days left.
- From December 1, 2026, Buy Pro appears on the License card and on your account page. If you’re in the preview, the early-bird price is applied at checkout automatically, so there’s no code to enter. Buying is covered by the Pro terms and the refund policy: a full refund within 30 days of your first purchase, no reason needed.
Two computers
- One account can be signed in on two computers. Sign out of this computer frees its place and deletes no data.
- Signing in on a third computer shows your other two on the sign-in page, where you can remove one. You can also rename or remove computers on the Account page. Removing computers is limited to three times in 30 days; after that, write to support@pyloxa.com.
Staying online
- Pyloxa refreshes the license about once a day, sending only a device ID, its credential and the app and Windows versions. Check again refreshes now.
- If it can’t reach the license service, Pro keeps working for 14 days from the last successful refresh; the app warns you after three days. After that Pro pauses until a refresh succeeds.
- If your company network blocks
account.pyloxa.com, write to support@pyloxa.com with the device ID shown on the License card. We can send an activation code to paste under Have an activation code from support?
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
| Folder | What’s in it |
|---|---|
%APPDATA%\Pyloxa | Settings, history and the database (pyloxa.sqlite3), encrypted API keys and license (secrets.json), backups of skills and memory, and test-drive samples |
%LOCALAPPDATA%\Pyloxa\worktrees | The git worktrees where agents work |
| Your repositories | Task 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:
- Delete
%APPDATA%\Pyloxaand%LOCALAPPDATA%\Pyloxa. - In each repository you used, run
git worktree prune, and delete thepyloxa/…branches you don’t need. - If you used Sync to CLIs, remove Pyloxa’s marked block from
AGENTS.mdand the CLI memory files. The CLIs themselves, and skills synced to them, stay installed. - 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).
- Check the file’s SHA-256 against the release notes, then restore it from quarantine or allow it in your antivirus. Allow Pyloxa’s install folder rather than turning protection off.
- Each new version is a new file, so you may need to allow it again after updating.
- Then choose Re-detect on Agent Connections.
A CLI shows “Can’t dispatch”
- Sign-in required: sign in again in a terminal (
claude auth login,codex login), then Re-detect. - CLI not found: install it, or restart Pyloxa if you just installed it.
- Unverified version: it still runs in supervised mode. To use a verified one, choose Update to {version} on its card.
- Settings → General settings → Usage and feedback → Copy diagnostics copies the versions and connection states, useful in a report.
A task stopped with an error
- Subscription quota exhausted: wait for the reset or let another agent take over. See When an agent runs out of quota.
- Temporarily rate-limited or Service or network error: Pyloxa retries once by itself; otherwise check your connection and choose Retry.
- Couldn’t parse the CLI output: please report it with the run’s history.
- A check failed after three automatic runs: open the session to see what happened, then retry, reassign or fix it yourself.
Sign-in or license problems
- “Couldn’t reach the Pyloxa license service”: check your connection; a company network may block
account.pyloxa.com. See Staying online. - “Already signed in on 2 computers”: remove one on the sign-in page or the account page.
- “Sign-in timed out”: choose Sign in again and finish within 5 minutes.
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
- In the app: Settings → General settings → Usage and feedback → Report a problem or suggestion opens our GitHub issue forms: Bug report or Feature request. Paste the text from Copy diagnostics into the bug report.
- Issues are public. Never paste tokens, API keys or code you can’t share, and check screenshots for project names, file contents and account details.
- For account, license or private questions, write to support@pyloxa.com.
- Security vulnerabilities: report them privately through GitHub security advisories, not in a public issue.
Free and Pro at a glance
| Feature | Free | Pro |
|---|---|---|
| Plans, routing rules, worktrees, verification commands, gates, brain review | Yes | Yes |
| Workflow templates and your own plan stages | Yes | Yes |
| Shared memory, test drive, verification card, background running, usage meter, settings backup | Yes | Yes |
| Projects running at once | One | Several, with the Task Center |
| Tasks at once in a plan | Two | No per-plan limit |
| Dispatch mode | Suggest then ask, or follow settings only | Also auto within limits |
| When quota runs out | You confirm each takeover | Automatic fallback |
| Cross-testing | When you ask | Automatic, with send-back for a fix |
| Brain | One | Up to three backup brains |
| Saved workflows, version history and describing a workflow in a sentence | Imported workflows are kept | Yes |
| Agent Teams (experimental) | — | Yes |
| Scheduled plans, project priority and quota shares | Waiting work resumes after the reset | Yes |
| Usage report export | Usage per run | Across projects, Markdown or CSV |
| Notifications | Windows desktop | Also Telegram, Discord, webhook |
| Skills | List and view | Library, sync, per-project assignment |
| Dispatch packs | Reads .pyloxa/ in a repository | Import and export, including your workflows |
| Prompt templates | Up to five | Any 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.