Integrations
Integrations are optional and self-hosted. With nothing configured, the tracker still watches saved files and git activity in your project folder. Layer 1 process labels cover many editors and agents out of the box; adapters only add finer counts.
What works without an adapter
Layer 1 process labels cover common editors and agents when they run over a linked repo. Details: Desktop tracker.
AI IDEs: Cursor, Windsurf, Trae, Kiro, Zed, Antigravity
Editors / IDEs: VS Code, VSCodium, Neovim, Helix, Kakoune, Sublime Text, Emacs, Vim, JetBrains (IDEA, WebStorm, PyCharm, GoLand, CLion, Rider, RustRover, Android Studio), Fleet, Nova, TextMate, Kate, gedit, Notepad++, Xcode, Arduino IDE
Game / creative / CAD / notebooks: Godot, Unity, KiCad, Blender, FreeCAD, OpenSCAD, Aseprite, Krita, GIMP, Figma, Jupyter, RStudio, Obsidian
CLI agents: Claude Code, Codex, OpenClaw, Aider, Goose, OpenCode, Gemini CLI, Amp, Crush, Qwen, Cline, Roo, Continue, Copilot, Cursor agent
Extend labels in ~/.config/struggletime/editors.json without shipping a plugin.
Shell hooks (exec categories)
Hooks emit command category events (test, build, run). They never send arguments or environment secrets.
Optional adapters
Adapters write allowlisted metadata only to ~/.aitime/agent_events.jsonl. No document text, prompts, argv, or absolute paths. Verify with make verify-adapters.
VS Code family (adapters/vscode)
Works in any VS Code fork that exposes vscode.env.appName:
appName contains | editor label |
|---|---|
| Cursor | cursor |
| Windsurf | windsurf |
| Trae | trae |
| Kiro | kiro |
| VSCodium / Code - OSS | vscodium |
| Visual Studio Code | vscode |
Load adapters/vscode/extension.js as a local extension. Emits human-edit, focus, and file-op counts.
Neovim (adapters/neovim)
Or add adapters/neovim to runtimepath and call require("struggletime").setup(). Emits insert vs external-edit, focus, and save counts.
JetBrains (adapters/jetbrains)
Covers IntelliJ IDEA, PyCharm, CLion, WebStorm, GoLand, RustRover, Rider, and Android Studio.
Build with the IntelliJ Platform Gradle plugin, or symlink the sources into a throwaway plugin module. Emits typing-burst vs bulk-write counts and window focus.
Godot 4 (adapters/godot)
Copy or symlink adapters/godot/addons/struggletime into your project, then enable the plugin under Project → Project Settings → Plugins. Emits focus, filesystem/edit heartbeats, and playtest counts.
Unity (adapters/unity)
Drop adapters/unity/Editor/StruggleTimeTracker.cs into any Assets/.../Editor/ folder (or symlink the tree). Emits focus pulses, asset-save counts, and play-mode enter/exit.
Claude Code (adapters/claude-code)
Merge adapters/claude-code/hooks.json into .claude/settings.json hooks. Emits agent turn / tool boundary counts — no prompt or tool-arg text.
Codex / Aider / other CLIs (adapters/codex)
Wraps start/stop around the CLI. Manual bridge:
OpenClaw (adapters/openclaw)
OpenClaw runs agents inside its gateway, so shell hooks see file/git results but miss turns. Run the adapter next to the daemon:
Tails local session logs and appends turn/tool counts only — message text and tool arguments are discarded.
GitHub
Connect with OAuth
- GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
- Authorization callback URL:
https://your-server/v1/auth/github/callback(local:http://127.0.0.1:18765/v1/auth/github/callback) - Start the server with
GITHUB_CLIENT_IDandGITHUB_CLIENT_SECRET(env,.env, or secret store; never committed) - In StruggleTime Settings, use "sign in with github", approve on GitHub, land back linked
The server exchanges the one-time code, reads your GitHub login, and discards the OAuth token. Only the username is stored. The manual endpoint POST /v1/users/{handle}/github still exists for tests and automation. The login appears on your public profile and in the builders list.
Repo webhooks (push → commit anchors)
- On your repo: Settings → Webhooks → Add webhook
- Payload URL:
https://your-server/v1/integrations/github/webhook - Content type
application/json, events:pushonly - Set a secret and start the server with the same value:
GITHUB_WEBHOOK_SECRET=... struggletime serve
The server verifies the signature (bad signature → 401), matches the push to the project whose repo URL matches, and stores a commit anchor: commit count and head SHA only. Commit messages are never stored. Anchors appear on GET /v1/projects/{id}/github for review cross-checks. With no secret set, webhooks are accepted unverified (fine locally, not on the public internet).
Live repo lookup (optional)
GET /v1/projects/{id}/github?fetch=1 fetches stars/branch/last push from the GitHub API. Set GITHUB_TOKEN to raise rate limits. Off unless you ask for it; the server does not phone home on its own.
Slack
Notifications
Set SLACK_WEBHOOK_URL (Slack app → Incoming Webhooks) before starting the server. New submissions and finished reviews post to that channel. If unset, the same messages queue locally and stay readable at GET /v1/integrations/events.
OAuth and slash command
For identity: Slack app → OAuth & Permissions → redirect URL https://your-server/v1/auth/slack/callback, then start the server with SLACK_CLIENT_ID and SLACK_CLIENT_SECRET. In StruggleTime Settings, use "sign in with slack", approve, land back linked. The code exchange happens server-side; only your Slack user id is kept.
- In the same Slack app: Slash Commands →
/struggletime - Request URL:
https://your-server/v1/integrations/slack/command - Automation fallback:
POST /v1/users/you/slack {"slack_user_id":"U0123ABCD"} - Start the server with
SLACK_SIGNING_SECRET=<signing secret from the app Basic Information page>
/struggletime stats replies only to you with weighted hours, streak, and bucket count. /struggletime stats somehandle looks up a handle. Forged signatures get 401. With no secret set, the command works unsigned for local testing.