Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/kashsuks/rode/llms.txt

Use this file to discover all available pages before exploring further.

WakaTime is an automatic time tracking tool for developers. Rode has built-in support for WakaTime, allowing you to track your coding activity without any manual intervention.

​
Prerequisites

Before configuring WakaTime in Rode, you need to install the WakaTime CLI:
1

Install WakaTime CLI

Follow the official WakaTime CLI installation guide for your operating system.On macOS with Homebrew:
brew install wakatime-cli
On Linux:
pip install wakatime-cli
2

Get your API key

Sign up for a free account at wakatime.com and get your API key from your settings page.

​
Configuration

Rode stores WakaTime configuration in a Lua file at ~/.config/rode/wakatime.lua.

​
Using the Settings UI

The easiest way to configure WakaTime is through Rode’s settings interface:
1

Open Settings

Open Rode and navigate to the settings panel. Look for the WakaTime section.
2

Enter your API key

Paste your WakaTime API key in the API Key field. The format should be waka_xxxxx....
3

Configure API URL (Optional)

By default, Rode uses https://api.wakatime.com/api/v1. You can change this if you’re using a self-hosted WakaTime instance.
4

Save settings

Click Save WakaTime Settings to persist your configuration.

​
Manual Configuration

You can also manually create or edit the configuration file at ~/.config/rode/wakatime.lua:
~/.config/rode/wakatime.lua
return {
  api_key = "waka_your_api_key_here",
  api_url = "https://api.wakatime.com/api/v1",
}

​
Configuration Options

​
api_key
string
required
Your WakaTime API key for authentication. Get this from your WakaTime settings.Format: waka_xxxxx...
​
api_url
string
default:"https://api.wakatime.com/api/v1"
The WakaTime API endpoint URL. Only change this if you’re using a self-hosted WakaTime instance.

​
How It Works

Once configured, Rode automatically sends heartbeats to WakaTime as you code:

​
Heartbeat Triggers

Rode sends heartbeats in the following scenarios:

Tab Focus

When you switch to a different file tab

File Save

When you save a file (marked as a write event)

​
Rate Limiting

To avoid excessive API calls, Rode implements intelligent rate limiting:
  • Heartbeats are sent at most once every 2 minutes for the same file
  • Switching to a different file immediately triggers a new heartbeat
  • Save operations always trigger a heartbeat (marked with --write flag)

​
Implementation Details

The heartbeat implementation can be found in src/wakatime/client.rs:5: 
pub fn send_heartbeat(entity: &str, is_write: bool, cfg: &WakaTimeConfig) -> std::io::Result<()> {
    if cfg.api_key.trim().is_empty() {
        return Ok(());
    }

    let mut cmd = Command::new("wakatime-cli");
    cmd.arg("--entity").arg(entity);
    cmd.arg("--plugin").arg("rode/0.1.0");
    cmd.arg("--key").arg(cfg.api_key.trim());

    if !cfg.api_url.trim().is_empty() {
        cmd.arg("--api-url").arg(cfg.api_url.trim());
    }

    if is_write {
        cmd.arg("--write");
    }

    cmd.stdout(Stdio::null()).stderr(Stdio::null());
    let _ = cmd.spawn()?;
    Ok(())
}
Key details:
  • The plugin identifier is rode/0.1.0
  • File paths are passed as the --entity argument
  • Write operations (saves) are flagged with --write
  • Heartbeats run asynchronously without blocking the editor

​
Troubleshooting

Possible causes:
  1. WakaTime CLI not installed - Verify with which wakatime-cli
  2. Invalid API key - Check that your API key is correct in settings
  3. API key is empty - Rode silently skips heartbeats if the API key is empty
Solution: Ensure wakatime-cli is in your PATH and your API key is correctly configured.
If you’re running your own WakaTime server:
  1. Set the api_url to your server’s API endpoint
  2. Make sure your API key is from your self-hosted instance
  3. Verify network connectivity to your server
Since Rode redirects stdout/stderr to null for heartbeat commands, you can temporarily monitor WakaTime CLI:
# Monitor WakaTime CLI logs (location varies by OS)
tail -f ~/.wakatime.log
You should see entries with rode/0.1.0 as the plugin identifier.
If your API key is empty or contains only whitespace, Rode will silently skip sending heartbeats. Make sure to configure your API key before expecting activity tracking.

​
Privacy

Rode only sends the following information to WakaTime:
  • File paths of the files you’re editing
  • Whether the event was a write operation (save)
  • Timestamp of the activity
  • Plugin identifier (rode/0.1.0)
No file contents or other sensitive information is transmitted.
File paths are sent to WakaTime servers. If you’re working with sensitive projects, consider using WakaTime’s project privacy settings or a self-hosted instance.

Build docs developers (and LLMs) love

Get started for freeTalk to us