Vicoa
An open-source AI orchestrator for running a team of coding agents from desktop, mobile, or VPS — sessions sync everywhere and the stack is self-hostable.
- Source repo
- vicoa-ai/vicoa
- Stars
- ★ 475
- Last updated
- 1d ago
- License
- AGPL-3.0
- Primary language
- Python
- FA score
- 52/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An engineer who launches several agents in parallel on one repo at the desk, then reviews diffs and answers agent questions from the phone after hours
- Not a fit if
- Users who want a single-vendor hosted service with no own model subscription or API keys
- Teams unwilling to self-host a backend/Postgres or accept account-based cloud sync of sessions
- Developers who only want a plain chat-style coding assistant
- Source review
- 52/100 · Major gaps
What does this agent do, and when should you use it?
Vicoa is an open-source (AGPLv3) AI orchestrator for running a team of coding agents — Claude Code, Codex, OpenCode, and 40+ others — from any device. It ships a complete self-hostable stack: a Python/FastAPI backend with PostgreSQL, a local vicoa daemon, a Next.js web and Electron desktop client, and a Flutter mobile app for iOS and Android. Each agent works in its own git worktree and branch so several can touch the same repo in parallel, and every session appears in one command-center list. You steer from the phone with conversation, inline diffs, and push notifications, and sessions stay synced across devices. The tool is BYO-key: it launches the agent CLIs already installed and authenticated on your machine with your own subscriptions or API keys.
The local vicoa daemon (or vicoa daemon) detects the agent CLIs installed on a machine and spawns sessions wherever you choose — your Mac, a Windows laptop, a Linux box, a VPS, or a remote server — each agent on its own git worktree and branch for parallel work on the same repo. The backend (FastAPI + WebSocket + PostgreSQL) handles auth, sessions, messages, tasks, and cron-based Automations, syncing everything in real time to the web, desktop, and mobile clients. You monitor all sessions from one list, prompt agents via @file fuzzy mentions, the agent's own /commands, or dictation, and start sessions straight from a task board. Inline per-file diffs, commit history, a file tree, a terminal, and a mobile live preview of a local dev website are viewable on desktop and phone. The CLI also drives sessions, chat history, tasks, and automations, so agents can operate Vicoa themselves. Integration-wise, Claude Code, Codex, Pi, Oh My Pi, and Antigravity have native integrations; the rest connect via the Agent Client Protocol (ACP), with 30+ more agents in the built-in catalog added via vicoa provider add <id>.
- An engineer who launches several agents in parallel on one repo at the desk, then reviews diffs and answers agent questions from the phone after hours
- A developer with code on multiple machines (Mac, Windows, Linux, VPS) who wants one place to pick where each session runs
- A team benchmarking Claude Code vs Codex vs OpenCode vs Gemini, running them side by side in one workspace
- A maintainer who wants cron-scheduled automations to let agents pick up and finish board tasks automatically
- A team that must keep sessions and data on its own infrastructure, self-hosting the full stack with Docker and PostgreSQL
- An automation tinkerer whose CLI-driven agents start sessions and manage tasks and automations in Vicoa the same way a human would
How do you install or deploy this agent?
Desktop: download Vicoa Desktop for macOS, Windows, or Linux from https://vicoa.ai/download, open it, and sign in. Prerequisite: the machine that runs agents needs at least one supported agent CLI installed and signed in (e.g. claude, codex, opencode).
Install the CLI (Node.js 18+):
bash
npm i -g @vicoa/clivicoa
On Intel Macs or old glibc systems, use pip instead:
bash
pip install vicoaSelf-host the full stack with Docker:
bash
cp .env.example .env # passwords and public URLs
./backend/scripts/generate-jwt-keys.sh selfhost/keys
docker compose -f docker-compose.selfhost.yml up -dThe full walkthrough is in SELF_HOSTING.md in the repository. Mobile: install Vicoa from the App Store or Google Play and sign in with the same account.
How do you use this agent?
- Install and sign in to Vicoa Desktop.
- Click New Session, pick the machine and the agent (e.g. claude, codex), and enter your first prompt.
- Install the Vicoa mobile app and sign in with the same account — running sessions sync automatically.
Terminal usage:
bash
vicoa # start a session, or vicoa daemon to just connect this machine
vicoa provider add <id> # add an ACP agent from the built-in catalogInside a session, use @file fuzzy mentions, the agent's own slash commands, or dictation; review inline diffs, the file tree, the terminal, and a live preview of your local dev website from desktop or phone. Plan work on the task board, start a session from a task, or let Automations run on cron schedules.
What are this agent's strengths and limitations?
- 40+ agents in parallel on the same repo: each gets its own git worktree and branch, avoiding collisions — something plain multi-tab terminal sessions can't do
- A real mobile coding app, not a chat tab: native iOS/Android clients with sessions, conversation, live git diffs, and lock-screen push notifications
- Vendor-neutral and BYO-key: it launches the agent CLIs already installed and authenticated on your machine with your own subscriptions or API keys, and the whole stack is self-hostable
- Programmable end to end: the CLI covers sessions, chat history, tasks, and automations, so your agents can drive Vicoa just like you
- The machine running agents must already have at least one supported agent CLI installed and signed in; Vicoa provides no model itself, so you need your own subscriptions or API keys
- Self-hosting means maintaining Docker Compose, JWT key generation, and PostgreSQL — more operational overhead than a single-binary tool
- Cross-device sync depends on the account and backend; if the network or backend is unavailable, multi-device collaboration stops, and self-hosters must ensure availability themselves
- The AGPLv3 license imposes copyleft obligations on commercial integration and redistribution, requiring legal review
- The desktop app is Electron and the mobile app requires Flutter builds, adding cost for resource-sensitive teams or those wanting to embed it in their own apps
How does this agent compare with similar options?
The README positions Vicoa as an orchestration layer over the agent CLIs you already use — Claude Code, Codex, Cursor, Pi, Kimi, and more — versus running each agent individually in a terminal; Vicoa adds parallel worktrees, one command center, cross-device sync, and mobile notifications. The repository does not name other orchestrator competitors.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Vicoa This agent | 52 · Major gaps | Desktop appFree + model costs | ★ 475 | 1d ago | Python | Codex · Claude Code |
| Cezar — AI Coding Agent Orchestrator | 63 · Some gaps | CLIFree | ★ 464 | 2d ago | TypeScript | Codex · Claude Code |
| Kandev | 74 · Some gaps | CLIFree + model costs | ★ 891 | today | Go | Codex · Claude Code |
| Solo Agent | 48 · Major gaps | Self-hosted serviceFree + model costs | ★ 697 | 21d ago | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows the daemon runs on user machines handling agent credentials and code, acknowledged in SECURITY.md; CI has fork guards, OIDC trusted publishing, and pinned glibc builds, showing supply-chain awareness. Deducted: no repository evidence for agent execution permission boundaries, user confirmation mechanisms, or data-flow documentation (README only links external docs); tests reveal `.env` may carry production email credentials that an autouse fixture must scrub to prevent real outbound mail — a weak point in sensitive configuration handling.
Repository layout matches the README; test infrastructure (testcontainers, transactional rollback, fail-closed capability hook tests) is high quality; builds include binary smoke tests. Deducted: the visible files are mostly tests and CI; failure messaging in the CLI/daemon itself is not in evidence; cross-platform builds are covered on paper but not executed.
README clearly targets desktop-to-mobile-to-VPS scenarios, 40+ agent CLIs and ACP, with solid environment fit notes (Node 18+, glibc floor, Intel Mac pip fallback). Deducted: capability boundaries (what requires user approval, automation/cron limits) and trigger precision are asserted only via external links, with insufficient in-repo evidence.
License is the full AGPL-3.0 text matching metadata (full marks); README is well structured with architecture diagram, self-hosting steps, SECURITY.md and CONTRIBUTING.md references. Deducted: no CHANGELOG or versioning file in evidence, no known-limitations section, examples/FAQ largely outsourced to the external docs site, maintenance responsibility only implied by community channels.
Clear product positioning (multi-agent orchestration plus mobile takeover), BYO-key reduces lock-in, self-hostable stack offers cost control. Deducted: output usability (actual session/diff review quality) and marginal value versus peers cannot be verified from README alone.
In-repo tests partially corroborate README claims (architecture, permission model); fact/inference separation is fairly clear in the files. Deducted: core security claims (credential handling, sync) cannot be traced in provided files; the 40+ agent support figure is unverifiable; external docs content not supplied.
- Agent execution permission boundaries and user-confirmation mechanisms are undocumented in the repo; audit how the daemon invokes agent CLIs in your own self-hosted environment before adoption.
- conftest.py indicates local `.env` may hold production email-provider credentials; isolate real credentials in self-hosted deployments and prevent outbound mail from test environments.
- Publisher identity is unverified; consider signature or checksum verification for the dependency chain (npm platform packages, PyInstaller binaries) before adopting.
- AGPL-3.0 imposes open-source obligations for network services; assess compliance cost before commercial embedding.