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
- ★ 544
- Last updated
- 1d ago
- License
- AGPL-3.0
- Primary language
- Python
- FA score
- 67/100 · Some 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
- Website
- vicoa.ai ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-20latest release v0.2.1 (2026-11-20)+0.6 ★/day over 7 days
- Source review
- 67/100 · Some 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
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npm i -g @vicoa/clipip install vicoa
- Config files
.env.example.envdocker-compose.selfhost.yml- Runtime
- Node.js 18+
- Install notes cover
- Windows · macOS · Linux · Docker
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 | 67 · Some gaps | Desktop appFree + model costs | ★ 544 | 1d ago | Python | Codex · Claude Code |
| Cezar — AI Coding Agent Orchestrator | 62 · Some gaps | CLIFree | ★ 1.1k | today | TypeScript | Codex · Claude Code |
| gnhf (Good Night, Have Fun) | 55 · Major gaps | CLIFree + model costs | ★ 4.3k | 4d ago | TypeScript | Codex · Claude Code |
| Kandev | 74 · Some gaps | CLIFree + model costs | ★ 1.2k | today | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The docs say the CLI uses the user's own agent credentials and call for inspection or confirmation before task mutations, session sharing, automation creation, and session starts. They disclose that share links may expose a transcript to anyone holding the URL and that automations start real sessions. They also describe hashed API-key storage, revocation checks, and private security reporting. Deductions: Vicoa can start coding agents and scheduled work on the user's behalf, with broad access to code; the supplied source excerpts do not show complete authorization, secret-storage, or recovery implementations, and source attribution is not explicit.
The two service entry points describe their roles and shutdown paths; the backend returns a retryable 503 for database disconnects, the CLI treats update-check failure as best effort, and SSE failures are logged. The test excerpts show transaction isolation and access-control semantics. Deductions: dependency inventories, availability policies, and complete failure paths are not supplied; excerpts of tests do not establish runtime outcomes.
The product targets desktop, mobile, remote-machine, and self-hosted use, lists native and ACP agents, and describes CLI modes, identity-provider options, and remote use. Skill triggers are specific, and some skills disable model-initiated invocation. Deductions: the breadth of components and agent combinations creates configuration and compatibility overhead; the excerpts do not fully specify support boundaries or platform differences.
The README, AGENTS file, and security policy provide layered repository guidance, installation and development entry points, component descriptions, examples, a security-reporting channel, and a supported-version policy; the license is clearly AGPL-3.0. Deductions: version information and changelog evidence are limited, maintenance responsibility is indicated only indirectly through community channels and a security email, and the excerpts cannot establish that all documentation stays aligned with implementation.
The product brings multiple coding agents, workspaces, sessions, tasks, and automations together across desktop, mobile, and CLI. The skills provide structured output formats and actionable workflows. Deductions: self-hosting requires a database, backend, server, and clients, and users must install and authenticate at least one external agent CLI; the source does not quantify operating costs or resource use.
README product claims can be compared with the architecture descriptions in AGENTS and the supplied backend and CLI excerpts; security and usage guidance also describes concrete behavior. Deductions: many capabilities remain documented claims, the supplied code and tests are samples that cannot verify every critical path, and this review distinguishes documentary claims from facts directly supported by excerpts but does not execute the software.
- Starting sessions, creating automations, and sharing transcripts have real external effects; verify the target machine, task, schedule, and audience first.
- Self-hosting involves several services and a database. This assessment is based only on the supplied excerpts; it did not run the software or verify all dependencies and security implementations.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Bundles Vicoa CLI daemon [v1.10.1](https://www.npmjs.com/package/@vicoa/cli/v/1.10.1). 🚀 Features * AGENTS: don't name other products in PRs, commits or docs in https://github.com/vicoa-ai/vicoa/commit/8a029d8 * Dashboard plugin: Needs you lists the open questions on tasks; the plugin bridge reports openQuestions in https://github.com/vicoa-ai/vicoa/commit/8231f26 * Tasks: annotate text in a comment and send it in a reply in https://github.com/vicoa-ai/vicoa/pull/264 …View on GitHub ↗ -
Release notes excerpt
Bundles Vicoa CLI daemon [v1.10.0](https://www.npmjs.com/package/@vicoa/cli/v/1.10.0). 🚀 Features * CLI: remove vicoa codex and the bundled Codex fork in https://github.com/vicoa-ai/vicoa/pull/255 * Keep earlier queued messages in the bar when a later one is steered in https://github.com/vicoa-ai/vicoa/pull/253 * Sessions: import sessions started outside Vicoa (Claude Code, Codex) in https://github.com/vicoa-ai/vicoa/pull/257 * Backend: index agent_instances.last_read_message_id so session deletes don't time out in https://github.com/vicoa-ai/vicoa/pull/256 …View on GitHub ↗ -
Release notes excerpt
Bundles Vicoa CLI daemon [v1.9.18](https://www.npmjs.com/package/@vicoa/cli/v/1.9.18). 🚀 Features * Sessions: send to a closed or stopped session to resume it in https://github.com/vicoa-ai/vicoa/pull/250 * Web: keep AskUserQuestion answers in the transcript in https://github.com/vicoa-ai/vicoa/pull/249 * AskUserQuestion: keep the answer in the transcript when the session reads active in https://github.com/vicoa-ai/vicoa/pull/239 * Daemon collision check knows which server each daemon belongs to in https://github.com/vicoa-ai/vicoa/pull/246 …View on GitHub ↗
FAQ
Do I have to pay?
Does my code and data pass through Vicoa's servers?
Which agents are supported, and how do I add new ones?
Will multiple agents editing one repo conflict?
Can I use it without a phone?
Is Vicoa open source?
Is Vicoa safe to use?
Is Vicoa still maintained?
Who makes Vicoa?
What is Vicoa's official website?
Thanks — we use this to improve the page.