# Traggo

Tag-based self-hosted time tracking in Go, driven by the same GraphQL API its UI uses.

Traggo records tagged time spans instead of tasks, with dashboards, list and calendar views, multiple themes and simple user management. It is a single Go binary with SQLite, configured through TRAGGO_* environment variables or server.ini. The Builder's schema.graphql defines mutations and queries for time spans, tags, stats, dashboards, users and device tokens; there is no separate API guide.

Alternative to: Toggl Track, Clockify

- Capabilities: adaptable, operable
- Vertical: scheduling-staffing
- Shape: business-app
- Form factor: web-app
- Execution model: deterministic
- Provenance: human-written (recorded, never ranked)
- Repo: https://github.com/traggo/server (GPL-3.0), 1623 stars, last commit 2026-07-31
- Last activity: 2026-07-31
- Page: apps/traggo--server.html
- JSON: apps/traggo--server.json

## Use it when

- I want the simplest possible self-hosted tracker where categories are tags I invent, not a project tree
- I want my agent to start and stop timers and pull weekly totals by tag over GraphQL

## Gotchas

- GPL-3.0 copyleft
- SQLite is the only database dialect
- No clients, projects, rates, invoices or exports: it tracks time and shows statistics
- The GraphQL API is documented only by schema.graphql; there is no agent guide and no OpenAPI

## Editions

- Free: Free, open source
  - source: https://github.com/traggo/server
  - container: docker-compose up -d
  - binary: https://github.com/traggo/server/releases

## Adaptable: make it yours

Effort: config-only (13 things to edit)

Set TRAGGO_PORT, TRAGGO_DEFAULT_USER_NAME and TRAGGO_DEFAULT_USER_PASS for first login, TRAGGO_DATABASE_CONNECTION for the SQLite path, and TRAGGO_LOG_LEVEL and TRAGGO_PASS_STRENGTH as needed, in .env, .env.local, ~/.config/traggo/server.ini or /etc/traggo/server.ini. Tags, dashboards and users are created in the UI or through GraphQL. The tag model is the customization: define a project tag, a type tag, a client tag and the reports follow.

- Env vars: TRAGGO_PORT, TRAGGO_DEFAULT_USER_NAME, TRAGGO_DEFAULT_USER_PASS, TRAGGO_PASS_STRENGTH, TRAGGO_LOG_LEVEL, TRAGGO_DATABASE_DIALECT, TRAGGO_DATABASE_CONNECTION
- Config files: .env.sample, .env, .env.local, ~/.config/traggo/server.ini, /etc/traggo/server.ini, docker-compose.yml
- Prompt files: none
- Accounts you'll need: none

## Operable: what an agent can drive

Operability: official. Interface: api at https://github.com/traggo/server/blob/master/schema.graphql (published by the builder, local).

### Reach (partial coverage)

- Start, stop and edit time spans: reachable. schema.graphql: createTimeSpan, updateTimeSpan, stopTimeSpan, copyTimeSpan, removeTimeSpan
- List time spans by date range: reachable. schema.graphql: timeSpans(fromInclusive, toInclusive, cursor)
- Define tags and bulk-replace tag values: reachable. createTag, updateTag, removeTag, replaceTimeSpanTags, suggestTag
- Aggregate statistics by tag and range: reachable. stats(ranges, tags, excludeTags, requireTags)
- Build dashboards: reachable. createDashboard, addDashboardRange, addDashboardEntry and their update/remove pairs
- Manage users: reachable. createUser, updateUser, removeUser (ADMIN role)
- Issue device tokens for API access: reachable. schema.graphql: login(username, pass, deviceName, type, cookie: false) and createDevice return Login.token; auth/middleware.go accepts 'Authorization: traggo <token>', a traggo cookie, or a token form value
- Change user settings and theme: reachable. setUserSettings
- Export to CSV or invoice: not reachable. no export or invoicing in schema.graphql or README features

## Code stack

- Languages: Go, TypeScript
- Frameworks: gqlgen, React
- Package manager: go modules
- Database: SQLite
- Hosting target: docker, binary

## Evidence and confidence

- formFactor: README: self-hosted web UI served by the Go server (confidence 0.95)
- executionModel: no model SDK or AI feature (confidence 0.95)
- operability: schema.graphql in traggo/server documents queries and mutations including login and createDevice that return a token; endpoint is /graphql (main.go). The header format 'Authorization: traggo <token>' appears only in auth/middleware.go; traggo.net has config, install, and dev pages but no API page. (confidence 0.8)
- effort: traggo.net/config lists TRAGGO_* variables and the config file search order; .env.sample read this run (confidence 0.95)
- editions: README: self-host only; GPL-3.0 (confidence 0.95)
- active: shortlist pushedAt 2026-07-31
- reach:  (confidence 0.85)

## Open questions

- The /graphql path and the 'Authorization: traggo <token>' header are only in source (main.go, auth/middleware.go); traggo.net has no API page

## Sources

- https://github.com/traggo/server (sourcing:scheduling-staffing:curated)
- https://traggo.net/config/ (sourcing:scheduling-staffing:curated)
- https://github.com/traggo/server/blob/master/schema.graphql (analysis:scheduling-staffing)