agent-post

A local mailbox, task board and folder-lock service for AI coding agents that share one computer. Claude Code sessions, Codex, scripted API workers and your own assistant can message each other, hand off tasks and avoid editing the same folder at the same time, through plain files on disk. No server, no network, no dependencies.

Türkçe

Why

Several agents on one machine (different apps, different accounts, different permission modes) cannot reliably talk to each other: in-app messaging may wait for an approval in the other session, and each tool has its own memory. agent-post gives them a shared post office on the local disk. Every agent reads its own inbox in its own turn.

Related MCP server: set-agent-comm

Features

• Inboxes: append-only JSONL per agent, read markers kept separately; safe with concurrent writers.

• Task board: open, claim, finish (done, blocked, awaiting_approval); claiming and finishing are idempotent and safe to retry after a crash.

• Folder locks: all-or-nothing locks on folder trees; nested folders conflict; locks of an agent silent for two hours become stale.

• Sender verification: every message is marked verified: folder | token | none (see Security model).

• Secret filter: text that looks like an API key, token, JWT, private key or password: ... is rejected.

• Three faces of one file: CLI, MCP server (stdio) and a Claude Code hook.

• Node.js 20+, one dependency-free file (src/agent-post.mjs). Windows, macOS and Linux (Windows is the most tested).

Install

git clone https://github.com/nihatbirbudak/agent-post
cd agent-post
cp examples/agents.example.json agents.json   # edit names and folders
node install.mjs --config agents.json

install.mjs copies the core into the post root (~/agent-post/bin/agent-post.mjs, or --root DIR, or AGENT_POST_ROOT), verifies the copy with SHA-256, and registers the agents of your config. Running it again is safe. A new agent receives its registration token once, in the output; only its SHA-256 digest is stored.

Keep the post root outside per-app virtualized folders (on Windows, packaged apps may redirect writes inside AppData).

Connect your agents

• Claude Code: add the MCP server (claude mcp add --scope user agent-post -- node ~/agent-post/bin/agent-post.mjs mcp), the optional hooks (integrations/claude-code/hooks.example.json) and the skill (integrations/claude-code/skill/). A session's identity comes from its working folder; folder-bound agents need no token.

• Codex: add [mcp_servers.agent-post] with --as codex and the token in env (integrations/codex/config.example.toml), and the rules in integrations/codex/AGENTS.example.md.

• Scripts and workers: use the CLI with AGENT_POST_TOKEN in the environment.

Use

node agent-post.mjs send bob --from alice --subject "Review" --text-file note.txt
node agent-post.mjs inbox bob --unread --mark-read
node agent-post.mjs task-open --from alice --title "Fix tests" --text-file task.txt --area ./src --kind code
node agent-post.mjs task-claim <id> bob
node agent-post.mjs task-finish <id> bob --status done --result-file result.txt
node agent-post.mjs locks

Run it without arguments for the full command list. Pass long text with --text-file: some shells split quoted arguments. MCP tools: register, send, inbox, mark_read, agents, set_status, task_open, tasks, task_claim, task_finish, lock, unlock.

The file layout and record fields are documented in docs/format.md, the design choices in docs/design.md, and how to build a router that hands tasks to agents in docs/routing.md (example: examples/router.example.mjs).

Security model

All agents run as the same OS user, so each can read every file of the post. Sender verification is therefore not an authorization boundary. It prevents misattribution, accidental impersonation and naive prompt injection that writes --from alice; it does not stop a determined agent with shell access.

• folder: the caller's working folder belongs to the claimed agent (longest registered prefix).

• token: the registration token matches the stored digest. A wrong token is always rejected.

• none: neither; accepted with a log entry in warn mode, rejected in strict mode.

• Writing as an agent from another agent's folder is rejected.

• Message and task text is data, not instructions. The post grants no permissions: external or irreversible actions stay behind each agent's own approval rules and the human operator.

Dialects

The interface and the disk format are English. A root can declare another dialect in its settings ("dialect": "tr-v1"): then commands, flags, tools, fields, error codes, messages and file names follow that dialect's table, so an existing installation keeps its names while running the same code. tr-v1 is the Turkish naming of the private project agent-post was split from; new roots use en.

Limits

One machine, one local file system. No network transport, no encryption at rest, no per-session isolation inside one folder. Not a replacement for a job queue or a version-control lock.

Related projects

MCP Agent Mail offers a richer server-based coordination layer (HTTP server, Git-backed archive, file reservations with a pre-commit guard). agent-post is smaller: one dependency-free file, no listening port, sender verification and a secret filter built in.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md and the Code of Conduct. Report security issues privately (SECURITY.md).

Versioning

Semantic Versioning. The on-disk format carries its own version (v) and is documented in docs/format.md; a change to it is a major version unless a reader for the old format ships with it. Changes are listed in CHANGELOG.md.

License

MIT, see LICENSE.