Vibes

A mobile-friendly web UI for coding agents, written in Go. Ships as a single static binary (~24 MB) with zero runtime dependencies.

Supports four ACP agents and Pi native RPC. Built for personal use over Tailscale.

This is the Go port — single binary, embedded frontend, pure-Go SQLite.
The original Python implementation is on the python branch.

Features

Streaming chat — real-time SSE with Markdown, KaTeX, and Mermaid rendering
Workspace explorer — file tree with previews, drag-and-drop upload, folder downloads (ZIP)
Code editor — tabbed CodeMirror 6 editor (13 languages, Vim mode, search/replace, pop-out windows)
Agent controls — approve/deny tool calls, queue follow-ups, mid-turn steering, slash commands
Rich media — paste images, attach files, OpenGraph link previews
SQLite storage — messages, media, and full-text search in a single file
PWA — installable, dark/light themes, responsive from phone to desktop
Single binary — no Python, no Node.js, no virtualenv, no runtime dependencies
Extension system — backend routes, SSE events, and frontend UI panels
Multi-agent — switch between Copilot, Codex, Claude, OpenCode, and Pi at runtime

Verified ACP agents

Agent	Binary	Version	Status
GitHub Copilot	`copilot-language-server --acp --stdio`	v1.472.0	✅
OpenAI Codex	`codex-acp`	v0.11.1	✅
Claude	`claude-agent-acp`	v0.29.2	✅
Pi	`pi-acp`	v0.0.26	✅
OpenCode	`opencode acp`	v1.14.31	✅

Capability matrix

Feature	Copilot	Codex	Claude	Pi	OpenCode
Image support	✅	✅	✅	✅	✅
Embedded context	✅	✅	✅	—	✅
MCP support	—	✅ (HTTP)	✅ (HTTP + SSE)	—	✅ (HTTP + SSE)
Session list/close	✅	✅	✅	✅	✅
Session fork/resume	—	—	✅	—	✅
Prompt queueing	—	—	✅	—	—
Free models	—	—	—	—	✅
Auth	GitHub OAuth	ChatGPT / API key	Pre-configured	Terminal login	`opencode auth`

All five implement ACP protocol v1 over stdio JSON-RPC. OpenCode provides free models (gpt-5-nano, hy3-preview-free, etc.) making it ideal for CI testing. Pi also supports a richer native RPC mode with streaming drafts, thinking traces, tool events, and live model control.

Quick start

# Build
git clone https://github.com/rcarmo/vibes.git && cd vibes
make build

# Run with GitHub Copilot (default)
./vibes

# Override detected ACP backends if needed
VIBES_CODEX_AGENT="codex-acp" ./vibes
VIBES_COPILOT_AGENT="copilot-language-server --acp --stdio" ./vibes

# Run with Pi native RPC selected by default (richer features)
VIBES_DEFAULT_AGENT=pi ./vibes

# Open in browser
open http://localhost:8080

Installation

From source (recommended)

make build    # frontend bundle + embedded Go binary

This produces a fully self-contained binary with all HTML, CSS, JS, fonts, and icons embedded at compile time via //go:embed.

Cross-compile

make build-linux-arm64    # Raspberry Pi, ARM Proxmox
make build-darwin-arm64   # macOS Apple Silicon
make build-all            # all platforms

Docker

# Local build
docker build -t vibes .
docker run -p 8080:8080 vibes

# Prebuilt release images from GHCR
docker pull ghcr.io/rcarmo/vibes:vX.Y.Z
docker run -p 8080:8080 ghcr.io/rcarmo/vibes:vX.Y.Z

The Dockerfile produces a scratch-based image (~24 MB) — just the binary + CA certificates. Release tags publish multi-arch images (linux/amd64, linux/arm64) to GHCR.

Agent binaries

Install the ACP agents you want to use:

npm install -g @github/copilot-language-server    # GitHub Copilot
npm install -g @openai/codex                       # OpenAI Codex (includes codex-acp)
npm install -g @agentclientprotocol/claude-agent-acp  # Claude
npm install -g pi-acp                              # Pi (ACP adapter)
npm install -g opencode-ai                         # OpenCode (free models)
npm install -g @mariozechner/pi-coding-agent       # Pi (native, for RPC mode)

Configuration

All configuration is via environment variables with VIBES_ prefix:

Variable	Default	Description
`VIBES_HOST`	`0.0.0.0`	Bind address
`VIBES_PORT`	`8080`	Port
`VIBES_DB_PATH`	`database/vibes.db`	SQLite database
`VIBES_DEBUG`	`false`	Verbose logging
`VIBES_COPILOT_AGENT`	`copilot-language-server --acp --stdio`	Copilot ACP command
`VIBES_COPILOT_ENABLED`	`true`	Enable Copilot backend discovery
`VIBES_CODEX_AGENT`	`codex-acp`	Codex ACP command
`VIBES_CODEX_ENABLED`	`true`	Enable Codex backend discovery
`VIBES_DEFAULT_AGENT`	`acp`	Default backend (`acp` is treated as `copilot` for compatibility)
`VIBES_PI_ENABLED`	`true`	Enable Pi native RPC discovery/probing (set `false` to disable)
`VIBES_PI_AGENT`	`pi`	Pi binary path
`VIBES_PERMISSION_TIMEOUT`	`30`	Permission request timeout (seconds)
`VIBES_PERMISSION_AUTO_APPROVE`	`false`	Auto-approve all tool calls
`VIBES_DISCONNECT_TIMEOUT`	`300`	Agent keepalive after last SSE client disconnects
`VIBES_ACP_DEBUG`	`false`	Wire-level ACP logging
`VIBES_ACP_MCP_SERVERS_JSON`	(unset)	JSON array of ACP MCP servers to pass to ACP sessions (`stdio` supported; `http`/`sse` filtered by negotiated agent capabilities)
`VIBES_EXTENSIONS_DIR`	`extensions`	Extension scan directory
`VIBES_CORS_ALLOW_ORIGIN`	(unset)	Enable CORS for a specific origin (or `*`)
`VIBES_API_TOKEN`	(unset)	Optional API token for sensitive/mutating routes (`X-API-Token` or `Authorization: Bearer`)
`VIBES_ENABLE_TERMINAL`	`false`	Enable terminal WebSocket endpoint (`/terminal/ws`)
`VIBES_ENABLE_PPROF`	`false`	Enable pprof endpoints under `/debug/pprof` (guarded by token when set)

See docs/CONFIGURATION.md for full reference, including ACP MCP server JSON examples and current ACP client-service limitations.

Security hardening (recommended for remote deployments)

# Require token auth on sensitive/mutating endpoints
export VIBES_API_TOKEN="change-me"

# Restrict browser CORS to your UI origin
export VIBES_CORS_ALLOW_ORIGIN="https://your-ui.example"

# Keep dangerous debug/shell surfaces disabled unless needed
export VIBES_ENABLE_TERMINAL=false
export VIBES_ENABLE_PPROF=false

Architecture

System diagram

┌─────────────────────────────────────────────────────────────────┐
│                         Browser (SPA)                            │
│  Preact + HTM │ CodeMirror 6 │ KaTeX │ Mermaid │ SSE client     │
└────────────────────────────────┬────────────────────────────────┘
                                 │ HTTP + SSE
┌────────────────────────────────┴────────────────────────────────┐
│                       Go HTTP Server (chi)                        │
│                                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │ Timeline │ │  Media   │ │Workspace │ │  Agents  │           │
│  │  Routes  │ │  Routes  │ │  Routes  │ │  Routes  │           │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘           │
│       │             │            │             │                  │
│  ┌────┴─────────────┴────────────┴─────────────┴──────────────┐  │
│  │              SQLite (WAL, FTS5, JSON columns)               │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌───────────────┐        ┌────────────────────────────────────┐  │
│  │   SSE Broker  │◄──────►│         Agent Registry             │  │
│  │  (per-client  │        │  ┌─────────┐  ┌─────────┐         │  │
│  │   buffered    │        │  │   ACP   │  │   Pi    │         │  │
│  │   fanout)     │        │  │Provider │  │Provider │         │  │
│  └───────────────┘        │  └────┬────┘  └────┬────┘         │  │
│                            │       │            │               │  │
│  ┌───────────────┐        │  ┌────┴────────────┴────┐         │  │
│  │  Extensions   │        │  │  Subprocess Manager   │         │  │
│  │  (registry)   │        │  └────┬─────────────────┘         │  │
│  └───────────────┘        └───────┼────────────────────────────┘  │
└───────────────────────────────────┼──────────────────────────────┘
                                    │ stdio (JSON-RPC / NDJSON)
                   ┌────────────────┼────────────────┐
                   ▼                ▼                ▼
          ┌──────────────┐  ┌────────────┐  ┌────────────┐
          │copilot-lang- │  │  codex-acp │  │claude-agent│
          │server --acp  │  │            │  │   -acp     │
          └──────────────┘  └────────────┘  └────────────┘
                                    │
                            ┌───────┴────────┐
                            │   pi --mode    │
                            │     rpc        │
                            └────────────────┘

Request flow: user message → agent response

1. User types message in compose box
2. Frontend POSTs to /agent/default/message
3. Server stores user message in SQLite
4. Server broadcasts "new_post" via SSE
5. Server spawns prompt on the active AgentProvider (async)
6. Agent streams events on stdout:
   - ACP: session/update notifications (draft/thought/tool_call)
   - Pi: NDJSON events (text_delta/thinking_delta/tool_execution)
7. Provider routes events → SSE broker → all connected clients
8. Frontend renders streaming draft/thought/status panels
9. Agent completes turn → final response stored in SQLite
10. Server broadcasts "agent_response" via SSE
11. Frontend renders final message in timeline

Data flow: SSE event types

Server → Client (text/event-stream):

  connected          Connection established
  new_post           User posted a message
  agent_draft        Streaming text from agent
  agent_thought      Agent thinking/reasoning stream
  agent_status       Tool call / status update
  agent_session_update  ACP session metadata/usage update
  agent_response     Final agent response (turn complete)
  agent_request      Permission request (approve/deny)
  agent_request_timeout  Permission timed out
  agent_error        Agent error
  interaction_updated    Post metadata changed
  interaction_deleted    Post removed

Implementation choices

Why Go

Concern	Python (original)	Go (this port)
Deployment	virtualenv + pip + Python runtime	Single static binary
Memory	~80 MB baseline (Python + aiohttp)	~15 MB baseline
Boot time	2–3s (Python import chain)	<100 ms
Cross-compile	Not practical	Makefile targets such as `make build-linux-arm64`
Concurrency	asyncio (single thread)	Goroutines (multi-core)
SQLite binding	C extension (requires build tools)	Pure Go (`modernc.org/sqlite`)
Asset delivery	Separate static directory	Embedded via `//go:embed`
Container	~200 MB Python image	~24 MB scratch image

Why chi (not Gin/Fiber/Echo)

stdlib net/http compatible — works with any middleware
Minimal API surface, no framework lock-in
Context-based routing with URL parameters
No reflection, no code generation

Why modernc.org/sqlite (not go-sqlite3)

Pure Go — no CGo, no C compiler needed at build time
Enables CGO_ENABLED=0 for truly static binaries
Enables cross-compilation without C toolchain
Same SQLite feature set (WAL, FTS5, JSON functions, virtual columns)
~10% slower than CGo version — acceptable for a single-user app

Why embed.FS (not external static directory)

Single binary deployment — copy one file, run it
No "missing static files" errors in production
Atomic updates (binary = code + assets together)
Same pattern as rcarmo/webterm
Trade-off: rebuild binary to update frontend (use make build)

ACP library: keepmind9/acp-sdk-go

Full typed schema for all ACP types (content blocks, tool calls, sessions)
ClientSideConnection with notification/request handlers
transport.Spawn for subprocess lifecycle
Contrib helpers: ToolCallTracker, PermissionBroker, SessionAccumulator
The only Go ACP SDK with schema parity as of April 2026

Extension system design

Inspired by piclaw's extension architecture:

type Extension interface {
    ID() string
    Name() string
    Version() string
    Init(ctx context.Context) error
    Shutdown(ctx context.Context) error
    Routes() []Route           // HTTP routes to mount
    EventTypes() []string      // SSE event types emitted
    StaticDir() string         // Static assets (/ext/{id}/)
    Manifest() *Manifest       // Frontend UI panels
}

type Manifest struct {
    Panels []PanelDef  // sidebar, main, overlay, toolbar
    CSS    []string    // CSS to inject
    JS     []string    // JS to load
}

Extensions can:

Register backend API routes (mounted on chi router)
Emit custom SSE event types
Serve static assets under /ext/{id}/
Declare frontend UI panels (sidebar, toolbar, overlays, main area)

Project structure

vibes/
├── cmd/
│   ├── vibes/main.go                 # Entry point
│   └── acp-test/main.go             # ACP agent verification tool
├── internal/
│   ├── app/app.go                    # Application wiring (chi + DB + agents + SSE)
│   ├── config/config.go              # Environment-based configuration
│   ├── db/
│   │   ├── db.go                     # SQLite open + WAL + connection management
│   │   ├── migrations.go            # Schema v1 (interactions, media, whitelist, FTS5)
│   │   ├── queries.go               # Typed CRUD + search + whitelist
│   │   ├── db_test.go               # 11 unit tests
│   │   └── db_fuzz_test.go          # 3 fuzz targets
│   ├── agent/
│   │   ├── provider.go              # Provider interface + Registry
│   │   ├── provider_test.go         # Registry tests
│   │   ├── acp/client.go            # ACP client (wraps acp-sdk-go)
│   │   └── pi/
│   │       ├── client.go            # Pi native RPC client
│   │       └── client_test.go       # Event routing tests
│   ├── server/sse/
│   │   ├── broker.go                # SSE connection management + fanout
│   │   └── broker_test.go           # Subscribe/broadcast/HTTP tests
│   ├── routes/
│   │   ├── timeline.go              # GET/POST/DELETE timeline, thread, search
│   │   ├── media.go                 # Upload, serve, thumbnail, info
│   │   ├── workspace.go             # Tree, file CRUD, rename, download, upload
│   │   ├── agents.go                # List, status, message, whitelist
│   │   ├── commands.go              # Slash commands (/model, /shell, etc.)
│   │   ├── opengraph.go             # Link preview fetcher
│   │   ├── permissions.go           # Permission broker + follow-up queue
│   │   ├── routes_test.go           # 12 route tests
│   │   ├── routes_fuzz_test.go      # Path traversal + parsing fuzz
│   │   ├── commands_test.go         # Command dispatch tests
│   │   └── permissions_test.go      # Queue + shell + permission tests
│   └── extensions/
│       ├── registry.go              # Extension discovery + lifecycle
│       ├── registry_test.go         # Registration + manifest tests
│       └── registry_fuzz_test.go    # ID fuzzing
├── static/                           # Frontend (embedded at compile time)
│   ├── index.html                    # SPA entry point
│   ├── manifest.json                 # PWA manifest
│   ├── css/styles.css                # Main stylesheet/base rules
│   ├── css/components/               # Per-component CSS split-outs
│   ├── dist/app.{js,css}            # Bundled frontend (Bun)
│   ├── js/                           # Source modules (Preact + HTM)
│   │   ├── app.js                    # Root SPA component
│   │   ├── api.js                    # API client
│   │   ├── components/               # UI components
│   │   ├── panes/                    # Popout editor
│   │   └── vendor/                   # Vendored Preact, CodeMirror, KaTeX
│   └── fonts/                        # KaTeX math fonts
├── tests/features/*.feature          # BDD user stories (Gherkin)
├── tests/steps/*.spec.mjs            # Playwright implementations (46 scenarios)
├── config/endpoints.json             # Custom action definitions
├── docs/                             # Protocol and integration docs
├── embed.go                          # //go:embed all:static
├── Dockerfile                        # Multi-stage: builder → scratch
├── Makefile                          # build, test, fuzz, lint, e2e, cross-compile
├── playwright.config.mjs
├── go.mod / go.sum
├── GO_PORT.md                        # Architecture deep-dive
└── LICENSE                           # MIT

API endpoints

Method	Endpoint	Description
GET	`/health`	Health check
GET	`/timeline`	Paginated posts (newest first)
POST	`/post`	Create post
DELETE	`/post/{id}`	Delete post (optional cascade)
GET	`/thread/{id}`	Get thread
POST	`/thread`	Reply to thread
GET	`/search?q=`	Full-text search
POST	`/media/upload`	Upload media file
GET	`/media/{id}`	Serve media
GET	`/media/{id}/thumbnail`	Serve thumbnail
GET	`/media/{id}/info`	Media metadata
GET	`/workspace/tree`	File tree
GET	`/workspace/file?path=`	Read file content (includes `mtime`)
PUT	`/workspace/file`	Write file (optional optimistic-lock `mtime`)
DELETE	`/workspace/file?path=`	Delete file
POST	`/workspace/create`	Create file/directory
POST	`/workspace/rename`	Rename/move
GET	`/workspace/raw?path=`	Raw file download
GET	`/workspace/download?path=`	Download file/dir (ZIP)
POST	`/workspace/upload`	Upload to workspace
GET	`/agents`	List agents and backend provider metadata
GET	`/agent/providers`	Backend discovery/capability map
GET/POST	`/thread/{id}/backend`	Read or switch thread backend affinity
GET	`/agent/status`	Current agent state
GET	`/agent/context`	Context window usage
GET	`/agent/commands`	List slash commands
POST	`/agent/{id}/message`	Send message to agent
GET	`/agent/whitelist`	List permission patterns
POST	`/agent/whitelist`	Add pattern
DELETE	`/agent/whitelist`	Remove pattern
POST	`/agent/respond`	Respond to permission request
GET	`/avatar/{kind}`	Agent/user avatar
GET	`/sse/stream`	SSE event stream
GET	`/terminal/ws`	Terminal WebSocket (only when `VIBES_ENABLE_TERMINAL=true`)
GET	`/debug/pprof/*`	pprof profiling endpoints (only when `VIBES_ENABLE_PPROF=true`)

Development

make help            # Show all targets
make build           # Full build (frontend + Go binary)
make dev             # Run from source with debug logging
make serve           # Build and run
make test            # Unit tests
make race            # Race detector
make coverage        # Coverage report
make fuzz            # All 9 fuzz targets
make check           # lint + test + coverage
make test-acp        # Verify ACP agent handshakes
make e2e             # Playwright BDD UX suite + PDF report
make build-all       # Cross-compile (linux-amd64, linux-arm64, darwin-arm64)
make clean           # Remove artifacts

Test suite

Layer	Tests	Coverage
`internal/config`	3 unit + 3 fuzz	100%
`internal/agent`	6 unit	100%
`internal/agent/pi`	4 unit	20%
`internal/extensions`	7 unit + 1 fuzz	96%
`internal/server/sse`	4 unit	85%
`internal/db`	11 unit + 3 fuzz	79%
`internal/routes`	20 unit + 2 fuzz	41%
Total	55+ tests, 9 fuzz targets	52%

Plus 46 Playwright BDD scenarios for end-to-end UX validation.

Keyboard shortcuts

Shortcut	Action
`Cmd/Ctrl+S`	Save current editor tab
`Cmd/Ctrl+F`	Search/replace in editor
`Escape`	Close active editor tab
`Alt+V`	Toggle Vim mode
`Alt+W`	Toggle whitespace visibility
`↑` / `↓`	Cycle compose history

Python version

The original Python implementation (aiohttp, 388 unit tests, 34 E2E tests) is on the python branch:

pip install -U git+https://github.com/rcarmo/vibes.git@python

The Go and Python versions share the same frontend, API, SSE events, and SQLite schema — they are interchangeable.

License

MIT

Navigation Menu

Repository files navigation

Vibes

Features

Verified ACP agents

Capability matrix

Quick start

Installation

From source (recommended)

Cross-compile

Docker

Agent binaries

Configuration

Security hardening (recommended for remote deployments)

Architecture

System diagram

Request flow: user message → agent response

Data flow: SSE event types

Implementation choices

Why Go

Why chi (not Gin/Fiber/Echo)

Why modernc.org/sqlite (not go-sqlite3)

Why embed.FS (not external static directory)

ACP library: keepmind9/acp-sdk-go

Extension system design

Project structure

API endpoints

Development

Test suite

Keyboard shortcuts

Python version

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 564 Commits
.github		.github
cmd		cmd
config		config
docs		docs
internal		internal
scripts		scripts
static		static
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
GO_PORT.md		GO_PORT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SPEC.md		SPEC.md
build.js		build.js
bun.lock		bun.lock
embed.go		embed.go
eslint.config.js		eslint.config.js
go.mod		go.mod
go.sum		go.sum
package.json		package.json
playwright.config.mjs		playwright.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Vibes

Features

Verified ACP agents

Capability matrix

Quick start

Installation

From source (recommended)

Cross-compile

Docker

Agent binaries

Configuration

Security hardening (recommended for remote deployments)

Architecture

System diagram

Request flow: user message → agent response

Data flow: SSE event types

Implementation choices

Why Go

Why chi (not Gin/Fiber/Echo)

Why modernc.org/sqlite (not go-sqlite3)

Why embed.FS (not external static directory)

ACP library: keepmind9/acp-sdk-go

Extension system design

Project structure

API endpoints

Development

Test suite

Keyboard shortcuts

Python version

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages