Works with AI
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.
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.
Your AI creates a folder with a
content.md file and updates the
project's .project.json.
The built-in file watcher picks up new and modified files within ~1 second. No restart needed.
Your kanban board updates silently. New tasks show up exactly where they belong.
Any AI assistant with filesystem access works out of the box. Here's how to use each one.
Claude Code has full filesystem access and understands Postal's format natively. Just tell it what to do.
Add a task called "Fix login bug" to my Work project in Postal.
My workspace is at ~/Documents/Postal
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.
The ChatGPT desktop app can read files from your computer. Ask it to generate task files and save them directly to your Postal workspace.
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's agent mode can read and write files. Point it at your Postal workspace and it manages tasks alongside your code.
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.
Copilot's agent mode in VS Code can create and modify files. Use it to keep your Postal board in sync as you code.
@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.
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.
#!/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)
#!/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)
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.
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
...
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.
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"
}
}
}
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.
Your AI agent already has filesystem access. No OAuth flows, no API rate limits, no authentication headaches.
Claude Code, Cursor, and Copilot can all write files natively. No marketplace plugins, no extensions to install.
Your AI agent writes to your local disk. No internet connection needed for the task management side. The board updates locally.
Plain Markdown and JSON. Read them, grep them, pipe them, version-control them. No proprietary lock-in. Ever.
Postal's file watcher detects changes within one second. Your AI creates a task and you see it on your board almost immediately.
Chain Postal with GitHub issues, CI/CD, email parsers, or cron jobs. If it can write a file, it can manage your board.
Download Postal and start managing tasks with your AI assistant today.