timecamp

当用户询问时间跟踪、时间条目、任务、计时器或与 TimeCamp 相关的任何内容时使用。触发“timecamp”、“时间条目”、“计时器”、“跟踪”、“小时”、“时间表”、“任务列表”、“启动计时器”、“停止计时器”、“活动”、“计算机活动”等关键字。

## 概述（中文）

当用户询问时间跟踪、时间条目、任务、计时器或与 TimeCamp 相关的任何内容时使用。触发“timecamp”、“时间条目”、“计时器”、“跟踪”、“小时”、“时间表”、“任务列表”、“启动计时器”、“停止计时器”、“活动”、“计算机活动”等关键字。

## 原文

# TimeCamp Skill

Two tools: **CLI** for quick personal actions (timer, entries CRUD) and **Data Pipeline** for analytics/reports.

## Bootstrap (clone if missing)

Before using either tool:

1. Ask user where repos should live (default: `~/utils`, but any location is valid).
2. If repos are missing in that chosen location, ask for confirmation to clone.

Example flow and commands:

```bash
# Ask first:
# "I don't see TimeCamp repos locally. Clone to ~/utils, or use a different location?"

REPOS_DIR=~/utils  # replace if user picked a different path
mkdir -p "$REPOS_DIR"

if [ ! -d "$REPOS_DIR/timecamp-cli/.git" ]; then
  git clone https://github.com/timecamp-org/timecamp-cli.git "$REPOS_DIR/timecamp-cli"
fi

if [ ! -d "$REPOS_DIR/good-enough-timecamp-data-pipeline/.git" ]; then
  git clone https://github.com/timecamp-org/good-enough-timecamp-data-pipeline.git "$REPOS_DIR/good-enough-timecamp-data-pipeline"
fi
```

## Tool 1: TimeCamp CLI (personal actions)

CLI at `~/utils/timecamp-cli`, installed globally via `npm link`.

| Intent | Command |
|--------|---------|
| Current timer status | `timecamp status` |
| Start timer | `timecamp start --task "Project A" --note "description"` |
| Stop timer | `timecamp stop` |
| Today's entries | `timecamp entries` |
| Entries by date | `timecamp entries --date 2026-02-04` |
| Entries date range | `timecamp entries --from 2026-02-01 --to 2026-02-04` |
| All users entries | `timecamp entries --from 2026-02-01 --to 2026-02-04 --all-users` |
| Add entry | `timecamp add-entry --date 2026-02-04 --start 09:00 --end 10:30 --duration 5400 --task "Project A" --note "description"` |
| Update entry | `timecamp update-entry --id 101234 --note "Updated" --duration 3600` |
| Remove entry | `timecamp remove-entry --id 101234` |
| List tasks | `timecamp tasks` |

## Tool 2: Data Pipeline (analytics & reports)

Python pipeline at `~/utils/good-enough-timecamp-data-pipeline`. **Use this for all analytics, reports, and bulk data fetching.**

### Run command

```bash
cd ~/utils/good-enough-timecamp-data-pipeline && \
uv run --with-requirements requirements.txt dlt_fetch_timecamp.py \
  --from YYYY-MM-DD --to YYYY-MM-DD \
  --datasets DATASETS \
  --format jsonl \
  --output ~/data/timecamp-data-pipeline
```

### Available datasets

| Dataset | Description |
|---------|-------------|
| `entries` | Time entries with project/task details |
| `tasks` | Projects & tasks hierarchy with breadcrumb paths |
| `computer_activities` | Desktop app tracking data |
| `users` | User details with group info and enabled status |
| `application_names` | Application lookup table (ID → name, category) |

### Formats: ``jsonl`

### Output structure

Files land in `~/data/timecamp-data-pipeline/timecamp/*.jsonl`.

### Examples

```bash
cd ~/utils/good-enough-timecamp-data-pipeline && \
uv run --with-requirements requirements.txt dlt_fetch_timecamp.py \
  --from 2026-02-11 --to 2026-02-14 \
  --datasets entries,users,tasks \
  --format jsonl --output ~/data/timecamp-data-pipeline

cd ~/utils/good-enough-timecamp-data-pipeline && \
uv run --with-requirements requirements.txt dlt_fetch_timecamp.py \
  --from 2026-01-01 --to 2026-02-14 \
  --datasets computer_activities,users,application_names \
  --format jsonl --output ~/data/timecamp-data-pipeline

cd ~/utils/good-enough-timecamp-data-pipeline && \
uv run --with-requirements requirements.txt dlt_fetch_timecamp.py \
  --from 2026-01-01 --to 2026-02-14 \
  --datasets computer_activities,users,application_names,entries,tasks \
  --format jsonl --output ~/data/timecamp-data-pipeline
```

## Analytics with DuckDB

Query the persistent data store directly.

```bash
DUCKDB=~/.duckdb/cli/latest/duckdb
DATA=~/data/timecamp-data-pipeline/timecamp

# Hours per person
$DUCKDB -c "
SELECT user_name, round(sum(TRY_CAST(duration AS DOUBLE))/3600.0, 1) as hours
FROM read_json_auto('$DATA/entries*.jsonl')
GROUP BY user_name ORDER BY hours DESC
"

# Hours per person per day
$DUCKDB -c "
SELECT user_name, date, round(sum(TRY_CAST(duration AS DOUBLE))/3600.0, 1) as hours
FROM read_json_auto('$DATA/entries*.jsonl')
GROUP BY user_name, date ORDER BY user_name, date
"

# Top applications by time (join activities with app names)
$DUCKDB -c "
SELECT COALESCE(an.full_name, an.application_name, an.app_name, 'Unknown') as app,
       round(sum(ca.time_span)/3600.0, 2) as hours
FROM read_json_auto('$DATA/computer_activities*.jsonl') ca
LEFT JOIN read_json_auto('$DATA/application_names*.jsonl') an
  ON ca.application_id = an.application_id
GROUP BY 1 ORDER BY hours DESC LIMIT 20
"

# People who logged < 30h in a given week
$DUCKDB -c "
SELECT user_name, round(sum(TRY_CAST(duration AS DOUBLE))/3600.0, 1) as hours
FROM read_json_auto('$DATA/entries*.jsonl')
WHERE date BETWEEN '2026-02-03' AND '2026-02-07'
GROUP BY user_name
HAVING sum(TRY_CAST(duration AS DOUBLE))/3600.0 < 30
ORDER BY hours
"
```

### Pattern

1. Check existing data range with DuckDB, if data is missing, fetch it with the pipeline, if it's already there, use it
2. Query with DuckDB: `$DUCKDB -c "SELECT ... FROM read_json_auto('$DATA/entries*.jsonl') ..."`

## Important Notes

- Duration (entries) is in seconds (3600 = 1h)
- `time_span` (activities) is also in seconds
- `applications_cache.json` in pipeline dir caches app name lookups
- For JSONL output, DuckDB glob `*.jsonl` catches all files for all datasets

## Safety

- Confirm before adding, updating, or removing entries
- Show the command before executing modifications
- When stopping a timer, show what was running first

## Author

[TimeCamp Time Tracking Software](https://www.timecamp.com)

## License

MIT