---
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 Zanei from source:

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

    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/zanei/blob/main/packaging/README.md).
    :::

2. **Check permissions**

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

    ```bash
    zanei 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
    zanei doctor --fix
    ```

    :::note
    Granting permissions is a user action; macOS does not allow apps to grant themselves permissions. See the [permissions guide](/guides/permissions).
    :::

3. **Start recording**

    ```bash
    zanei start
    ```

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

    ```bash
    zanei status
    ```

4. **Get your first timeline**

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

    ```bash
    zanei timeline --since 15m
    ```

    You get a session-structured, deduplicated Markdown timeline — the same form agents consume. For raw events, use `zanei 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
    zanei 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 in a local SQLite database (`~/.local/state/zanei/store.sqlite`) and is not sent anywhere.
- Keystroke content is not recorded by default — only the fact that typing happened and the
  field type. To opt in explicitly, run `zanei config set capture.text_content true`, then
  restart recording with `zanei stop && zanei 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 with [filters](/guides/filters).

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