capture

🧠 Clear your mind instantly — capture thoughts to Gmail with a single command ⚡

Quick Start · Installation · Configuration

---

Overview

Capture implements the Getting Things Done (GTD) methodology by letting you dump thoughts, tasks, and ideas from your mind into Gmail instantly. Stop letting random thoughts interrupt your focus — capture them in seconds and process them later.

Features

• ⚡ Instant capture — Send notes to Gmail in under 2 seconds
• 🎯 Multiple targets — Route messages to different inboxes (home, work, etc.)
• 🔒 Secure OAuth2 — Gmail API authentication, no passwords stored
• 💻 Cross-platform — Works on macOS, Linux, and Windows
• 📝 Alfred workflow — Add notes to markdown files and capture ideas with c keyword
• ⌨️ Hotkey ready — AutoHotkey (Windows) and Alfred (macOS) integration included

Quick Start

# Install
uv tool install git+https://github.com/tsilva/capture.git

# Capture a thought
capture home "Buy groceries after work"

Installation

Prerequisites

• Python 3.8+
• uv package manager
• Google Cloud project with Gmail API enabled

Install

Method	Command
From GitHub	uv tool install git+https://github.com/tsilva/capture.git
Local clone	git clone https://github.com/tsilva/capture.git && cd capture && uv tool install .

Gmail API Setup

1. Create a project in Google Cloud Console
2. Enable the Gmail API
3. Go to Credentials → Create Credentials → OAuth 2.0 Client ID
4. Select Desktop app as application type
5. Download and save as client_secret.json in your config directory

Configuration

Config Directory

Platform	Location
macOS / Linux / Windows	~/.capture/

Required Files

client_secret.json — OAuth credentials from Google Cloud Console

targets.json — Email routing configuration:

{
  "home": {
    "from": "you@gmail.com",
    "to": "you@gmail.com"
  },
  "work": {
    "from": "you@gmail.com",
    "to": "work@company.com"
  }
}

Usage

capture <target> <message>

Argument	Description
target	Key from targets.json (e.g., home, work)
message	The thought or note to capture

Examples

# Personal reminder
capture home "Call dentist to schedule appointment"

# Work task
capture work "Review PR #42 before standup"

# Quick idea
capture home "Blog post idea: productivity tips for developers"

Alfred Integration (macOS)

MD Note Capture

An Alfred workflow for adding notes to markdown files and quick idea capture.

# Install the workflow and helper scripts
./install.sh

Type c in Alfred to:

• Select a note file to append text to <notes_dir>/<note-name>.md
• Select gmail to capture a quick idea via Gmail

Configuration

Configuration is handled by ~/.capture/config.json, which is created interactively during ./install.sh:

{
  "notes_dir": "~/Documents/Notes",
  "repos_dir": "~/repos"
}

notes_dir — Directory where markdown notes are stored (must contain .md files) repos_dir — Directory containing git repositories (used for note icons)

Window Management with AeroSpace

For the best experience, use aerospace-setup to manage your windows. It includes:

• Automatic workspace organization for Cursor projects
• alt+p to switch between projects
• alt+s to organize windows by priority
• Optional alt+c keybinding for instant capture (auto-detected during install)

Hotkey Integration

AutoHotkey (Windows)

1. Install AutoHotkey
2. Copy autohotkey/capture-home.ahk.example to capture-home.ahk
3. Edit the target if needed and run the script
4. Press F1 to capture thoughts instantly

Troubleshooting

First Run Authentication

On first use, a browser window opens for Gmail authorization. Grant access to allow capture to send emails on your behalf.

Missing Config Files

If you see "Missing required configuration files":

1. Ensure client_secret.json exists in your config directory
2. Create targets.json with at least one target defined
3. Run capture again to authenticate

---

Built with Python and Gmail API

License

MIT