---
title: "How trails works"
description: "From local coding-agent sessions to a private, readable timeline on one Mac."
---

> Documentation Index
> Fetch the complete documentation index at: https://trails.manzanita.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How trails works

The default trails system fits on one Mac. The same standalone binary runs the canonical service, collects that Mac's sessions, and creates daily backups. Tailscale and other Macs are optional extensions.

## The local path from session to day

1. **A coding agent leaves a session log**

   Claude Code, Codex, omp, and pi already record local session history as part of their normal operation.
2. **The collector reads changed sessions**

   Once a minute, trails parses files that may have changed. Transcript parsing happens on the Mac where the session was created.
3. **Trails normalizes the observation**

   It derives timestamps, project context, event counts, the first prompt, minute activity, and a bounded digest. Raw transcript paths and bodies stay on the originating Mac.
4. **The hub commits canonical state**

   On a one-Mac installation this is the same machine. It stores observations and user edits in SQLite. Repeated submissions are idempotent, so retries do not duplicate sessions.
5. **The browser reads the timeline**

   Open `http://127.0.0.1:7412/` on that Mac. The browser shows day, week, thread, and project views without receiving source-local session identifiers or digests.

“Hub” names the role that owns canonical state. “Collector” names the role that reads session logs. A single Mac performs both roles; they are not separate products or required machines.

## Attention and agent time

Agent-heavy work has two different clocks:

- **Agent time** is when a coding agent was active, including periods when it continued without you.
- **Attention time** is when your prompts and steering show you were present.

Trails renders both in one lane instead of collapsing them into wall-clock duration. That distinction reconstructs the shape of your day without asking you to run a timer.

## Adding spokes

When work is spread across several Macs, Tailscale can privately connect them. The hub still collects its own sessions and remains canonical. Each additional spoke parses its own sessions locally and sends normalized observations to the hub every minute.

The hub service still binds only to `127.0.0.1:7412`. Tailscale Serve proxies that loopback service privately; trails never listens on the LAN. Tailscale carries encrypted network traffic but does not store trails data.

[Add other Macs →](/add-other-macs)

## The hub owns the truth

Canonical SQLite state includes:

- normalized session observations;
- project names and assignments;
- thread and divergence-pocket state;
- generated summaries;
- user settings;
- daily backups.

Browsers are readers and editors over that canonical state. A second browser converges on the same organization.

## Cloudflare's narrow role

Cloudflare does not host the trails application or database. When optional summary generation is enabled, a small authenticated Worker relays bounded inputs to Workers AI. Complete transcripts are not sent through that relay. SQLite on the hub remains canonical.

[Read the exact privacy boundary →](/concepts/privacy)

Source: https://trails.manzanita.dev/concepts/how-it-works/index.mdx