Development Guide

This document describes how to contribute code to VibeCoding.

Development Environment Setup

System Requirements

Go 1.24+
Git
Make (optional)
bubblewrap (optional, for sandbox testing)

Get Source Code

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

Install Dependencies

go mod download

Build Project

# Build
make build

# Install to $GOPATH/bin
make install

Run Tests

# Run all tests
make test

# Run tests for specific package
go test ./internal/tools/

# Run specific test
go test -run TestReadTool ./internal/tools/

Project Structure

vibecoding/
├── cmd/vibecoding/          # CLI entry point
│   └── main.go
├── internal/
│   ├── agent/               # Core Agent loop
│   │   ├── agent.go         # Agent main logic
│   │   ├── events.go        # Event type definitions
│   │   ├── provider.go      # Provider adapter
│   │   └── system_prompt.go # System prompt generation
│   ├── config/              # Configuration management
│   ├── contextfiles/        # Context file loading
│   ├── provider/            # LLM Provider abstraction
│   │   ├── provider.go      # Provider interface
│   │   ├── anthropic/       # Anthropic implementation
│   │   └── openai/          # OpenAI implementation
│   ├── sandbox/             # Sandbox implementation
│   ├── session/             # Session management
│   ├── skills/              # Skills system
│   ├── tools/               # Tool implementations
│   │   ├── tool.go          # Tool interface and registration
│   │   ├── bash.go          # Bash command
│   │   ├── read.go          # File reading
│   │   ├── write.go         # File writing
│   │   ├── edit.go          # File editing
│   │   ├── grep.go          # Content search
│   │   ├── find.go          # File finding
│   │   └── ls.go            # Directory listing
│   ├── tui/                 # Terminal UI
│   └── util/                # Utility functions
└── pkg/sdk/                 # Public SDK (future)

Core Interfaces

Provider Interface

type Provider interface {
    Name() string
    Models() []*Model
    GetModel(id string) *Model
    Chat(ctx context.Context, params ChatParams) <-chan StreamEvent
}

Tool Interface

type Tool interface {
    Name() string
    Description() string
    Parameters() json.RawMessage
    Execute(ctx context.Context, params json.RawMessage) (string, error)
}

Adding New Tools

Step 1: Create Tool File

// internal/tools/mytool.go
package tools

import (
    "context"
    "encoding/json"
)

type MyTool struct {
    workdir string
}

func NewMyTool(workdir string) *MyTool {
    return &MyTool{workdir: workdir}
}

func (t *MyTool) Name() string {
    return "mytool"
}

func (t *MyTool) Description() string {
    return "Description of my tool"
}

func (t *MyTool) Parameters() json.RawMessage {
    return json.RawMessage(`{
        "type": "object",
        "properties": {
            "param1": {
                "type": "string",
                "description": "First parameter"
            }
        },
        "required": ["param1"]
    }`)
}

func (t *MyTool) Execute(ctx context.Context, params json.RawMessage) (string, error) {
    var p struct {
        Param1 string `json:"param1"`
    }
    if err := json.Unmarshal(params, &p); err != nil {
        return "", err
    }
    // Implement tool logic
    return "result", nil
}

Step 2: Register Tool

In internal/tools/tool.go's RegisterDefaults() method:

func (r *Registry) RegisterDefaults() {
    r.Register(&ReadTool{workdir: r.workdir})
    r.Register(&WriteTool{workdir: r.workdir})
    r.Register(&EditTool{workdir: r.workdir})
    r.Register(&BashTool{workdir: r.workdir, sandbox: r.sandbox})
    r.Register(&GrepTool{workdir: r.workdir})
    r.Register(&FindTool{workdir: r.workdir})
    r.Register(&LsTool{workdir: r.workdir})
    r.Register(&MyTool{workdir: r.workdir}) // Add new tool
}

Step 3: Update System Prompt

Add tool description in internal/agent/system_prompt.go.

Step 4: Write Tests

// internal/tools/mytool_test.go
package tools

import (
    "context"
    "testing"
)

func TestMyTool_Execute(t *testing.T) {
    tool := NewMyTool("/tmp")
    params := `{"param1": "value"}`
    
    result, err := tool.Execute(context.Background(), json.RawMessage(params))
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
    
    if result != "expected" {
        t.Errorf("expected 'expected', got '%s'", result)
    }
}

Adding Provider Support

Most new services should be added as vendor adapters, not new protocol providers. If the service speaks OpenAI Chat Completions or Anthropic Messages, reuse the generic provider and register vendor defaults in internal/provider.

Add an OpenAI/Anthropic-Compatible Vendor

Create internal/provider/vendor_myvendor.go.
Register URL detection and defaults with RegisterVendorAdapter.
Add model compat flags only for behavior that differs from the generic protocol.
Add focused tests in internal/provider and, if request formatting changes, in internal/provider/openai or internal/provider/anthropic.

package provider

func init() {
    RegisterVendorAdapter(simpleVendorAdapter{
        name:           "myvendor",
        domains:        []string{"api.myvendor.example"},
        thinkingFormat: "deepseek", // optional
        defaultAPI:     "openai-chat",
    })
}

Provider creation for CLI and ACP goes through internal/provider/factory, so do not add vendor-specific creation code to cmd/vibecoding/main.go or internal/acp/acp.go.

Add a New Protocol Provider

Only add a new provider package when the service has a native protocol that is not covered by OpenAI Chat Completions or Anthropic Messages.

Create internal/provider/myprotocol.
Implement provider.Provider.
Add construction support in internal/provider/factory.
Keep settings JSON compatibility stable.
Add provider and factory tests.

Testing

Run All Tests

make test

Run Tests for Specific Package

go test ./internal/agent/
go test ./internal/tools/

Generate Coverage Report

go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Code Standards

Formatting

make fmt

Or manually:

gofmt -w .
goimports -w .

Linting

make lint

Naming Conventions

Package names: lowercase words, e.g., tools, agent
Interface names: verbs or nouns, e.g., Provider, Tool
Struct names: PascalCase, e.g., ReadTool, AgentConfig
Function names: PascalCase, e.g., NewAgent, Execute
Variable names: camelCase, e.g., workdir, maxTokens

Error Handling

// Good practice
result, err := doSomething()
if err != nil {
    return fmt.Errorf("do something: %w", err)
}

// Bad practice
result, _ := doSomething()

Git Workflow

Commit Convention

Use Conventional Commits:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation
refactor: Refactoring
test: Tests
chore: Miscellaneous

Examples:

feat(tools): add new search tool
fix(agent): fix streaming issue
docs(readme): update installation guide

Pull Request

Fork project
Create feature branch
Commit changes
Run tests
Create Pull Request

Debugging

Enable Debug Logging

vibecoding --debug

Using dlv

# Install dlv
go install github.com/go-delve/delve/cmd/dlv@latest

# Debug
dlv debug ./cmd/vibecoding -- --debug

Release Process

Version Numbers

Use Semantic Versioning:

MAJOR.MINOR.PATCH

Example: 1.0.0, 1.1.0, 1.0.1

Create Release

# Update version number
git tag -a v1.0.0 -m "Release v1.0.0"

# Push tags
git push --tags

# Build release packages
make build-all

Publish to npm

# Publish release version
make npm-publish

# Publish pre-release version
make npm-publish-pre

Users can install via npm:

npm install -g vibecoding-installer

Frequently Asked Questions

Q: How to add a new tool?

A: See Adding New Tools section.

Q: How to add a new Provider?

A: See Adding New Providers section.

Q: What to do if tests fail?

Check Go version
Run go mod tidy
Check error logs

Q: How to debug sandbox issues?

Use --debug flag
Check if bwrap is installed: bwrap --version
Check system logs

FilesExpand file tree

development.md

Latest commit

History