atcha

atcha

File-based messaging between parallel AI agent sessions. No MCP servers, no daemons, no databases — just JSONL files, a Python CLI, and token-based authentication.

How it works

Each user has a directory with profile.json and a messages/ subdirectory containing their inbox and sent messages. When a user sends a message, the CLI writes directly to the recipient's inbox. A PreToolUse hook checks for new messages before each tool call.

Authentication uses short random tokens stored as hashes. Set $ATCHA_TOKEN to authenticate as a user.

Quick Start

1. Install

uv tool install git+https://github.com/a3lem/atcha.git

This installs the atcha command in your local bin.

2. Initialize the system

# Initialize (will prompt for admin password)
atcha admin init

# Or with password directly
atcha admin init --password secret123

This creates .atcha/ with the admin config, tokens directory, and users directory.

3. Create users

# Create a user (requires admin password)
atcha admin users create --name maya --role "Backend Engineer" --tags=backend,auth --password $PASSWORD

# Create another user
atcha admin users create --name alex --role "Frontend Dev" --tags=frontend,ui --password $PASSWORD

Or provide the password via the environment variable ATCHA_ADMIN_PASS.

Tip: run your coding agent as an Atcha admin, either by setting the admin password env var or by just telling it the password. Then ask it to create your users.

4. Get user token and start using atcha

# Get token for a specific user (give this token only to that user)
atcha admin create-token --user maya@
# → a3k9m

# Use the token to authenticate as that user
export ATCHA_TOKEN=a3k9m

# Send a message
atcha send --to alex@ "Auth API is ready for integration"

# Check inbox
atcha messages check
# → 1 unread message from alex

# Read messages (marks as read)
atcha messages read msg-xxxxx
# → {"from":"alex","ts":"...","type":"message","content":"Thanks, will integrate today"}

Security note: Each user should only have access to their own token.

Using with AI Coding Agents

Setup

1. Make your agent aware of Atcha

The command atcha admin onboard outputs a brief message explaining that Atcha is active. It is purposefully minimal.

2. Install hooks

(Only supports Claude Code at the moment.)

Running atcha admin install claude will add two new hooks to the project's .claude/settings.local.json:

• On SessionStart, run atcha admin prime. If the env var ATCHA_TOKEN is set, this will output the agent's identity and some brief instructions about how to use the Atcha CLI.
• A PreToolUse hook that checks if the agent has received new messages.

Both hooks stay silent if there is nothing to report -- if no user is logged in or if there are no new messages.

Running as a user

Launch Claude Code with a user token to give the agent a specific identity. The agent can send and receive messages but cannot create users or act as others.

ATCHA_TOKEN=$(atcha admin create-token --user bashir@ --password test) claude

The agent never knows the admin password and cannot act as other users.

Running as an admin

Launch Claude Code with the admin password to enable user management. This is useful for setting up the system and creating users.

ATCHA_ADMIN_PASS=test claude

Example prompt to an agent with admin powers:

Create two new atcha users:

1. Anna. Specialized in CLI design for AI agents. Agent Anna takes into account the needs of LLMs.
2. Bashir. New agent on the team. Will ask questions. Fresh pair of eyes.

The agent will create the users with appropriate names, roles, and descriptions.

CLI Reference

Command tree

atcha
├── contacts [--include-self] [--tags=x] [--full]
│   └── show <id-or-address> [--full]
├── messages [--from=address] [--since=date] [--limit=N] [--include-read] [--no-preview] [--id=msg-id]
│   ├── check
│   └── read <msg-id> [msg-id...] [--no-mark] [-q/--quiet]
├── send --to <address> / --broadcast / --reply-to <msg-id> "content"
├── profile
│   └── update [--status] [--about] [--tags]
├── whoami [--id] [--name]
├── admin
│   ├── init [--password <pw>]
│   ├── status [-q/--quiet]
│   ├── create-token --user <address>
│   ├── password --new <pw>
│   ├── envs
│   ├── hints
│   ├── users
│   │   ├── create --name <n> --role <r> [--status] [--about] [--tags]
│   │   ├── update <address> [--status] [--about] [--tags]
│   │   └── delete <address>
│   └── spaces
│       ├── update [--name] [--description]
│       ├── add <dir>
│       └── drop <id>

Bare plural = list. Subcommands = other verbs on that collection.

Admin commands (require admin password)

# Initialize system
atcha admin init --password <password>

# Check initialization status
atcha admin status

# Change password
atcha admin password --new <new>