Digitize Handwritten Notes with AI CLI: Photos to Structured Markdown

The Notebook That Remembers Everything and Retrieves Nothing

She had three notebooks from last semester. Organic chemistry, molecular biology, European history. Somewhere in those six hundred pages was a diagram she drew during a lecture in October -- a reaction mechanism that explained the one concept the final exam always tested. She remembered drawing it. She remembered the green pen. She could not remember whether it was in the first notebook or the third, whether it was near the front or the back, or whether it was on a right-hand page or a left-hand page.

She flipped. Page after page. Past grocery lists that had migrated into the margins of her biology notes. Past a phone number with no name. Past three pages of crossed-out false starts on an essay outline. The diagram was not there. It was not in the second notebook either. She found it in the third, 40 minutes later, wedged between a to-do list and a drawing of a cat.

This is the fundamental paradox of handwritten notes. The act of writing helps you learn. Research confirms this repeatedly -- handwriting activates deeper cognitive processing than typing. But the notes themselves become almost useless for retrieval. A notebook has no search bar. No tags. No links. It is a sequential storage medium in a world that demands random access.

What if you could keep the learning benefits of handwriting and gain the retrieval power of digital? Not by switching to a tablet. Not by retyping everything. By photographing your notebooks and letting an AI read them -- not just recognize the characters, but understand the content and restructure it into something searchable.

That is what this article builds. A workflow that turns a stack of notebook photos into a folder of clean, structured markdown files. The kind you can search, link, and actually find things in.

What You Will Build

The workflow is simple in shape:

1. Photograph your handwritten pages. Phone camera. Nothing special.
2. Feed the photos to Claude Code, which uses vision to read your handwriting.
3. The AI extracts and structures the content -- not as a flat transcription, but as organized markdown with headings, lists, tags, and integrated margin notes.
4. You get searchable files. One per topic, one per lecture, however you want them sliced.

The key distinction from traditional OCR: Claude does not just convert squiggles into characters. It reads the page the way a human would. A main paragraph with an arrow pointing to a margin note? The AI understands that the margin note is a comment on the paragraph and integrates it naturally. A list with some items circled and others crossed out? The AI recognizes which items are emphasized, which are deleted, and outputs only the relevant ones. A page that starts with chemistry and ends with a reminder to buy milk? The AI separates the chemistry content from the grocery note and files each where it belongs.

This is not OCR. This is reading comprehension.

Prerequisites

• Claude Code installed and authenticated. If you have not set it up yet, follow the first hour tutorial -- ten minutes.
• A phone with a camera. Any phone made in the last decade works.
• Handwritten notes you want to digitize. Notebooks, loose pages, Post-its, index cards, napkins -- anything with writing on it.
• Basic terminal comfort. You will type commands. No programming required.

Step 1: Photograph Your Notes

The quality of the output depends on the quality of the input. Not artistic quality -- legibility quality. A few rules:

Lighting matters more than camera quality. Photograph in daylight or under a bright desk lamp. Avoid shadows falling across the page. The number one reason AI misreads handwriting is shadow obscuring strokes, not camera resolution.

Flatten the page. Curled notebook pages with text disappearing into the spine are hard for any reader, human or AI. Press the notebook flat. Use a book weight or a second phone.

One page per photo. Do not try to capture a two-page spread. The resolution per page drops, and text near the spine gets distorted. One photo, one page.

Shoot straight down. Angle distortion makes letters ambiguous. An a shot at 30 degrees can look like an o. Hold the phone directly above the page.

Organize the photos into a folder:

mkdir -p ~/handwritten-notes/photos
# Transfer photos from your phone to this folder
# Use AirDrop, USB, cloud sync -- whatever works

Name the files in order if possible. Most phones timestamp photos, which preserves sequence. If you are photographing multiple notebooks, use subfolders:

~/handwritten-notes/photos/
  orgchem-notebook/
    IMG_0401.jpg
    IMG_0402.jpg
    IMG_0403.jpg
    ... (80 pages)
  biology-notebook/
    IMG_0501.jpg
    IMG_0502.jpg
    ... (120 pages)
  history-notebook/
    IMG_0601.jpg
    IMG_0602.jpg
    ... (90 pages)

Step 2: Set Up the Instructions

Create a CLAUDE.md file in your working directory. This tells the AI exactly how you want the output structured:

# Handwritten Note Digitization Rules

## Goal

Read photos of handwritten notebook pages. For each page, extract the
content, understand its structure, and output clean structured markdown.

## Input

Photos are in ~/handwritten-notes/photos/, organized by notebook.

## Output

Write organized markdown files to ~/handwritten-notes/output/.

## Reading Rules

1. READ the handwriting carefully. If a word is unclear, use surrounding
   context to infer it. Mark truly illegible words as [illegible].
2. UNDERSTAND the structure of the page. Identify:
   - Main content vs. margin notes
   - Headings vs. body text
   - Lists (numbered or bulleted)
   - Diagrams (describe them in words)
   - Crossed-out text (skip it unless it seems intentional)
   - Circled or highlighted items (mark as emphasized)
   - Arrows connecting ideas (integrate the connection in the output)
3. SEPARATE unrelated content on the same page. Chemistry notes and a
   grocery list on the same page become two different entries.
4. INTEGRATE margin notes into the main content where they belong.
   A margin note next to a paragraph is a comment on that paragraph --
   include it as a parenthetical or a blockquote, not as a separate section.

## Output Format

For each notebook, create markdown files organized by topic or lecture:

  ~/handwritten-notes/output/{notebook-name}/{topic}.md

Each file must include:

### Frontmatter
---
title: "Descriptive Topic Title"
date: YYYY-MM-DD (estimated from context, or "unknown")
source: notebook name and page numbers
tags:
  - subject-tag
  - topic-tag
---

### Content
- Clear headings (H1 for the topic, H2 for subtopics)
- Clean formatted text with proper markdown
- Lists preserved as markdown lists
- Diagrams described in blockquotes: > **Diagram:** description
- Key terms in **bold**
- Formulas in inline code or code blocks
- Margin notes as blockquotes: > **Note:** content

### Cross-References
- If content on one page references content on another, add links
  between the output files: [See Topic Name](./topic-name.md)

## Quality Rules

- Never invent content that is not on the page.
- Preserve the author's meaning, even if the grammar is rough.
- Clean up obvious abbreviations: "w/" becomes "with", "bc" becomes
  "because", "govt" becomes "government" -- unless the abbreviation
  is a standard term in the field.
- Keep technical notation exact. Do not expand chemical formulas or
  mathematical symbols.

## Index

Generate ~/handwritten-notes/output/INDEX.md listing:
- Every notebook processed
- Every topic file created, with page number references
- A tag cloud showing the most frequent topics

This is the brain of the operation. Adjust the output format to match how you think. A student might want files per lecture. A researcher might want files per experiment. A cook digitizing a recipe notebook might want files per dish.

Step 3: Run the Digitization

cd ~/handwritten-notes
claude

In the Claude Code prompt:

Read CLAUDE.md for instructions. Then process all photos in photos/orgchem-notebook/.
For each page, read the handwriting, extract the content, and write
structured markdown files to output/orgchem-notebook/.
Show me the first 3 pages as a preview before processing the rest.

The preview step is important. It lets you calibrate before the AI processes 80 pages. You might discover that your abbreviations need different expansion rules, or that the AI is misreading your t as an l. Fix the instructions early.

The preview output for a single page might look like this:

## Page 1 (IMG_0401.jpg) - Preview

**Detected content:** Lecture notes on nucleophilic substitution reactions
**Structure:** Title, three subsections, two diagrams, margin notes on right side

**Proposed output:**

```markdown
---
title: "Nucleophilic Substitution: SN1 vs SN2"
date: 2025-09-15
source: orgchem-notebook, page 1
tags:
  - organic-chemistry
  - reaction-mechanisms
  - substitution
---

# Nucleophilic Substitution: SN1 vs SN2

## SN2 Mechanism

- Single concerted step
- **Backside attack** by nucleophile
- Rate = k[substrate][nucleophile]
- Inversion of stereochemistry

> **Diagram:** Newman projection showing nucleophile approaching
> from the back side of the carbon bearing the leaving group.
> Arrow shows simultaneous bond formation (Nu-C) and bond
> breaking (C-LG).

> **Note:** "This is the one Prof. Kim always puts on exams.
> Pay attention to the stereochemistry flip."

## SN1 Mechanism

- Two-step process: ionization then nucleophilic attack
- Rate = k[substrate] (first order -- nucleophile not in rate equation)
- Carbocation intermediate forms
- Racemization at the stereocenter (attack from both faces)

> **Diagram:** Energy diagram showing two transition states
> with a carbocation intermediate valley between them.
> E_a for step 1 (ionization) is higher than E_a for step 2.

## When to Expect Which

| Factor | Favors SN2 | Favors SN1 |
|--------|-----------|-----------|
| Substrate | Primary, methyl | Tertiary |
| Nucleophile | Strong | Weak (or solvent) |
| Solvent | Polar aprotic | Polar protic |
| Leaving group | Good LG for both | Good LG for both |

[See Elimination Reactions](./elimination-reactions.md) for the
competing E1/E2 pathways.
```

Look at what happened. A single handwritten page with arrows, circled terms, margin scrawls, and two diagrams became a clean, structured document. The margin note about Prof. Kim's exam preferences is preserved as context, right next to the relevant content. The diagrams are described in enough detail to be useful. The comparison table was probably not a table in the notebook -- it was likely a scattered set of bullet points -- but the AI understood the underlying comparison and structured it as a table.

If the preview looks good:

This looks correct. Process all remaining pages in orgchem-notebook/.

Step 4: Handle the Hard Cases

Not every page is a clean set of lecture notes. Notebooks are messy. Here is how the AI handles real-world chaos.

Pages with Mixed Content

A single page might contain biology lecture notes at the top, a reminder to email your advisor in the middle, and a doodle of a molecule at the bottom. The AI separates these. The lecture notes go into the biology file. The reminder goes into a misc/tasks.md file or gets skipped entirely, depending on your instructions.

Terrible Handwriting

Everyone thinks their handwriting is the worst. It usually is not. Claude's vision capability handles most handwriting styles, including cursive, print-cursive hybrid, and the compressed scrawl that happens when you are writing faster than the professor is talking. When it truly cannot read a word, it marks [illegible] and moves on. You can search your output files for [illegible] later and fill in the gaps from memory -- which is easier when the surrounding context is already clean.

Diagrams and Drawings

A flowchart. A circuit diagram. A map of the nervous system. The AI cannot reproduce these as images, but it can describe them with enough precision that the description is useful for studying. A reaction mechanism diagram becomes a step-by-step textual description. A flowchart becomes a nested list. If you need the actual diagram, the output file references the original photo path.

Multi-Language Notes

If you switch between English and another language in your notes -- a common pattern for bilingual students -- the AI handles both. It preserves the original language rather than translating, unless you instruct otherwise.

Step 5: Batch-Process All Notebooks

Once you have calibrated with one notebook, process the rest:

Now process photos/biology-notebook/ and photos/history-notebook/
using the same rules. Output to their respective directories.

For a large batch -- say, 300 pages across three notebooks -- this takes time. Claude Code works through the pages sequentially, reading each image and writing each output file. You can watch the progress or go do something else. The output accumulates in your folder as files, so you can start reading the early results while later pages are still processing.

After all notebooks are processed, generate the master index:

Generate INDEX.md as specified in CLAUDE.md.
Include a summary of what was processed and a tag cloud.

The index becomes your entry point. Every topic, every lecture, every notebook -- searchable from one file.

Step 6: Make It Searchable

Your output folder is now full of structured markdown files. Here is the payoff.

Find that chemistry diagram:

cd ~/handwritten-notes/output
grep -r "reaction mechanism" --include="*.md" -l

Three results in 0.2 seconds. The diagram you spent 40 minutes flipping for is in orgchem-notebook/nucleophilic-substitution.md, line 34.

Find everything about a specific topic:

grep -r "mitochondria" --include="*.md" -l

It appears in your biology notes, your history notes (in a section about the history of cell biology), and surprisingly in your chemistry notes where the professor mentioned ATP synthesis. Three connections you never would have found by flipping.

Use with any markdown tool. The output files work in Obsidian, VS Code, Notion (import markdown), Bear, or any text editor. They are just files. No lock-in.

Want to go further? The scattered notes organization guide shows how to take these markdown files and organize them into a fully linked Obsidian vault with wikilinks, tags, and a knowledge graph.

The Script for Ongoing Digitization

You will take more handwritten notes. New notebooks will fill up. Here is a script that processes new photos incrementally:

#!/usr/bin/env bash
set -euo pipefail

PHOTOS_DIR="${1:?Usage: digitize-notes.sh <photos-directory>}"
OUTPUT_DIR="${2:-$(dirname "$PHOTOS_DIR")/output}"
PROCESSED_LOG="$OUTPUT_DIR/.processed-photos.txt"

mkdir -p "$OUTPUT_DIR"
touch "$PROCESSED_LOG"

# Find photos not yet processed
NEW_PHOTOS=$(comm -23 \
  <(find "$PHOTOS_DIR" -type f \( -name "*.jpg" -o -name "*.jpeg" -o -name "*.png" -o -name "*.heic" \) | sort) \
  <(sort "$PROCESSED_LOG"))

NEW_COUNT=$(echo "$NEW_PHOTOS" | grep -c '.' || true)

if [[ "$NEW_COUNT" -eq 0 ]]; then
  echo "No new photos to process."
  exit 0
fi

echo "Found $NEW_COUNT new photos to digitize."

claude -p "You are a handwritten note digitizer.
Read the CLAUDE.md in $(dirname "$PHOTOS_DIR") for rules.

These are NEW photos to process:
$NEW_PHOTOS

Read the handwriting in each photo, extract and structure the content,
and write organized markdown to $OUTPUT_DIR/.
Append new entries to existing topic files where relevant.
Update INDEX.md with new entries.

After processing, list each file you processed (one per line, full path)."

echo "$NEW_PHOTOS" >> "$PROCESSED_LOG"
echo "Done. $NEW_COUNT pages digitized to $OUTPUT_DIR."

Run it whenever you photograph new pages. Each run only processes what is new.

What Changed

Before: three notebooks with six hundred pages of handwritten notes. A linear, unsearchable archive. Finding anything meant flipping through every page. The knowledge you wrote down was effectively locked inside a medium that could not be searched, linked, or queried.

After: a folder of structured markdown files. Every lecture, every topic, every margin note -- searchable in under a second. Diagrams described in text. Margin scrawls integrated into the content they annotate. Cross-references linking related topics across notebooks. An index that maps your entire semester of notes.

The handwriting did its job during the lecture -- it helped you encode the knowledge into your brain. The AI did the job the handwriting could not -- it made that knowledge retrievable. You kept the pen. You gained the search bar.

The notebooks are still there. The photos are still there. Nothing was lost or replaced. You just built a second interface to the same knowledge -- one that can answer the question "where did I write about reaction mechanisms?" in 0.2 seconds instead of 40 minutes.

For more on getting started with Claude Code, see the first hour walkthrough. For organizing all your digital notes alongside the digitized handwritten ones, see the full note organization guide.