vicoa README

The project's README from github.com/vicoa-ai/vicoa. As one markdown file: README.md.

Vicoa Vicoa

Vicoa website Desktop and CLI on macOS, Windows and Linux Mobile apps for iOS and Android Join the Vicoa Discord Follow Vicoa on X

English | 简体中文

Vicoa is an open-source AI orchestrator for running a team of coding agents from any device.

Download Vicoa

The Vicoa desktop app running several agent sessions, with the same sessions open on a phone

Start at your desk. Steer from your pocket.

Run a team of coding agents

Claude Code, Codex, Cursor, Pi, Kimi, and more

Steer from any device.

The session you started on your laptop, in your pocket.

Four Vicoa mobile screens: agent sessions grouped by project, a chat with a coding agent, a git diff review, and lock-screen push notifications

A real mobile coding app, not a chat tab: sessions, conversation, live git diffs, and push notifications.

More Features

Get started

Download Vicoa Desktop for macOS, Windows, or Linux. It connects the computer it runs on and detects installed agents.

The one prerequisite: the machine that runs agents needs at least one supported agent CLI installed and signed in.

Prefer the terminal?

npm i -g @vicoa/cli     # Node.js 18+; on Intel Macs or old glibc, use: pip install vicoa
vicoa                   # start a session, or `vicoa daemon` to just connect this machine

Your first session in three minutes

1. Install and sign in. Open Vicoa Desktop and sign in.

2. Start some agents. Click New Session, pick the machine, the agent, and enter your first prompt.

3. Steer from your phone. Install the Vicoa mobile app and sign in with the same account — running sessions sync automatically.

Download on the App Store   Get it on Google Play

Full walkthrough: Set up Vicoa · Start a remote session

Supported agents

Vicoa launches the agent harness and CLIs you already have installed and authenticated, on your machine, with your credentials.

Agent CLI Agent CLI
Claude Code claude Cursor cursor-agent
Codex codex GitHub Copilot copilot
OpenCode opencode Kimi kimi
Gemini gemini Hermes hermes
Pi pi Oh My Pi omp

Claude Code, Codex, Pi, and Oh My Pi have native integrations; the rest connect over the Agent Client Protocol (ACP).

Documentation

What's in this repository

This is Vicoa, open source: the complete, self-hostable stack:

Vicoa is BYO-key: you bring your own agent and model subscriptions or API keys

Self-hosting

Run the whole stack yourself with Docker:

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.

Architecture

     Web  ·  Desktop (macOS/Windows)  ·  iOS  ·  Android  ·  CLI
                            │
                            ▼
  ┌──────────────┐   ┌────────────────┐   ┌──────────────────┐
  │   Next.js    │──>│    FastAPI     │──>│    PostgreSQL    │
  │  dashboard   │<──│  backend + WS  │<──│                  │
  └──────────────┘   └───────┬────────┘   └──────────────────┘
                             │  sessions and messages over WebSocket
                     ┌───────┴───────┐
                     │ vicoa daemon  │  runs on your machine, next to your code
                     └───────┬───────┘
                             │  spawns
                     ┌───────┴─────────────────────────────────┐
                     │ Claude Code · Codex · OpenCode · Gemini │
                     │ Cursor · Copilot · Kimi · Hermes        │
                     │ Pi · Oh My Pi                           │
                     └─────────────────────────────────────────┘
Layer Stack
Web Next.js 15 + React 19, shadcn/ui, Fumadocs for the docs
Desktop Electron, running the web UI and supervising a bundled daemon
Mobile Flutter (iOS / Android)
Backend Python 3.10+ / FastAPI: a user-facing REST API, plus an agent-facing REST + WebSocket server
Database PostgreSQL via SQLAlchemy and Alembic
Agent runtime The local vicoa daemon, spawning any of the agent CLIs above

Development

Start with the Contributing.md.

Quick repository layout:

vicoa/
├── backend/              # Python: FastAPI backend + REST servers + CLI & daemon
│       └── vicoa/        # the `vicoa` CLI and the local daemon
├── apps/
│   ├── web/              # Next.js dashboard (also the desktop renderer) + docs
│   ├── desktop/          # Electron desktop app
│   └── mobile/           # Flutter app (iOS / Android)

Common commands: 

# backend, CLI and daemon (Python)
cd backend 
make dev-install
./dev-start.sh

make lint && make test

# web and docs (Next.js)
cd apps/web && pnpm install && pnpm dev

# desktop app (Electron); see apps/desktop/README.md
cd apps/desktop && pnpm install && pnpm dev

# mobile app (Flutter)
cd apps/mobile && flutter pub get && flutter run

Community & Support

License

Vicoa is open source under AGPLv3 license.

vicoa (vicoa-ai/vicoa)

ade
Searching Database…

518 ·GitHub
Vicoa
What is this?Vicoa is an open-source AI orchestrator that lets you run and manage a team of coding agents (Claude Code, Codex, Cursor, and more) from your desktop, phone, or a VPS, with sessions synced across devices.
Is this a chat app, or does it actually run my coding agents?It actually launches the real agent CLIs (claude, codex, cursor-agent, etc.) on a machine you control and gives you sessions, live git diffs, a file browser, and push notifications, not just a chat window.
How do I get it running?Download Vicoa Desktop for macOS, Windows, or Linux; it auto-detects agent CLIs on that machine. Then click New Session, pick the machine and agent, and type your first prompt; install the iOS/Android app to keep steering the same session from your phone.
Do I need Claude Code or Codex already installed?Yes, Vicoa doesn't ship its own model; it launches agent CLIs you already have installed and signed in on the machine, such as claude, codex, cursor-agent, or opencode.
Does Vicoa include its own AI model, or do I need my own subscription?It's BYO-key: Vicoa orchestrates sessions but you supply your own agent and model subscriptions or API keys.
Which devices can I use to steer a session?A session started on the Mac/Windows/Linux desktop app can be picked up from the iOS or Android app or the web client, since running sessions sync automatically across devices once you sign in with the same account.
Which coding agents does Vicoa support?Claude Code, Codex, OpenCode, Gemini, Cursor, GitHub Copilot, Kimi, Hermes, Pi, and Oh My Pi can all run side by side; Claude Code, Codex, Pi, and Oh My Pi have native integrations while the rest connect over the Agent Client Protocol (ACP).
Why does each agent get its own git worktree?So several agents can work on the same repo at once without stepping on each other, since each session runs on its own git worktree and branch.
What's included if I self-host the stack?The full stack: a CLI plus local daemon, a Python/FastAPI backend with PostgreSQL, and the web, Electron desktop, and Flutter mobile clients, deployed with Docker as described in SELFHOSTING.md.
What else can I do besides chat with an agent?You also get inline file diffs, a file browser, an in-app terminal, a mobile live preview of your local dev server, a task board, and cron-based automations so agents can pick up work on their own.
What are similar projects?orca, paseo, claude_codex_bridge, Ghostex, oh-my-openagent, zuse, hapi, ordewell
Which topics is it in?ade, agent-client-protocol, git-worktrees, kimi, task-management, vibe-coding, hermes-agent, flutter, github-copilot, agplv3, fastapi, opencode
Creator
vicoa-ai
Size
49.9 MB
Stars
518
Updated
CommitOct 10Releasev0.1.38Oct 08
Age
1mo
Commits · 90 Days