Merge pull request #35 from priyanshujain/cleanup-excessive-comments

Remove redundant comments across codebase

Author: priyanshujain

CLAUDE.md

@@ -1,3 +1,8 @@
+## Coding Guidelines
+
+  - Keep code simple and easy to read.
+  - Avoid excessive comments — only comment when absolutely necessary.
+
 ## Git Branch Rules
 
   - No slashes in branch names (e.g., use `fix-something` not `fix/something`).

agent/compact.go

@@ -8,8 +8,6 @@ import (
 
 const defaultMaxHistory = 40
 
-// compactHistory trims history to half of maxHistory when it exceeds maxHistory,
-// prepending a summary placeholder for the removed messages.
 func (a *Agent) compactHistory() {
 	if len(a.history) <= a.maxHistory {
 		return

agent/scrub.go

@@ -6,17 +6,12 @@ var credentialPattern = regexp.MustCompile(
 	`(?i)(token|api[_-]?key|password|secret|authorization)(\s*[:=]\s*)(\S+)`,
 )
 
-// bearerPattern matches "Bearer <token>" to scrub the actual token value.
 var bearerPattern = regexp.MustCompile(
 	`(?i)(Bearer\s+)(\S+)`,
 )
 
-// ScrubCredentials redacts credential values in strings like "TOKEN=abcdef"
-// or "api_key: sk-proj-abc". The label and separator are preserved; only the
-// value is replaced with a redacted form that keeps the first 4 characters.
 func ScrubCredentials(s string) string {
-	// Scrub Bearer tokens first (e.g. "Bearer eyJhbG...") before the
-	// credential pattern replaces the keyword that precedes them.
+	// Scrub Bearer tokens before the credential pattern replaces the keyword.
 	s = bearerPattern.ReplaceAllStringFunc(s, func(match string) string {
 		parts := bearerPattern.FindStringSubmatch(match)
 		if len(parts) < 3 {

daemon/lock_unix.go

@@ -8,8 +8,6 @@ import (
 	"syscall"
 )
 
-// acquireLock takes an exclusive file lock to prevent multiple daemon instances.
-// Returns the lock file which must be kept open for the lifetime of the daemon.
 func acquireLock() (*os.File, error) {
 	f, err := os.OpenFile(lockPath(), os.O_CREATE|os.O_RDWR, 0600)
 	if err != nil {
@@ -24,7 +22,6 @@ func acquireLock() (*os.File, error) {
 	return f, nil
 }
 
-// releaseLock releases the file lock and removes the lock file.
 func releaseLock(f *os.File) {
 	syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
 	f.Close()

daemon/lock_windows.go

@@ -20,13 +20,10 @@ const (
 	lockfileFailImmediately = 0x00000001
 )
 
-// lockHandle stores the Windows file handle obtained during acquireLock
-// so that releaseLock can unlock the same handle. On Windows, os.File.Fd()
-// returns a new duplicated handle on each call, so we must capture it once.
+// On Windows, os.File.Fd() returns a new duplicated handle on each call,
+// so we capture it once during acquireLock for use in releaseLock.
 var lockHandle uintptr
 
-// acquireLock takes an exclusive file lock to prevent multiple daemon instances.
-// Returns the lock file which must be kept open for the lifetime of the daemon.
 func acquireLock() (*os.File, error) {
 	f, err := os.OpenFile(lockPath(), os.O_CREATE|os.O_RDWR, 0600)
 	if err != nil {
@@ -51,7 +48,6 @@ func acquireLock() (*os.File, error) {
 	return f, nil
 }
 
-// releaseLock releases the file lock and removes the lock file.
 func releaseLock(f *os.File) {
 	ol := new(syscall.Overlapped)
 	procUnlockFileEx.Call(

internal/cli/setup.go

@@ -20,7 +20,6 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// gwsServices lists the Google Workspace services available via gws.
 var gwsServices = []string{"calendar", "drive", "docs", "sheets", "tasks", "people"}
 
 var setupCmd = &cobra.Command{
@@ -33,7 +32,6 @@ var setupCmd = &cobra.Command{
 
 		fmt.Print("\n  Welcome to OpenBotKit setup!\n\n")
 
-		// Step 1: Source selection.
 		var sources []string
 		sourceOptions := []huh.Option[string]{
 			huh.NewOption("LLM Models (for obk chat)", "models"),
@@ -113,7 +111,6 @@ var setupCmd = &cobra.Command{
 			return fmt.Errorf("save config: %w", err)
 		}
 
-		// Install skills based on current auth state.
 		fmt.Println("\n  -- Installing skills --")
 		result, err := skills.Install(cfg)
 		if err != nil {
@@ -151,7 +148,6 @@ func setupGoogle(cfg *config.Config) error {
 		return fmt.Errorf("create provider dir: %w", err)
 	}
 
-	// Credentials path.
 	defaultCredPath := cfg.GoogleCredentialsFile()
 	var credPath string
 
@@ -177,7 +173,6 @@ func setupGoogle(cfg *config.Config) error {
 		return fmt.Errorf("credentials file not found: %s", credPath)
 	}
 
-	// Save to config.
 	if cfg.Providers == nil {
 		cfg.Providers = &config.ProvidersConfig{}
 	}
@@ -186,7 +181,6 @@ func setupGoogle(cfg *config.Config) error {
 	}
 	cfg.Providers.Google.CredentialsFile = credPath
 
-	// Scope selection.
 	var scopes []string
 	err = huh.NewForm(
 		huh.NewGroup(
@@ -207,7 +201,6 @@ func setupGoogle(cfg *config.Config) error {
 		scopes = []string{"https://www.googleapis.com/auth/gmail.readonly"}
 	}
 
-	// OAuth flow.
 	gp := google.New(google.Config{
 		CredentialsFile: credPath,
 		TokenDBPath:     cfg.GoogleTokenDBPath(),
@@ -221,7 +214,6 @@ func setupGoogle(cfg *config.Config) error {
 
 	fmt.Printf("\n  Authenticated as %s\n", email)
 
-	// Sync window.
 	var syncDays string
 	err = huh.NewForm(
 		huh.NewGroup(
@@ -247,7 +239,6 @@ func setupGWS(cfg *config.Config, services []string) error {
 	fmt.Printf("\n  -- Google Workspace Setup (%s) --\n", strings.Join(services, ", "))
 	fmt.Println("  These services are powered by gws (Google Workspace CLI).")
 
-	// Check for gws binary.
 	gwsPath, err := exec.LookPath("gws")
 	if err != nil {
 		fmt.Println("\n  Checking for gws... not found.")
@@ -273,7 +264,6 @@ func setupGWS(cfg *config.Config, services []string) error {
 		fmt.Printf("  gws found at %s\n", gwsPath)
 	}
 
-	// Share credentials with gws.
 	credPath := cfg.GoogleCredentialsFile()
 	home, err := os.UserHomeDir()
 	if err != nil {
@@ -295,7 +285,6 @@ func setupGWS(cfg *config.Config, services []string) error {
 	}
 	fmt.Printf("  Shared credentials with gws (%s)\n", gwsCredPath)
 
-	// Run gws auth login.
 	scopeArg := strings.Join(services, ",")
 	fmt.Println("\n  Opening browser for Google Workspace access...")
 	authCmd := exec.Command(gwsPath, "auth", "login", "--scopes", scopeArg)
@@ -307,7 +296,6 @@ func setupGWS(cfg *config.Config, services []string) error {
 	}
 	fmt.Println("  Google Workspace authenticated.")
 
-	// Save to config.
 	if cfg.Integrations == nil {
 		cfg.Integrations = &config.IntegrationsConfig{}
 	}
@@ -316,7 +304,6 @@ func setupGWS(cfg *config.Config, services []string) error {
 	}
 	cfg.Integrations.GWS.Enabled = true
 
-	// Merge with existing services.
 	existing := make(map[string]bool)
 	for _, s := range cfg.Integrations.GWS.Services {
 		existing[s] = true
@@ -369,7 +356,6 @@ func isGWSService(s string) bool {
 	return false
 }
 
-// cleanPath handles drag-and-drop paths that may have quotes and whitespace.
 func cleanPath(s string) string {
 	s = strings.TrimSpace(s)
 	s = strings.Trim(s, "'\"")

oauth/google/tokensource.go

@@ -7,8 +7,6 @@ import (
 	"golang.org/x/oauth2"
 )
 
-// dbTokenSource wraps an oauth2.TokenSource and persists refreshed tokens
-// back to the database on every refresh.
 type dbTokenSource struct {
 	email   string
 	store   *TokenStore

oauth/google/tokenstore.go

@@ -10,8 +10,6 @@ import (
 	"golang.org/x/oauth2"
 )
 
-// TokenStore persists Google OAuth tokens in a local SQLite database.
-// Uses a single unified table instead of the legacy 2-table design.
 type TokenStore struct {
 	db *sql.DB
 }

provider/anthropic/anthropic.go

@@ -24,21 +24,17 @@ const (
 	vertexAPIVersion = "vertex-2023-10-16"
 )
 
-// Anthropic implements the provider.Provider interface using the Anthropic Messages API.
-// It supports both the direct Anthropic API and Google Vertex AI.
 type Anthropic struct {
 	apiKey  string
 	baseURL string
 	client  *http.Client
 
-	// Vertex AI fields.
 	vertexProject string
 	vertexRegion  string
 	tokenOnce     sync.Once
 	tokenSource   oauth2.TokenSource
 }
 
-// Ensure Anthropic implements Provider at compile time.
 var _ provider.Provider = (*Anthropic)(nil)
 
 func init() {
@@ -55,29 +51,23 @@ func init() {
 	})
 }
 
-// Option configures the Anthropic provider.
 type Option func(*Anthropic)
 
-// WithBaseURL sets a custom API base URL (useful for testing).
 func WithBaseURL(url string) Option {
 	return func(a *Anthropic) { a.baseURL = url }
 }
 
-// WithHTTPClient sets a custom HTTP client.
 func WithHTTPClient(c *http.Client) Option {
 	return func(a *Anthropic) { a.client = c }
 }
 
-// WithVertexAI configures the provider to use Google Vertex AI instead of the direct Anthropic API.
-// Uses Google Application Default Credentials unless a custom TokenSource is provided via WithTokenSource.
 func WithVertexAI(project, region string) Option {
 	return func(a *Anthropic) {
 		a.vertexProject = project
 		a.vertexRegion = region
 	}
 }
 
-// WithTokenSource sets a custom OAuth2 token source for Vertex AI authentication.
 func WithTokenSource(ts oauth2.TokenSource) Option {
 	return func(a *Anthropic) { a.tokenSource = ts }
 }
@@ -103,7 +93,6 @@ func (a *Anthropic) vertexToken(ctx context.Context) (string, error) {
 	return token.AccessToken, nil
 }
 
-// New creates a new Anthropic provider.
 func New(apiKey string, opts ...Option) *Anthropic {
 	a := &Anthropic{
 		apiKey:  apiKey,
@@ -116,7 +105,6 @@ func New(apiKey string, opts ...Option) *Anthropic {
 	return a
 }
 
-// Chat sends a non-streaming chat request.
 func (a *Anthropic) Chat(ctx context.Context, req provider.ChatRequest) (*provider.ChatResponse, error) {
 	body := a.buildRequest(req, false)
 
@@ -138,7 +126,6 @@ func (a *Anthropic) Chat(ctx context.Context, req provider.ChatRequest) (*provid
 	return a.parseResponse(&apiResp), nil
 }
 
-// StreamChat sends a streaming chat request and returns a channel of events.
 func (a *Anthropic) StreamChat(ctx context.Context, req provider.ChatRequest) (<-chan provider.StreamEvent, error) {
 	body := a.buildRequest(req, true)
 
@@ -167,14 +154,12 @@ func (a *Anthropic) buildRequest(req provider.ChatRequest, stream bool) map[stri
 		body["stream"] = true
 	}
 
-	// Convert messages.
 	var msgs []map[string]any
 	for _, m := range req.Messages {
 		msgs = append(msgs, convertMessage(m))
 	}
 	body["messages"] = msgs
 
-	// Convert tools.
 	if len(req.Tools) > 0 {
 		var tools []map[string]any
 		for _, t := range req.Tools {
@@ -417,8 +402,6 @@ func (a *Anthropic) parseSSE(body io.ReadCloser, ch chan<- provider.StreamEvent)
 	}
 }
 
-// API types for JSON marshaling.
-
 type apiResponse struct {
 	Type       string         `json:"type"`
 	Content    []apiContent   `json:"content"`

provider/credential.go

@@ -8,8 +8,6 @@ import (
 	"github.com/zalando/go-keyring"
 )
 
-// LoadCredential retrieves an API key from the OS keyring.
-// The ref format is "keychain:<service>/<account>", e.g. "keychain:obk/anthropic".
 func LoadCredential(ref string) (string, error) {
 	service, account, err := parseCredentialRef(ref)
 	if err != nil {
@@ -22,7 +20,6 @@ func LoadCredential(ref string) (string, error) {
 	return val, nil
 }
 
-// StoreCredential saves an API key to the OS keyring.
 func StoreCredential(ref, value string) error {
 	service, account, err := parseCredentialRef(ref)
 	if err != nil {
@@ -34,9 +31,6 @@ func StoreCredential(ref, value string) error {
 	return nil
 }
 
-// ResolveAPIKey resolves an API key from a keyring reference or
-// an environment variable. For headless/CI environments where no
-// keyring is available, set the environment variable directly.
 func ResolveAPIKey(ref, envVar string) (string, error) {
 	if ref != "" && strings.HasPrefix(ref, "keychain:") {
 		key, err := LoadCredential(ref)