---
title: Quickstart
description: From install to your first timeline and agent integration. Takes about five minutes.
---

Requires **macOS** (Apple Silicon or Intel) — currently the only supported platform.

1. **Install**

    Homebrew and GitHub Releases distribution are being prepared. Until they are available, build and
    install Tadoru from source:

    ```bash
    git clone https://github.com/KentoShimizu/tadoru.git
    cd tadoru
    cargo build --release
    mkdir -p "$HOME/.cargo/bin"
    install -m 755 target/release/tadoru "$HOME/.cargo/bin/tadoru"
    ```

    Make sure `$HOME/.cargo/bin` is on your `PATH`.

    :::warning[Source builds and macOS permissions]
    Unsigned and ad-hoc-signed binaries do not have a persistent code-signing identity, so macOS resets
    their TCC permissions after each rebuild. To preserve permissions across rebuilds, sign the binary
    with a persistent self-signed development certificate; see the
    [packaging instructions](https://github.com/KentoShimizu/tadoru/blob/main/packaging/README.md).
    :::

2. **Check permissions**

    Tadoru doesn't record your screen. Instead, depending on what you capture, it needs macOS permissions (Accessibility, Input Monitoring, Automation). Start with a diagnosis:

    ```bash
    tadoru doctor
    ```

    If anything is missing, you'll see what is needed, why, and how to grant it. Add `--fix` to open the relevant System Settings pane directly:

    ```bash
    tadoru doctor --fix
    ```

    :::note
    Granting permissions is always a user action — macOS does not allow apps to grant themselves permissions, and Tadoru never tries to work around that. See the [permissions guide](/guides/permissions).
    :::

3. **Start recording**

    ```bash
    tadoru start
    ```

    Recording starts in the background as a launchd agent. You can check on it at any time:

    ```bash
    tadoru status
    ```

4. **Get your first timeline**

    Work normally for a bit, then pull up your recent history:

    ```bash
    tadoru timeline --since 15m
    ```

    You get a session-structured, deduplicated Markdown timeline — the same form agents consume. For raw events, use `tadoru query --since 15m` instead (see [retrieving data](/guides/timeline)).

5. **Connect your agent (optional)**

    Place the skill file for your agent and print its MCP registration command:

    ```bash
    tadoru setup --agent claude
    ```

    From now on, telling your agent "check what I was just working on and continue" lets it restore context from the timeline. See [agent integration](/agents) for supported agents and details.

## Before you start recording

- Data is stored **only in a local SQLite database** (`~/.local/state/tadoru/store.sqlite`). Nothing is ever sent anywhere.
- Keystroke **content** is not recorded by default — only the fact that typing happened and the
  field type. To opt in explicitly, run `tadoru config set capture.text_content true`, then
  restart recording with `tadoru stop && tadoru start`.
- Events are deleted automatically after **48 hours** by default (configurable in [settings](/reference/config)).
- Apps and sites you don't want recorded can be excluded **before they are written to the store** with [filters](/guides/filters).

:::tip[If you want to stop]
`tadoru pause --for 1h` pauses temporarily, `tadoru stop` stops completely (data is kept), and `tadoru purge --all` deletes all data.
:::