Editor Plugins

VS Code / Cursor Extension

The BuilderBox extension provides comprehensive tracking with AI detection, activity type breakdown, and automatic configuration.

Installation

1. Open VS Code or Cursor
2. Go to Extensions (Ctrl/Cmd+Shift+X)
3. Search for "BuilderBox"
4. Click Install
5. Sign in when prompted

Or install from the command line:

# VS Code
code --install-extension builderbox.builderbox

# Cursor
cursor --install-extension builderbox.builderbox

Features

• Automatic tracking - No manual intervention needed
• AI detection - Distinguishes AI from human code
• Activity breakdown - Coding, reviewing, terminal, prompting
• Status bar - Shows current tracking status
• Offline support - Queues heartbeats when offline

Configuration

Configure via VS Code settings (Ctrl/Cmd+,):

{
  // Enable/disable tracking
  "builderbox.enabled": true,
  
  // Debug mode (verbose logging)
  "builderbox.debug": false,
  
  // Minutes of inactivity before idle
  "builderbox.idleCutoffMinutes": 15
}

CLI Integration

For editors without native plugins, use the BuilderBox CLI to send heartbeats. This works with Neovim, Vim, Emacs, Sublime Text, or any editor with autocmd/hook support.

Setup

1. Install the BuilderBox CLI (see Installation)
2. Authenticate with builderbox auth login
3. Configure your editor to send heartbeats on file events

Heartbeat Command

builderbox heartbeat --file <path> [options]

Options:
  --file <path>        File path being edited (required)
  --language <lang>    Programming language (auto-detected if omitted)
  --project <name>     Project name (auto-detected if omitted)
  --branch <name>      Git branch (auto-detected if omitted)
  --is-ai              Mark as AI-generated code
  --ai-tool <name>     AI tool used (copilot, cursor, cline, etc.)
  --chars-added <n>    Characters added
  --chars-deleted <n>  Characters deleted
  --lines-added <n>    Lines added
  --lines-deleted <n>  Lines deleted

Neovim Integration

Add this to your Neovim configuration to send heartbeats automatically:

Lua Configuration (init.lua)

-- BuilderBox heartbeat integration
local builderbox_group = vim.api.nvim_create_augroup('BuilderBox', { clear = true })

-- Send heartbeat on save
vim.api.nvim_create_autocmd('BufWritePost', {
  group = builderbox_group,
  callback = function()
    local file = vim.fn.expand('%:p')
    if file ~= '' then
      vim.fn.jobstart({'builderbox', 'heartbeat', '--file', file}, {
        on_exit = function(_, code)
          if code ~= 0 then
            vim.notify('BuilderBox heartbeat failed', vim.log.levels.WARN)
          end
        end
      })
    end
  end
})

-- Send heartbeat periodically while editing
vim.api.nvim_create_autocmd('CursorHold', {
  group = builderbox_group,
  callback = function()
    local file = vim.fn.expand('%:p')
    if file ~= '' then
      vim.fn.jobstart({'builderbox', 'heartbeat', '--file', file})
    end
  end
})

-- Optional: Send heartbeat when entering a buffer
vim.api.nvim_create_autocmd('BufEnter', {
  group = builderbox_group,
  callback = function()
    local file = vim.fn.expand('%:p')
    if file ~= '' and vim.bo.buftype == '' then
      vim.fn.jobstart({'builderbox', 'heartbeat', '--file', file})
    end
  end
})

VimScript Configuration (init.vim)

" BuilderBox heartbeat integration
augroup BuilderBox
  autocmd!
  " Send heartbeat on save
  autocmd BufWritePost * silent! call jobstart(['builderbox', 'heartbeat', '--file', expand('%:p')])
  " Send heartbeat periodically
  autocmd CursorHold * silent! call jobstart(['builderbox', 'heartbeat', '--file', expand('%:p')])
  " Send heartbeat when entering buffer
  autocmd BufEnter * if &buftype == '' | silent! call jobstart(['builderbox', 'heartbeat', '--file', expand('%:p')]) | endif
augroup END

Vim Integration

Add this to your .vimrc:

" BuilderBox heartbeat integration
augroup BuilderBox
  autocmd!
  " Send heartbeat on save
  autocmd BufWritePost * silent! !builderbox heartbeat --file %:p &
  " Send heartbeat periodically (requires +timers)
  if has('timers')
    autocmd CursorHold * silent! !builderbox heartbeat --file %:p &
  endif
augroup END

Note: The & at the end runs the command in the background to avoid blocking Vim.

Emacs Integration

Add this to your Emacs configuration:

;; BuilderBox heartbeat integration
(defun builderbox-send-heartbeat ()
  "Send a heartbeat to BuilderBox."
  (when buffer-file-name
    (start-process "builderbox" nil "builderbox" "heartbeat" "--file" buffer-file-name)))

;; Send heartbeat on save
(add-hook 'after-save-hook #'builderbox-send-heartbeat)

;; Send heartbeat periodically (every 2 minutes)
(run-with-idle-timer 120 t #'builderbox-send-heartbeat)

;; Send heartbeat when switching buffers
(add-hook 'window-buffer-change-functions
          (lambda (_) (builderbox-send-heartbeat)))

Other Editors

Any editor with hook or autocmd support can integrate with BuilderBox. The key is to:

1. Send a heartbeat when saving a file
2. Send a heartbeat periodically while editing (every 2 minutes)
3. Optionally send heartbeats on file open/focus

The CLI auto-detects language, project, and git branch from the file path, so only the --file argument is required.

JetBrains Plugin (Coming Soon)

Native JetBrains plugin support for IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs is planned. In the meantime, you can use the CLI integration with JetBrains' File Watchers or External Tools feature.

Temporary Workaround

1. Go to Settings → Tools → External Tools
2. Add new tool with:
   • Program: builderbox
   • Arguments: heartbeat --file $FilePath$
3. Bind to a keyboard shortcut or add to macro

WakaTime Migration

BuilderBox is compatible with WakaTime's heartbeat format. If you're migrating from WakaTime, your existing editor plugins may work with BuilderBox's API endpoint (with appropriate authentication).

For historical data import from WakaTime, see our CLI import command.

Troubleshooting

Heartbeats Not Sending

1. Verify CLI is installed: builderbox --version
2. Verify authentication: builderbox auth status
3. Check config file exists: cat ~/.config/builderbox/config.json
4. Test manually: builderbox heartbeat --file /path/to/file.ts

Data Not Showing in Dashboard

• Heartbeats are aggregated every few minutes
• Refresh the dashboard after a few minutes
• Check browser timezone settings match your local time

High CPU Usage

• Reduce heartbeat frequency in your editor config
• Use CursorHold instead of CursorMoved events
• Ensure the CLI process runs in the background