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

At a glance

How it runs
Desktop appCLISelf-hosted service
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
Node.js 18+ (CLI)Docker (self-hosting)PostgreSQL (self-hosted backend)At least one supported agent CLI (e.g. claude, codex, opencode)Python 3.10+ (backend, or pip install vicoa)Flutter (mobile app development)Shell / CLINetwork accessLocal filesystem
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>.

  1. 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
  2. A developer with code on multiple machines (Mac, Windows, Linux, VPS) who wants one place to pick where each session runs
  3. A team benchmarking Claude Code vs Codex vs OpenCode vs Gemini, running them side by side in one workspace
  4. A maintainer who wants cron-scheduled automations to let agents pick up and finish board tasks automatically
  5. A team that must keep sessions and data on its own infrastructure, self-hosting the full stack with Docker and PostgreSQL
  6. 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/cli
  • pip install vicoa
Config files
.env.example .env docker-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/cli

vicoa

On Intel Macs or old glibc systems, use pip instead:
bash

pip install vicoa

Self-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 -d

The 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?

  1. Install and sign in to Vicoa Desktop.
  2. Click New Session, pick the machine and the agent (e.g. claude, codex), and enter your first prompt.
  3. 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 catalog

Inside 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?

Pros
  • 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
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Some gaps
67/ 100 5-point scale 3.4 / 5
This review covers the source as of Nov 07, 2026. The project has shipped 6 stable release(s) since, which have not been re-reviewed. The score and verdict describe the reviewed version only. Recent releases ↓
Trust 14/29
Reliability 8/14
Adaptability 16/18
Convention 12/18
Effectiveness 12/13
Verifiability 5/8
Why each dimension lost points
Trust14 / 29 · 2.4/5

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.

Reliability8 / 14 · 2.9/5

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.

Adaptability16 / 18 · 4.4/5

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.

Convention12 / 18 · 3.3/5

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.

Effectiveness12 / 13 · 4.6/5

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.

Verifiability5 / 8 · 3.1/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 07, 2026 Reviewed revision e7d584606bb9 New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/vicoa.svg)](https://followagents.com/en/agents/vicoa)
<a href="https://followagents.com/en/agents/vicoa"><img src="https://followagents.com/badge/vicoa.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v0.2.1
    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 ↗
  2. v0.2.0
    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 ↗
  3. v0.1.46
    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?
Vicoa itself is open source (AGPLv3) and free, including self-hosting; but the agents need their own subscriptions or API keys (BYO-key), and those usage costs are yours.
Does my code and data pass through Vicoa's servers?
With the official backend, sessions and messages sync through its API/realtime server; you can also self-host the entire backend (FastAPI + PostgreSQL) with Docker and keep data on your own infrastructure.
Which agents are supported, and how do I add new ones?
Built-in: Claude Code, Codex, OpenCode, Gemini, Cursor, GitHub Copilot, Kimi, Hermes, Pi, Oh My Pi, and Antigravity — with native integrations for Claude Code, Codex, Pi, Oh My Pi, and Antigravity; the rest connect over ACP, and any ACP-speaking agent works via a custom launch command.
Will multiple agents editing one repo conflict?
No — each agent runs on its own git worktree and branch, so several can work the same repo at once without stepping on each other.
Can I use it without a phone?
Yes. Vicoa offers macOS/Windows/Linux desktop apps, a web UI, and a CLI; mobile is an optional multi-device entry point.
Is Vicoa open source?
Yes. The source code is on GitHub (vicoa-ai/vicoa) under the AGPL-3.0 licence. AGPL-3.0 is a copyleft licence that also covers network use: if you run a modified version as a service, you must offer its source to users.
Is Vicoa safe to use?
FollowAgents' FARS review (Nov 07, 2026) scored Vicoa 14/29 on trust and safety. None of the eight safety controls the review checks for was missing outright. The repository has changed since that review.
Is Vicoa still maintained?
Yes. The latest commit on GitHub is from 2026-11-20, within the last 30 days. The latest release is v0.2.1 (2026-11-20).
Who makes Vicoa?
Vicoa is published on GitHub by the account vicoa-ai. FollowAgents has not verified which person or company is behind that account.
What is Vicoa's official website?
The project's GitHub repository lists https://vicoa.ai as its website. That link is set by the repository owner; the source code itself is on GitHub (vicoa-ai/vicoa).
Was this page helpful?
View on GitHub ↗ Install ↓

Host ecosystems

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts