timeforged (Blysspeak)

Self-hosted time tracking for developers. Daemon + CLI + Web Dashboard + MCP, written in Rust.

______________________________________________________________________

快速开始

git clone https://github.com/Blysspeak/timeforged.git
cd timeforged
bash install.sh

安装程序将：

• 构建web仪表板（Vue 3+Tailwind）
• 编译Rust二进制文件(timeforged 守护进程+ tf CLI）
• 安装到 ~/.local/bin/
• 设置systemd用户服务
• 在远程服务器上注册(timeforged.blysspeak.space)用于同步和公共配置文件卡
• 配置自动同步（通过systemd定时器每15分钟一次）
• 安装Claude代码挂钩（如果检测到）
• 安装Waybar模块（如果检测到Waybar）
• 启动守护进程并显示您的API密钥

然后初始化跟踪：

tf init ~/projects    # watch a directory tree

打开 http://127.0.0.1:6175 在浏览器中，仪表板立即工作，无需在本地主机上登录。

手动构建

# Build dashboard
cd crates/timeforged/web && npm install && npx vite build && cd ../../..

# Build binaries
cargo build --release

# Run daemon
./target/release/timeforged

首次运行时，会自动创建一个管理员用户和API密钥：

==============================================
  TimeForged — first run setup
  Created admin user with API key:
  tf_abc123...
  Save this key! It won't be shown again.
==============================================

Web仪表板

该守护进程在以下位置提供内置的web仪表板 http://127.0.0.1:6175:

• 周期切换器 --今天/7天/30天/所有时间
• 所有时间总计 --始终可见，显示累计小时数、活动天数和项目计数
• 活动图表 --所选期间的每天时间
• 项目和语言 --进度条和语言图标细分
• 会话 --最近的编码会话及其持续时间
• 统计 --顶级项目，会话计数

本地主机请求是自动验证的-查看仪表板不需要API键。

文件监视器

TimeForged通过文件系统事件自动跟踪您的编码活动，无需编辑器插件。

tf init ~/projects          # start watching (recursive, inotify-based)
tf list                     # show watched directories
tf unwatch ~/projects       # stop watching

守护进程递归监视已注册的目录，并在文件更改时创建心跳事件。特征：

• 项目检测 --被监视根目录的第一级子目录将成为项目名称
• 语言检测 --从文件扩展名和文件名模式推断
• 分支 --每个项目缓存（60s TTL）
• 防抖 --每个文件30秒，以避免事件垃圾邮件
• 被忽略的路径 — .git, node_modules, target, __pycache__，锁定文件、二进制文件
• 窗口跟踪器 （可选）--民意调查 hyprctl / xdotool 活动编辑器文件每15秒一次

监视的目录将保留在 ~/.config/timeforged/watched.toml.

Waybar模块

在Waybar面板中显示今天的编码时间：

bash contrib/waybar/install.sh

这将安装一个自定义模块，该模块每隔60秒查询一次TimeForged API，将时间显示为 󱑂 1:25，并单击打开仪表板。工具提示显示了每个项目的细分。

安装程序也由以下人员自动运行 install.sh 当检测到Waybar时。

Claude代码集成

TimeForged可以通过以下方式自动跟踪您的AI辅助编码会话 克劳德代码 钩子。

bash install.sh   # choose "yes" when prompted for Claude Code hooks

或手动安装：

mkdir -p ~/.claude/hooks
cp contrib/claude-code/timeforged-heartbeat.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/timeforged-heartbeat.sh

然后添加到 ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [{ "type": "command", "command": "~/.claude/hooks/timeforged-heartbeat.sh" }],
    "PostToolUse": [{ "type": "command", "command": "~/.claude/hooks/timeforged-heartbeat.sh" }],
    "Stop": [{ "type": "command", "command": "~/.claude/hooks/timeforged-heartbeat.sh" }]
  }
}

钩子在每次交互时都会触发30秒的去抖动，在后台发送心跳（非阻塞），并从钩子上下文中自动检测项目、语言、分支和文件路径。

建筑

crates/
  timeforged-core/   # Shared types, models, config
  timeforged/        # Daemon — Axum REST API + SQLite + embedded SPA
    web/             # Vue 3 + Tailwind CSS dashboard
  tf/                # CLI client
contrib/
  waybar/            # Waybar module + installer
  claude-code/       # Claude Code heartbeat hook

File Watcher (inotify) ──┐
Window Tracker (optional) ┼──→ Events ──→ Storage (SQLite)
Claude Code (hooks) ──────┤
HTTP API (POST /events) ──┘
                                            ↓
Browser → Embedded SPA (rust-embed) ──→ Reports API ──→ Storage
Waybar module ─────────────────────────→ Reports API

命令行界面

tf init ~/projects              # watch a directory tree
tf list                         # show watched directories
tf unwatch ~/projects           # stop watching

tf status                       # daemon status
tf today                        # today's summary
tf report --range week          # weekly report
tf report --range month --project myapp

tf send /path/to/file.rs --project myapp --language Rust  # manual heartbeat

API密钥在中配置一次 ~/.config/timeforged/cli.toml 或通过 TF_API_KEY.

远程同步和GitHub个人资料卡

TimeForged可以将您的本地活动同步到远程服务器，并为您的GitHub配置文件生成SVG卡。

设置

安装程序会自动处理此问题。要手动设置，请执行以下操作：

# Register on the remote server
tf register  --remote https://timeforged.blysspeak.space

# Enable public profile (makes your card visible)
tf profile --public

# Sync events
tf sync

GitHub自述卡

将此添加到您的GitHub个人资料README中：

  ?theme=dark" width="766" alt="TimeForged Activity" />

同步时，卡会自动更新。可用参数：

• theme — dark （默认）或 light
• days --显示的天数（1-365，默认值7）

用于同步的CLI配置

# ~/.config/timeforged/cli.toml
server_url = "http://127.0.0.1:6175"
api_key = "tf_..."
remote_url = "https://timeforged.blysspeak.space"
remote_key = "tf_..."

公共API（无需身份验证）

码头工人

docker compose up -d

或者手动构建：

docker build -t timeforged .
docker run -d -p 6175:6175 -v timeforged-data:/data timeforged

REST API

所有经过身份验证的端点都需要 X-Api-Key header（或本地主机访问）。

查询参数

from, to （ISO 8601）， project, language

事件主体

{
  "timestamp": "2026-02-27T10:00:00Z",
  "event_type": "file",
  "entity": "/home/user/project/src/main.rs",
  "project": "app",
  "language": "Rust",
  "branch": "main",
  "activity": "coding"
}

event_type: file | terminal | browser | meeting | custom activity: coding | browsing | debugging | building | communicating | designing | other

省略时，项目和语言将从文件路径自动推断出来。

配置

守护进程-- ~/.config/timeforged/config.toml

host = "127.0.0.1"
port = 6175
database_url = "sqlite:~/.local/share/timeforged/timeforged.db?mode=rwc"
idle_timeout = 300
log_level = "info"

CLI-- ~/.config/timeforged/cli.toml

server_url = "http://127.0.0.1:6175"
api_key = "tf_..."
remote_url = "https://timeforged.blysspeak.space"
remote_key = "tf_..."

关注的目录-- ~/.config/timeforged/watched.toml

[[directories]]
path = "/home/user/projects"

通过管理 tf init / tf unwatch.

环境变量

所有设置都可以用以下命令覆盖 TF_ 前缀：

TF_HOST, TF_PORT, TF_DATABASE_URL, TF_IDLE_TIMEOUT, TF_LOG_LEVEL, TF_SERVER_URL, TF_API_KEY, TF_REMOTE_URL, TF_REMOTE_KEY

许可证

麻省理工学院