Tivra

Attention intelligence for modern work.

Tivra tracks your digital activity across all browsers and native apps, understands your focus habits, and helps you build more deep work — privately, on your Mac.

What makes Tivra different

• Cross-browser tracking — Chrome, Edge, Brave, Arc, Firefox, Zen. Not just Safari.
• Habit-based focus sessions — sessions adapt to your real patterns, not generic timers.
• Local-first — all data stays on your machine. Always.
• Actionable insights — not dashboards full of numbers, but clarity on what's actually happening.

Monorepo structure

tivra/
  apps/
    macos/          # Native macOS app (Swift/SwiftUI)
    landing/        # Marketing site (Next.js)
  extensions/
    chromium/       # Chrome, Edge, Brave, Arc (Manifest V3)
    firefox/        # Firefox, Zen (WebExtension API)
  packages/
    event-schema/   # Canonical event types
    analytics/      # Focus score engine
    ui/             # Design system
    config/         # Shared configs
  docs/             # Technical documentation

Status

🚧 Active development — currently in Phase 1 (foundation).

See ROADMAP.md for the full plan.

Docs

• BRAND.md — brand brief, positioning, tone
• ARCHITECTURE.md — technical architecture and data flow
• ROADMAP.md — 6-week plan and phase gates

Requirements

• macOS 14+
• Swift 6 / Xcode 16+
• Node.js 20+ (for extensions and landing)

Debug Console

Set TIVRA_DEBUG_LOGS=1 before launching Tivra from Terminal to print structured pipeline traces to the console.

cd apps/macos
TIVRA_DEBUG_LOGS=1 open .build-xcode/Build/Products/Debug/FocusFlow.app

Each line is emitted as ISO_TIMESTAMP CATEGORY LEVEL {json} and covers frontmost app detection, idle transitions, browser merge decisions, session segmentation, and storage fetch/insert activity.

Localhost Fallback Receiver

The macOS app includes the extension fallback receiver directly. While FocusFlow.app is running, it binds only to 127.0.0.1:4242 and accepts POST /events with the Tivra event JSON shape plus HMAC authentication headers:

• X-Tivra-Timestamp
• X-Tivra-Nonce
• X-Tivra-Signature

Security model:

• Native Messaging remains the preferred extension transport.
• Localhost fallback now requires an app-generated shared secret stored in macOS Keychain.
• Requests are signed over method + path + timestamp + nonce + rawBody.
• The app rejects missing/invalid signatures, stale timestamps, and replayed nonces.
• The Chromium and Firefox extensions default to minimized browser payloads: domain + tab/window ids, empty title, and URL reduced to origin only.

Dev bootstrap flow:

• Set TIVRA_ENABLE_LOCALHOST_BOOTSTRAP=1 before launching FocusFlow.app.
• While enabled, GET /auth/bootstrap is available only on localhost, only once per app process, and only for 60 seconds after receiver startup.
• In production, leave bootstrap disabled and prefer Native Messaging.

Database encryption prep:

• The macOS app now provisions a database encryption key from Keychain at startup.
• Current builds do not link SQLCipher yet; TIVRA_ENABLE_SQLCIPHER=1 only exercises the hook path and logs that SQLCipher still needs to be enabled in the build.

Smoke test:

export TIVRA_SECRET="$(curl -fsS http://127.0.0.1:4242/auth/bootstrap | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"secret\"])')"
export TIVRA_BODY='{"type":"heartbeat","ts":1710000000123,"source":"chromium","payload":{"domain":"openai.com","tabId":"tab-1","durationMs":10000}}'
export TIVRA_TS="$(python3 -c 'import time; print(int(time.time()))')"
export TIVRA_NONCE="$(python3 -c 'import uuid; print(uuid.uuid4())')"
export TIVRA_SIG="$(printf 'POST\n/events\n%s\n%s\n%s' \"$TIVRA_TS\" \"$TIVRA_NONCE\" \"$TIVRA_BODY\" | openssl dgst -sha256 -hmac \"$TIVRA_SECRET\" -binary | xxd -p -c 256)"

curl -i \
  -X POST http://127.0.0.1:4242/events \
  -H 'Content-Type: application/json' \
  -H "X-Tivra-Timestamp: $TIVRA_TS" \
  -H "X-Tivra-Nonce: $TIVRA_NONCE" \
  -H "X-Tivra-Signature: $TIVRA_SIG" \
  -d "$TIVRA_BODY"

Unsigned requests should now fail:

curl -i \
  -X POST http://127.0.0.1:4242/events \
  -H 'Content-Type: application/json' \
  -d "$TIVRA_BODY"

Expected success body:

{"ok":true}

Expected unsigned failure status: 401 Unauthorized

License

MIT