# ✍️ How to Use Escribano

# How to Use Escribano

Escribano runs in your menu bar and captures your screen every few seconds. Each frame is analyzed by a vision model and stored as a text description. You query that history through the `escribano-query` CLI.

## Quick Start

Open Terminal and run:

```bash
escribano-query today
```

This shows your activity from today, bucketed into moments with tools, files, and descriptions.

> **Tip:** `--json` is the default when output is piped, so you can pipe straight into `jq`, `fx`, or any other JSON tool.


---

## Recipes

Jump to: [What was I working on?](#what-was-i-working-on) · [Find something specific](#find-something-specific) · [What tools did I use?](#what-tools-did-i-use-today) · [Show me the screenshot](#show-me-the-screenshot) · [Support context](#draft-support-context)

### What was I working on?

```bash
escribano-query recent --since 4h
```

Returns a timeline of moments. Each one includes:

* **Time range** — `bucket_start_iso` → `bucket_end_iso`
* **Description** — `vlm_description`
* **Applications** — `applications`
* **Entities** — files, URLs, tools, languages, etc.

For a tighter view without descriptions:

```bash
escribano-query recent --since 4h --compact
```

### Find something specific

```bash
escribano-query search "debugging session" --since 1d --collapse
```

| Flag | Effect |
|------|--------|
| `--collapse` | Deduplicate adjacent observations with similar descriptions |
| `--latest` | Return only the most recent match |
| `--since`, `--from` / `--to` | Restrict the time window |

Search uses **OR semantics** by default — `search "swift actor"` matches either word. Use quoted phrases for exact matches:

```bash
escribano-query search '"swift actor"'      # exact phrase
escribano-query search "swift AND actor"    # both terms required
```

### What tools did I use today?

```bash
escribano-query entities --since 24h
```

Returns aggregated counts grouped by entity kind:

* `software_tool` — VS Code, Terminal, Chrome…
* `programming_language` — Swift, TypeScript, Python…
* `framework` — React, SwiftUI…

Filter to a single kind:

```bash
escribano-query entities --since 24h --kind software_tool
```

[Full list of entity kinds →](/doc/cli-reference-escribano-query-VOMrfUt91U)

### Show me the screenshot


:::warning
**Privacy note:** Always confirm with the user before using `--images`. Screenshots may contain sensitive content.

:::

```bash
escribano-query search "error message" --latest --images
```

The `image_path` field in the output is an absolute path to a JPEG. Agents with vision capability can read it directly.

### Draft support context

```bash
escribano-query support-context --json
```

A structured context summary built for support drafts and agent handoffs — aggregated signals only, no raw observations.


---

## Date Formats

| Flag | Format | Example |
|------|--------|---------|
| `--since` | Duration | `30m`, `2h`, `1d`, `1w` |
| `--from` / `--to` | ISO 8601 or `yyyy-MM-dd` | `2026-04-20T10:00:00Z` or `2026-04-20` |


---

## Agent Integration

The CLI outputs structured JSON (`api_version: 2`) that agents can consume directly. Install the `escribano-query` skill for your agent to get natural-language access to your work history.

 ![](https://notes.eduardosanzb.dev/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzcwMDg0ZDU4LThiZTUtNDVmZS1iZjMyLTVjYTU4ZTY3ZWIwYS84ZGE3NjAzYi03NTM4LTRiYjUtYjRlYi02YmRiOWM2NzM4NDQvU0NSLTIwMjYwNDI5LWlwa3AucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTEzNjgxMDAsImV4cCI6MTc5MTQ1NDUwMH0.SKogNwpLUq-s8qvJziKY1_NNPNacuqNvX72gLHoYItY " =992x672")

### MCP Server

A Model Context Protocol server for any MCP-compatible agent — *coming soon*.


---

## License

Run `escribano-query status` to check your current tier. 

| Tier | History window | Activate |
|------|----------------|----------|
| **Free** | Last 7 days    | —        |
| **Beta** | Unlimited      | `escribano-query activate ESC-BETA-XXXX` |
| **Pro** | Unlimited      | `escribano-query activate ESC-PRO-XXXX` |



:::tip
Also you can request an API key in the support page, in the “Trust Console”; remember to “Allow follow-up”.  
 ![](https://notes.eduardosanzb.dev/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzcwMDg0ZDU4LThiZTUtNDVmZS1iZjMyLTVjYTU4ZTY3ZWIwYS9kZGY3MTk3MS1hOTA5LTQ0YzgtYWViNS05Zjk0N2NmMWE1NmYvU0NSLTIwMjYwNDI5LWl6ZHItMi5wbmciLCJ0eXBlIjoiYXR0YWNobWVudCIsImlhdCI6MTc5MTM2ODEwMCwiZXhwIjoxNzkxNDU0NTAwfQ.mRXPYRLyaF5MZmUv8BwFbaXYqBWjGTUPIe8iq2ilxfo " =1056x660")

:::



---

## Self-Discovery

For agents (and curious humans):

```bash
escribano-query --help --json
```

Returns the full command surface, flags, and output schemas as machine-readable JSON.