README
¶
vibekit
A browser-based front-end for the Kiro CLI — chat with an AI coding agent from any device, with shared sessions, a live terminal, an editor, and git/forge workflows.
What it is
Vibekit is a Go web server that drives kiro-cli over the Agent Client Protocol (ACP). Each active chat runs one kiro-cli acp subprocess (the "bridge"); multiple devices and tabs on the same chat share it. The server is the single source of truth and the client is a pure projection of server state — every mutation goes through POST /api/command and is echoed back over SSE, so there is no optimistic local rendering and no multi-device drift.
Features
- Multi-device chat — open the same conversation on phone and desktop; both stay in sync via SSE fan-out. One JSON file per chat, atomic writes, full history.
- Streaming with reasoning — token-by-token markdown rendering with a collapsible "thinking" block, batched for smoothness.
- Live terminal — a real PTY shell in the browser (powered by
@cplieger/vterm) plus per-agent command terminals. - Editor + diff + conflict views — read/edit workspace files, view tool-call diffs, resolve merge conflicts inline.
- Checkpoints — a content-addressed per-file snapshot system with two-phase atomic restore and cross-chat conflict detection (independent of git).
- Supervised mode — a per-chat write-gate that stages every agent file write for per-hunk accept/reject/merge before it touches disk.
- Subagent crew monitor, rewind (branch a chat from a past turn), MCP integration (add/configure MCP servers from the UI), and git + forge workflows (GitHub/GitLab/Gitea via the first-party
gh/glab/teaCLIs — PRs, issues, releases). - PWA with web-push notifications for turn-complete and permission prompts.
Run it
# compose.yaml
services:
vibekit:
image: ghcr.io/cplieger/vibekit:latest
ports:
- "8080:8080"
volumes:
- ./config:/config # chats, kiro-cli auth/state, tools
- ./workspace:/workspace # your repos
restart: unless-stopped
kiro-cli is downloaded and pinned on first boot (it is not redistributed in the image, per the AWS Customer Agreement). On first launch, authenticate kiro-cli and start chatting.
Security
Network-exposed: put it behind an authenticating reverse proxy — vibekit has its own password/OIDC auth, but it controls an agent with shell and filesystem access to /workspace. Web-push uses an SSRF-hardened transport. Debian base (a shell + the kiro-cli subprocess are required, so this is not distroless). Images are published with cosign signatures and SBOM attestations.
License
GPL-3.0. See LICENSE.
Documentation
¶
Overview ¶
Vibekit for Kiro: ACP-based web interface for kiro-cli.
One kiro-cli subprocess per active chat; multiple browsers on the same chat share the same bridge and context. Server is the source of truth; the browser projects server state via SSE + GET /api/chats.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
wire-codegen
command
Command wire-codegen generates TypeScript interfaces, validating decoders, and an SSE event→decoder registry from Go wire types using the wiregen library (AST-based; github.com/cplieger/wiregen).
|
Command wire-codegen generates TypeScript interfaces, validating decoders, and an SSE event→decoder registry from Go wire types using the wiregen library (AST-based; github.com/cplieger/wiregen). |
|
internal
|
|
|
api
Package api defines the internal contracts between vibekit components.
|
Package api defines the internal contracts between vibekit components. |
|
auth
Package auth wires the /api/whoami, /api/login, /api/logout endpoints that shell out to the bundled kiro-cli binary for identity operations.
|
Package auth wires the /api/whoami, /api/login, /api/logout endpoints that shell out to the bundled kiro-cli binary for identity operations. |
|
bridge
Package bridge manages a single kiro-cli ACP subprocess.
|
Package bridge manages a single kiro-cli ACP subprocess. |
|
buffer
Package buffer provides the per-chat assistant turn buffering subsystem.
|
Package buffer provides the per-chat assistant turn buffering subsystem. |
|
chat
Package chat implements per-chat persistence: one JSON file per chat under <dir>/<chat_id>.json.
|
Package chat implements per-chat persistence: one JSON file per chat under <dir>/<chat_id>.json. |
|
chat/archive
Package archive implements the chat archive lifecycle: move to archive, list, restore, update summary, delete, and age-based purge.
|
Package archive implements the chat archive lifecycle: move to archive, list, restore, update summary, delete, and age-based purge. |
|
checkpoint/gc
Package gc implements the blob garbage collector for the checkpoint subsystem.
|
Package gc implements the blob garbage collector for the checkpoint subsystem. |
|
checkpoint/types
Package types defines checkpoint domain types shared between the checkpoint implementation and its consumers (api, hub).
|
Package types defines checkpoint domain types shared between the checkpoint implementation and its consumers (api, hub). |
|
command
Package command implements the POST /api/command dispatch table.
|
Package command implements the POST /api/command dispatch table. |
|
dedup
Package dedup provides a bounded, TTL-based idempotency cache for deduplicating repeated requests by request ID.
|
Package dedup provides a bounded, TTL-based idempotency cache for deduplicating repeated requests by request ID. |
|
filehandler
Package filehandler provides HTTP endpoints for browsing, reading, editing, uploading, and downloading files.
|
Package filehandler provides HTTP endpoints for browsing, reading, editing, uploading, and downloading files. |
|
forges
Package forges integrates remote git forges (GitHub, GitLab, Gitea/Codeberg) by orchestrating their first-party CLI tools (gh, glab, tea).
|
Package forges integrates remote git forges (GitHub, GitLab, Gitea/Codeberg) by orchestrating their first-party CLI tools (gh, glab, tea). |
|
forges/cliexec
Package cliexec provides CLI subprocess execution with structured output capture, size-capped buffers, and typed errors.
|
Package cliexec provides CLI subprocess execution with structured output capture, size-capped buffers, and typed errors. |
|
forges/gitea
Package gitea provides the Gitea/Codeberg ForgeOps implementation.
|
Package gitea provides the Gitea/Codeberg ForgeOps implementation. |
|
forges/github
Package github provides the GitHub ForgeOps implementation.
|
Package github provides the GitHub ForgeOps implementation. |
|
forges/gitlab
Package gitlab provides the GitLab ForgeOps implementation.
|
Package gitlab provides the GitLab ForgeOps implementation. |
|
forges/oauth
Package oauth implements the GitHub OAuth device flow protocol.
|
Package oauth implements the GitHub OAuth device flow protocol. |
|
gitexec
Package gitexec provides hardened git subprocess execution and credential scrubbing shared by the git and forges packages.
|
Package gitexec provides hardened git subprocess execution and credential scrubbing shared by the git and forges packages. |
|
hub
Package hub coordinates SSE connections, ACP bridge lifecycle, and POST /api/command dispatch.
|
Package hub coordinates SSE connections, ACP bridge lifecycle, and POST /api/command dispatch. |
|
ids
Package ids provides random identifier generation for stored records.
|
Package ids provides random identifier generation for stored records. |
|
logctl
Package logctl owns the process-wide slog handler so settings toggles can flip the log level at runtime without restarting the container.
|
Package logctl owns the process-wide slog handler so settings toggles can flip the log level at runtime without restarting the container. |
|
mcp
Package mcp persists and serves the user's configured MCP (Model Context Protocol) servers.
|
Package mcp persists and serves the user's configured MCP (Model Context Protocol) servers. |
|
mcp/prewarm
Package prewarm handles npx package pre-warming for MCP servers.
|
Package prewarm handles npx package pre-warming for MCP servers. |
|
pending
Package pending implements the staging store for Supervised mode.
|
Package pending implements the staging store for Supervised mode. |
|
permissions
Package permissions resolves kiro-cli permission args from the user's config.json.
|
Package permissions resolves kiro-cli permission args from the user's config.json. |
|
permissions/eval
Package eval implements the pure shell-command evaluation pipeline.
|
Package eval implements the pure shell-command evaluation pipeline. |
|
push/crypto
Package crypto provides RFC 8291 encryption helpers and VAPID JWT construction for Web Push.
|
Package crypto provides RFC 8291 encryption helpers and VAPID JWT construction for Web Push. |
|
server
Package server — REST Idempotency-Key dedup middleware.
|
Package server — REST Idempotency-Key dedup middleware. |
|
sessions
Package sessions manages kiro-cli session lockfiles on disk: stale lock detection, startup cleanup, PID-based liveness probes, and flock-based staleness checks.
|
Package sessions manages kiro-cli session lockfiles on disk: stale lock detection, startup cleanup, PID-based liveness probes, and flock-based staleness checks. |
|
settings
Package settings provides a single-source-of-truth reader for <configDir>/config.json.
|
Package settings provides a single-source-of-truth reader for <configDir>/config.json. |
|
steering
Package steering generates the environment.md steering file kiro-cli reads on every session.
|
Package steering generates the environment.md steering file kiro-cli reads on every session. |
|
testsupport
Package testsupport provides shared test fakes for interfaces defined in the api package.
|
Package testsupport provides shared test fakes for interfaces defined in the api package. |
|
translate
Package translate handles ACP → domain event translation.
|
Package translate handles ACP → domain event translation. |
|
version
Package version holds the single-source-of-truth build version string for vibekit.
|
Package version holds the single-source-of-truth build version string for vibekit. |
|
workspace
Path helpers for kiro-cli's per-user state directory.
|
Path helpers for kiro-cli's per-user state directory. |
Click to show internal directories.
Click to hide internal directories.