Your AI assistant
can manage your board

Postal stores tasks as plain files on disk. If your AI agent can write a file, it can create tasks, organize projects, and track your progress. No API keys, no plugins, no setup.

How it works

Postal's file format is intentionally simple. Tasks are Markdown files. Metadata is JSON. A built-in file watcher detects changes within one second. That's all your AI agent needs to know.

1

Agent writes files

Your AI creates a folder with a content.md file and updates the project's .project.json.

2

Postal detects the change

The built-in file watcher picks up new and modified files within ~1 second. No restart needed.

3

Tasks appear on your board

Your kanban board updates silently. New tasks show up exactly where they belong.

Works with every AI coding tool

Any AI assistant with filesystem access works out of the box. Here's how to use each one.

Claude Code

Anthropic

Claude Code has full filesystem access and understands Postal's format natively. Just tell it what to do.

What you say
Add a task called "Fix login bug" to my Work project in Postal.
My workspace is at ~/Documents/Postal
What Claude Code does
1. Reads ~/Documents/Postal/.workspace.json
2. Finds the "Work" project path
3. Reads ~/Documents/Postal/Work/.project.json
4. Creates a new task folder with content.md
5. Updates .project.json with the task entry
   → Task appears on your board within 1 second

Drop Postal's AGENT.md into your project root and Claude Code will reference it automatically.

ChatGPT

OpenAI

The ChatGPT desktop app can read files from your computer. Ask it to generate task files and save them directly to your Postal workspace.

Example prompt
I use Postal for task management. My workspace is at
~/Documents/Postal. Create a new task in my "Work"
project called "Prepare Q2 roadmap" with notes about
the key milestones. Save the files to my workspace
using the AGENT.md format.

ChatGPT can also generate shell scripts that create tasks in bulk — useful for importing from other tools or setting up a new workspace.

Cursor

AI IDE

Cursor's agent mode can read and write files. Point it at your Postal workspace and it manages tasks alongside your code.

Example prompt in Cursor
Read the AGENT.md file in this project, then create
a task in my Postal workspace at ~/Documents/Postal
in the "Backend" project called "Add rate limiting
to /api/auth endpoint" with notes about the approach.

Cursor respects .cursorrules files. Add a reference to AGENT.md so the agent always knows the format.

GitHub Copilot

GitHub

Copilot's agent mode in VS Code can create and modify files. Use it to keep your Postal board in sync as you code.

Example in Copilot Chat
@workspace Look at the AGENT.md file for the Postal
task format. Create a new task in my "Frontend" project
called "Migrate to React 19" with notes listing the
breaking changes we need to handle.

Works with Copilot's @workspace agent which has full file read/write access in your project.

Shell scripts & automation

Any language

A five-line shell script can create tasks from GitHub issues, emails, CI failures, or any source. The format is simple enough to write by hand.

Create a task in 5 lines
#!/bin/bash
PROJ="$HOME/Documents/Postal/Work"
FID=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-z0-9' | head -c 8)
mkdir -p "$PROJ/$FID"
echo "# Deploy v2.1 to production" > "$PROJ/$FID/content.md"
# Update .project.json with jq (see AGENT.md for full recipe)
Import GitHub issues
#!/bin/bash
# Pull open issues and create Postal tasks for each one
PROJ="$HOME/Documents/Postal/GitHub Issues"
gh issue list --json title,body --limit 20 | jq -c '.[]' | while read issue; do
    TITLE=$(echo "$issue" | jq -r '.title')
    BODY=$(echo "$issue" | jq -r '.body // empty')
    FID=$(cat /dev/urandom | LC_ALL=C tr -dc 'a-z0-9' | head -c 8)
    mkdir -p "$PROJ/$FID"
    printf "# %s\n\n%s\n" "$TITLE" "$BODY" > "$PROJ/$FID/content.md"
done
# Then update .project.json (see AGENT.md for full format)

The AGENT.md format

Postal's file format is an open specification. Any tool that can read and write files can integrate with it. Here's the complete structure.

Directory structure

workspace/
  .workspace.json         # Workspace config
  My Project/             # Project folder
    .project.json         # Project + task metadata
    k7m2x9pq/            # Task folder (8-char ID)
      content.md          # Task title + notes
      attachments/        # Optional files
    b3n5h8wr/
      content.md
  Another Project/
    .project.json
    ...

content.md — task content

First # Heading is the title. Everything after is Markdown notes.

# Fix authentication timeout

The session expires after 15 minutes even when
the user is active. Needs investigation.

## Steps to reproduce
1. Log in and stay on the dashboard
2. Wait 15 minutes without navigating
3. Next action returns 401

## Possible fix
Check the `refreshToken` middleware — it may
not be extending the session on API calls.

.project.json — project metadata

Stores the project name, color, and all task metadata.

{
  "version": 1,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Project",
  "color": "#3B82F6",
  "createdAt": "2026-02-07T15:30:00.000Z",
  "tasks": {
    "k7m2x9pq": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "title": "Fix authentication timeout",
      "completed": false,
      "completedAt": null,
      "order": 0,
      "createdAt": "2026-02-07T15:30:00.000Z"
    }
  }
}

.workspace.json — workspace config

Tracks which projects exist, their column positions, and display order.

{
  "version": 1,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Workspace",
  "createdAt": "2026-02-07T15:30:00.000Z",
  "projects": [
    {
      "id": "project-uuid-here",
      "hint": "~/workspace/My Project",
      "column": 0,
      "order": 0
    }
  ]
}

The full specification — including ID generation, ordering rules, and more recipes — ships with every copy of Postal as AGENT.md in the app bundle.

Why file-based is better for AI

No API keys or tokens

Your AI agent already has filesystem access. No OAuth flows, no API rate limits, no authentication headaches.

No plugins needed

Claude Code, Cursor, and Copilot can all write files natively. No marketplace plugins, no extensions to install.

Works offline

Your AI agent writes to your local disk. No internet connection needed for the task management side. The board updates locally.

Open, portable format

Plain Markdown and JSON. Read them, grep them, pipe them, version-control them. No proprietary lock-in. Ever.

Instant feedback

Postal's file watcher detects changes within one second. Your AI creates a task and you see it on your board almost immediately.

Scriptable & composable

Chain Postal with GitHub issues, CI/CD, email parsers, or cron jobs. If it can write a file, it can manage your board.

Try it free for 10 days

Download Postal and start managing tasks with your AI assistant today.