Kojo — Controle remoto de IA para CLIs de codificação
loppo-llc/kojo
Controle CLIs de IA em múltiplas máquinas desde o celular, com agentes persistentes
Ver no GitHubAgent multi-dispositivo que permite operar remotamente Claude Code, Codex e Grok Build via navegador mobile. Executa agentes IA persistentes com memória, credenciais criptografadas e colaboração em grupo, conectados via Tailscale P2P sem servidor central.
Instalação
npx convez-ai loppo-llc/kojo1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Executar assistentes de código (Claude, Codex, Grok) remotamente do mobile
- Orquestrar agentes IA persistentes com memória entre múltiplas máquinas
- Cluster descentralizado de desenvolvimento via Tailscale com zero configuração
Veredito

Ferramenta sofisticada para developers que precisam gerenciar CLIs de IA em múltiplas máquinas remotamente. A arquitetura P2P com Tailscale e suporte nativo a agentes persistentes é diferencial sólido, mas exige conhecimento técnico e setup prévio (Go, Node, tmux).
README
A tradução para o português deste README ainda está na fila.
kojo
Remotely operate AI coding CLIs (Claude Code, Codex, Grok Build) from your mobile device — and run persistent AI agents, across one or more machines, that think, remember, and collaborate on their own.
┌───────────────────┐ Tailscale ┌──────────────────┐
│ macOS / Win / Linux│◄─────(P2P encrypted)─────►│ Mobile Browser │
│ │ │ │
│ kojo server │ WebSocket / HTTP │ Web UI │
│ ├─ PTY sessions │◄─────────────────────►│ ├─ xterm.js │
│ ├─ AI agents │ │ ├─ React │
│ └─ credentials DB │ │ └─ Web Push │
└───────────────────┘ └──────────────────┘
Features
- Single binary — Built with Go, web UI embedded
- Cross-platform — macOS/Linux (tmux + PTY) and Windows (ConPTY) native support
- AI agents — Persistent AI personas with memory, scheduled execution, encrypted credentials, and group DM
- tmux-backed sessions (macOS/Linux) — CLI tools run inside tmux for crash resilience and persistence across kojo restarts
- Unified PTY — All CLIs handled uniformly via PTY. No SDK dependencies
- Tailscale P2P — No central server or database. Encrypted with WireGuard
- Zero config — Just run
kojowith Tailscale running
Requirements
macOS / Linux
- Go 1.25+
- Node.js 20+
- tmux
- Tailscale
- Supported CLIs:
claude,codex,grok(Grok Build) — at least one
Windows
- Go 1.25+
- Node.js 20+
- Windows 10 1809+ / Windows 11 (ConPTY support required)
- Tailscale
- Supported CLIs:
claude,codex,grok(Grok Build) — at least one
Note: On Windows, sessions run via ConPTY instead of tmux. Session persistence across kojo restarts is not available.
Build
# Production build (macOS/Linux)
make build
# Cross-compile for Windows (from macOS/Linux)
make build-windows
# Build on Windows
build.bat
# Development (two terminals)
make dev-server # Go server (--dev mode, proxies to Vite)
make dev-web # Vite dev server
# Hot reload (auto rebuild on Go file changes)
make watch
Usage
# Via Tailscale (default, auto HTTPS)
kojo
# Local only
kojo --local
# Custom port (auto-increments if busy)
kojo --port 9090
By default, kojo listens on the Tailscale network via tsnet with HTTPS.
Use --local or --dev to bind to localhost only.
Multi-device cluster (peer mode)
A second machine joins the Hub as a peer with a single command. Any combination of macOS, Linux, and Windows machines is supported.
# On the peer host
kojo --peer
The peer auto-discovers the Hub via Tailscale MagicDNS
(https://kojo.<tailnet>.ts.net:8080), writes the Hub into its local
peer registry, and POSTs a join request. The Hub holds the request and
surfaces it in Settings → Peers → "Pending join requests". Click
Approve to grant the peer the privileged surface (sessions, files,
git). Reject drops the request; the peer is free to retry.
Override the discovery target when needed:
kojo --peer --hub https://hub.example.ts.net:8080
KOJO_HUB_URL=https://hub.example.ts.net:8080 kojo --peer
Bind the peer listener to the Tailscale interface only (refuse to fall
back to 0.0.0.0):
kojo --peer --tailnet-only
The legacy manual pairing path (--peer-add / --peer-trust /
--peer-remove) still works as an escape hatch.
See docs/multi-device.md for the full multi-device setup, agent device-switch, and Hub failover procedure.
Upgrading from an earlier release
The on-disk config layout changed in v0.101.0. If you ran an earlier
kojo release (v0.x using ~/.config/kojo/ on macOS / Linux or
%APPDATA%\kojo\ on Windows), see docs/migration.md
for the --migrate flow, rollback path, and the list of features that
did not carry over (Gemini CLI backend and Gmail notifications were
removed).
Tailscale HTTPS Setup
kojo uses tsnet to join your Tailscale network directly as a node named kojo. All traffic is encrypted with WireGuard — no ports to open, no certificates to manage.
Prerequisites
- Install Tailscale on your machine and your mobile device
- Sign in to the same Tailscale account on both devices
- Ensure both devices appear in Tailscale admin console
How it works
When you run kojo (without --local):
- kojo starts an embedded Tailscale node via tsnet
- The node registers itself as
kojoon your tailnet - HTTPS is automatically provisioned using Tailscale's built-in Let's Encrypt integration
- Your server becomes reachable at
https://kojo.<tailnet-name>.ts.net
$ kojo
kojo v0.102.0 running at:
https://kojo.tail1234.ts.net
https://100.x.y.z:8080
First run
On the first launch, tsnet will print an authentication URL to stderr. Open it in your browser to authorize the node. This is a one-time step — credentials are cached in ~/.config/tsnet-kojo/.
Access from mobile
- Install the Tailscale app on your phone
- Sign in with the same account
- Open
https://kojo.<tailnet-name>.ts.netin your mobile browser
All communication is peer-to-peer via WireGuard. No data passes through a central server.
Security model
| Layer | Protection |
|---|---|
| Network | WireGuard encryption (Tailscale P2P) |
| TLS | Auto-provisioned HTTPS via Let's Encrypt |
| WebSocket | Origin restricted to Tailscale IPs (100.*), *.ts.net, and localhost |
| Access | Only devices on your tailnet can reach kojo |
ACL (optional)
You can restrict which devices can access kojo using Tailscale ACLs:
{
"acls": [
{
"action": "accept",
"src": ["tag:mobile"],
"dst": ["tag:kojo:*"]
}
],
"tagOwners": {
"tag:mobile": ["autogroup:admin"],
"tag:kojo": ["autogroup:admin"]
}
}
Troubleshooting
| Problem | Solution |
|---|---|
| Auth URL not appearing | Check stderr output, or remove ~/.config/tsnet-kojo/ and restart |
| Cannot reach from mobile | Ensure both devices are on the same tailnet and Tailscale is connected |
| Port conflict | Use --port <number> (auto-increments up to 10 times if busy) |
| Want localhost only | Use --local or --dev to skip Tailscale entirely |
What it does
Terminal Sessions
- Manage multiple sessions simultaneously (newest first)
- Session persistence via tmux on macOS/Linux (
~/.config/kojo/sessions.json, auto-cleanup after 7 days). Sessions survive kojo restarts and crashes - Session restart with tool-specific resume (
claude --resume,codex resume,grok --resume) - Real-time PTY output streaming (xterm.js)
- Text input (Enter for newline, Shift+Enter to send) and special keys (Esc, Tab, Ctrl, arrows)
- Working directory path completion
- File browser (syntax highlighting for text, image preview)
- File attachment (camera, images, text)
- Git panel (status, log, diff, commit diff view)
- Web Push notifications (permission prompts, completion alerts)
- Yolo mode (auto-approve permissions)
- Minimal system prompt option for claude (override default with a working-directory note)
AI Agents
- Create persistent AI personas with custom name, personality, avatar, and backend (Claude / Codex / Grok Build, plus custom Anthropic Messages API endpoints like llama-server)
- AI-assisted persona generation (via claude/codex/grok CLI) and avatar generation (Gemini Image API)
- Interactive chat with streaming responses, thinking display, and tool-use cards
- Markdown rendering in agent messages
- Scheduled autonomous execution (10 min – 24 h intervals) with auto-staggering, per-agent timeout, and cross-process dedup
- Persistent memory: long-term
MEMORY.md+ daily notes with full-text search (SQLite FTS5) - Encrypted credential vault (AES-256-GCM SQLite) with TOTP 2FA support
- Public profile and agent directory for inter-agent discovery
- Group DM: multi-agent conversations with notification-based messaging
- Slack integration (Socket Mode) — per-agent bot with live streaming replies, per-thread session resumption, and channel/thread-aware system prompt
- Agent data reset (clear conversations and memory while keeping settings, persona, avatar, and credentials)
- Fork agents preserving persona and memory
Tech Stack
| Layer | Technology |
|---|---|
| Server | Go, net/http, coder/websocket, creack/pty (Unix) / ConPTY (Windows), tmux (Unix), tsnet |
| Web UI | React 19, Vite, TypeScript, Tailwind CSS, xterm.js |
| Agents | Claude / Codex / Custom API backends, encrypted SQLite (credentials + FTS5 memory) |
| Notifications | Web Push (VAPID) |
| Network | Tailscale WireGuard P2P |
Install
go install github.com/loppo-llc/kojo/cmd/kojo@latest