Skip to content

README.md

Latest commit

 

History

History
289 lines (226 loc) · 7.96 KB

README.md

File metadata and controls

289 lines (226 loc) · 7.96 KB

VibeCoding

VibeCoding

A terminal-based AI coding assistant written in ~10,000 lines of Go, inspired by pi.dev

Features

  • Multi-Provider Support: DeepSeek (default), OpenAI, Anthropic, and any custom provider via OpenAI/Anthropic-compatible APIs
  • SSE Streaming: Real-time token streaming for fast response delivery
  • Think Mode: Extended thinking/reasoning support (DeepSeek reasoning)
  • Three Modes:
    • 🗒️ Plan — Read-only analysis and planning. Sandboxed, no file writes
    • 🔧 Agent (default) — Controlled read/write access to the project. Bash requires approval (configurable whitelist). Sandboxed, no network
    • 🚀 YOLO — Full system access with no restrictions
  • bwrap Sandbox: Linux sandboxing via bubblewrap for secure execution
  • Session Management: JSONL-based session files with tree structure, branching, compaction
  • Context Management: Automatic context window management and token estimation
  • Rich TUI: Terminal UI built with BubbleTea, with Markdown rendering and code highlighting
  • Cache Hit Rate: Real-time cache hit percentage display in footer, with per-turn cache statistics
  • ACP Support: Run as an Agent Client Protocol (ACP) stdio agent for editor integrations and compatible clients, including VS Code, Zed, and JetBrains IDEs such as IntelliJ IDEA/WebStorm via ACP-compatible plugins

Quick Start

Install

Option 1: npm (Recommended)

npm install -g vibecoding-installer

Option 2: One-line Install

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/startvibecoding/vibecoding/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/startvibecoding/vibecoding/main/install.ps1 | iex

Or with custom install directory:

# Linux/macOS
INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/startvibecoding/vibecoding/main/install.sh | bash

# Windows
$env:VIBECODING_INSTALL_DIR="C:\Tools\vibecoding"; irm https://raw.githubusercontent.com/startvibecoding/vibecoding/main/install.ps1 | iex

Option 3: Go Install

go install github.com/startvibecoding/vibecoding/cmd/vibecoding@latest

Option 4: Build from Source

git clone https://github.com/startvibecoding/vibecoding.git
cd vibecoding
make build

Cross-compile

make build-all    # Build for linux/amd64, darwin/amd64, darwin/arm64, windows/amd64

Configure

Set your API key:

# DeepSeek
export DEEPSEEK_API_KEY=sk-...

Or configure directly in settings.json:

{
  "providers": {
    "deepseek-openai": { "apiKey": "sk-..." }
  }
}

Run

# Interactive mode
vibecoding

# With initial prompt
vibecoding "Explain this codebase"

# Non-interactive (print mode)
vibecoding -p "Write a hello world in Go"

# Specify provider and model
vibecoding --provider deepseek-openai --model deepseek-v4-flash

# Change mode
vibecoding --mode plan    # Read-only planning
vibecoding --mode agent   # Standard (default)
vibecoding --mode yolo    # Full access

# Continue most recent session
vibecoding -c

# Disable sandbox
vibecoding --no-sandbox

Configuration

Settings Files

Location Platform Scope
~/.vibecoding/settings.json Linux/macOS Global (all projects)
%APPDATA%\vibecoding\settings.json Windows Global (all projects)
.vibe/settings.json All Project (overrides global)

Windows users: %APPDATA% resolves to C:\Users\<Username>\AppData\Roaming.

Example Settings

{
  "defaultProvider": "deepseek-openai",
  "defaultModel": "deepseek-v4-flash",
  "defaultThinkingLevel": "medium",
  "defaultMode": "agent",
  "maxContextTokens": 1000000,
  "maxOutputTokens": 384000,
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "sandbox": {
    "enabled": true,
    "level": "standard",
    "allowNetwork": false
  },
  "contextFiles": {
    "enabled": true
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000
  },
  "approval": {
    "bashWhitelist": ["go ", "make ", "git ", "npm ", "yarn "],
    "bashBlacklist": ["rm -rf", "sudo"]
  }
}

Environment Variables

Variable Description
DEEPSEEK_API_KEY DeepSeek API key
VIBECODING_DIR Override config directory
VIBECODING_PROVIDER Override default provider
VIBECODING_MODEL Override default model
VIBECODING_MODE Override default mode
VIBECODING_THINKING Override default thinking level
VIBECODING_USER_AGENT Custom User-Agent string

Sandbox Security

VibeCoding uses bubblewrap for Linux sandboxing.

Mode File System Network bwrap
Plan (strict) Project read-only ✗ ✓
Agent (standard) Project read-write ✗ ✓
YOLO (none) Full access ✓ ✗

Installing bwrap

# Debian/Ubuntu
sudo apt install bubblewrap

# Fedora
sudo dnf install bubblewrap

# Arch
sudo pacman -S bubblewrap

CLI Reference

vibecoding [flags] [message...]
Aliases: vc

Flags:
  -p, --provider string    Provider (deepseek-openai, deepseek-anthropic, or custom provider name)
  -m, --model string       Model ID
  -M, --mode string        Mode (plan, agent, yolo)
  -t, --thinking string    Thinking level (off, minimal, low, medium, high, xhigh)
  -c, --continue           Continue most recent session
  -r, --resume string      Resume session by ID or path
      --session string     Use specific session file or ID
      --sandbox            Enable sandbox (bwrap) for secure execution
  -P, --print              Print response and exit (non-interactive)
      --verbose            Verbose output
      --debug              Enable debug logging
  -v, --version            Show version
  -h, --help               Show help

Interactive Commands

Command Description
/mode [plan|agent|yolo] Switch mode
/model Show current model
/think Cycle thinking level
/skills List loaded skills
/clear Clear conversation
/help Show help
/quit Exit

Keyboard Shortcuts

Key Action
Ctrl+C Abort / Clear input
Ctrl+D Quit
Tab Cycle thinking level
Ctrl+T Toggle thinking display

Development

make build      # Build binary
make test       # Run tests
make lint       # Run linter
make fmt        # Format code
make clean      # Clean build artifacts
make build-all  # Cross-compile for all platforms
make dist       # Build distribution packages (.deb, .tar.gz)

Architecture

vibecoding/
├── cmd/vibecoding/        # CLI entry point
├── internal/
│   ├── agent/             # Core agent loop
│   ├── config/            # Configuration system
│   ├── context/           # Context management and token estimation
│   ├── contextfiles/      # Context file discovery (AGENTS.md, CLAUDE.md, etc.)
│   ├── platform/          # Cross-platform compatibility utilities
│   ├── provider/          # LLM provider abstraction
│   │   ├── openai/        # OpenAI Chat Completions API
│   │   └── anthropic/     # Anthropic Messages API
│   ├── sandbox/           # Sandbox (bwrap) implementation
│   ├── session/           # Session management (JSONL)
│   ├── skills/            # Skills system
│   ├── tools/             # Tool implementations
│   ├── tui/               # Terminal UI (BubbleTea)
│   └── ua/                # User-Agent string generation
└── pkg/sdk/               # Public SDK interface

License

MIT