How do I connect Claude Code to Postal?

Add Postal integration instructions to your CLAUDE.md file (either ~/.claude/CLAUDE.md for global access or a project-level CLAUDE.md). The instructions tell Claude Code to use the postal CLI at ~/.local/bin/postal for quick task capture. For full workspace access, open your Postal workspace folder directly in Claude Code.

Can Claude Code read and edit Postal tasks?

Yes. Claude Code has full filesystem read/write access. When you open your Postal workspace folder, Claude Code can read AGENT.md (the file format spec), then read .project.json for task metadata, create new tasks by writing content.md files, edit task notes, mark tasks complete, and perform bulk operations.

What is CLAUDE.md and how does it work with Postal?

CLAUDE.md is Claude Code's instruction file. You can place it globally at ~/.claude/CLAUDE.md or per-project. By adding Postal instructions to this file, Claude Code automatically knows how to use the postal CLI to capture tasks, notes, and research items whenever you ask.

Claude Code + Postal - Manage Tasks from Your Terminal

Three ways to connect

Pick the method that fits your workflow, or combine them all.

Method 1: CLI capture

2 minutes

Add a few lines to your CLAUDE.md file and Claude Code learns to use the postal CLI. Say "remember this" or "save this to Postal" and it runs the command for you.

Add to ~/.claude/CLAUDE.md (global) or your project's CLAUDE.md

## Postal Integration
When the user asks you to "remember this", "save this to Postal",
"make a note of this", or "capture this", run the Postal CLI:

~/.local/bin/postal "the text to capture"

Options:
- --label NAME      assign a label (e.g. --label Work)
- --type TYPE       set type: note (default), task, research
- --due YYYY-MM-DD  set a due date
- --workspace NAME  target a specific workspace

That's it. Now you can say things like:

What you say to Claude Code

"Remember to follow up with Chris on Friday"

"Save this to Postal: the auth service needs a rate limiter"

"Capture this as a Work task due next Monday: deploy v2.1"

What Claude Code runs

~/.local/bin/postal "Follow up with Chris on Friday"

~/.local/bin/postal "The auth service needs a rate limiter"

~/.local/bin/postal --label Work --type task --due 2026-03-23 "Deploy v2.1"

The CLI writes directly to your workspace on disk. Postal detects the change within ~1 second and the task appears on your board.

Method 2: Full workspace access

5 minutes

Open your Postal workspace folder directly in Claude Code. It reads AGENT.md (the file format spec that ships with Postal) and gets full read/write access to every task, note, and label.

Open your workspace in Claude Code

claude --dir ~/Documents/Postal

Claude Code reads AGENT.md automatically and understands the file structure. Now you can ask it to:

Read and search your tasks

"What tasks do I have labeled Work?"
→ Reads .project.json, filters by labelId, lists matches

"Find any tasks mentioning the API redesign"
→ Searches content.md files across all task folders

"What's overdue?"
→ Reads due dates from .project.json, compares to today

Create and edit tasks

"Create a task called 'Fix login bug' with notes about the auth timeout"
→ Creates task folder + content.md, updates .project.json

"Add detailed notes to the 'Deploy v2' task about the migration steps"
→ Reads existing content.md, appends new Markdown content

"Mark all tasks older than 30 days as completed"
→ Bulk updates .project.json (completed: true, completedAt: timestamp)

Claude Code has full filesystem access — it can create task folders, write content.md files, and update .project.json metadata. Postal's file watcher picks up changes within ~1 second.

Method 3: Both (recommended)

Best

Combine CLAUDE.md instructions for quick capture with workspace access for full management. Each method serves a different moment.

Quick capture via CLI

# You're deep in a coding session and think of something:
"Remember to update the changelog before release"
→ Claude Code runs: postal "Update changelog before release"

# Capture a task with context:
"Save this as a Work task: Chris mentioned the billing endpoint
needs to handle European VAT codes"
→ Claude Code runs: postal --label Work --type task "..."

Deep management via workspace

# When you need to actually work with your tasks:
claude --dir ~/Documents/Postal

"Reorganize my tasks: move everything related to the API
redesign under the Backend label"

"Write a summary of what I accomplished this week based
on my completed tasks"

"Create five tasks from this meeting transcript..."

The CLI is for quick "save this thought" moments during any session. Workspace access is for when you need Claude Code to read, search, and restructure your entire board.

What Claude Code can do with your board

Capture from anywhere

Working in any project, any terminal session. Say "remember this" and the postal CLI saves it to your board. No context switching.

Search all your tasks

Claude Code can grep through every content.md file and read .project.json metadata. Ask it to find tasks by keyword, label, date, or status.

Create tasks with rich notes

New tasks get a folder, a content.md with Markdown notes, and a metadata entry in .project.json. Full formatting, checklists, code blocks.

Edit and update tasks

Append notes to existing tasks, change titles, set due dates, assign labels, mark tasks complete. Claude Code reads and writes the files directly.

Bulk operations

"Label all tasks containing 'API' as Backend." "Archive everything completed before March." Claude Code loops through .project.json and handles it.

Weekly reviews

Ask Claude Code to summarize your completed tasks, list what's overdue, and suggest priorities for next week — all from the files on disk.

Claude Code + Postal