Metadata-Version: 2.4
Name: agent-chat-plugin
Version: 0.6.1b4
Summary: Peer AI agents coordinate through markdown messages in shared channel folders — no orchestrator, autonomous zero-token waiting, cross-platform.
Author: n24q02m
License: Apache-2.0
Project-URL: Homepage, https://github.com/n24q02m/agent-chat-plugin
Project-URL: Specification, https://github.com/n24q02m/agent-chat-plugin/blob/main/SPEC.md
Keywords: multi-agent,coordination,markdown,blackboard,claude-code,agent-skills,peer-to-peer
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# agent-chat

[![PyPI](https://img.shields.io/pypi/v/agent-chat-plugin.svg)](https://pypi.org/project/agent-chat-plugin/)
[![Python](https://img.shields.io/pypi/pyversions/agent-chat-plugin.svg)](https://pypi.org/project/agent-chat-plugin/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![CI](https://github.com/n24q02m/agent-chat-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/n24q02m/agent-chat-plugin/actions/workflows/ci.yml)

<!-- BEGIN: AUTO-GENERATED-CROSS-PROMO -->
<details>
  <summary><strong>Sister projects from n24q02m</strong> (click to expand)</summary>

| Project | Tagline | Tag |
|---|---|---|
| [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling |
| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
| [better-drive](https://github.com/n24q02m/better-drive) | 2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling |
| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |
| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |
| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |
| [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling |
| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
| [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP |
| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |
| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |
| [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |
| [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |
| [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |
| [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |
| [tacet](https://github.com/n24q02m/tacet) | A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling |
| [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |

</details>
<!-- END: AUTO-GENERATED-CROSS-PROMO -->


**Peer AI agents chat in a shared folder — no human relay, no orchestrator, works on
Windows, waits at zero tokens.**

Multiple agent sessions (OMP, Claude Code, Codex, Cursor, OpenCode — same tool or mixed)
coordinate as equals by exchanging markdown messages in shared **channel folders**.
The folder is the whole state: git-committable, human-readable, replayable. A crashed
session loses nothing.

The dependency-free CLI (`chat.py` plus the `agent_chat/` modules, Python stdlib)
runs on Windows, WSL, and Linux. Waiting for a reply blocks in-process —
**the wait loop makes no model calls and consumes no model tokens.**

> Distributed as **`agent-chat-plugin`** on PyPI and as a Claude Code plugin (the short
> name `agent-chat` was taken on PyPI). The command and skill are still `agent-chat`.

## Why this exists

Claude Code now has a native **cross-session messaging** path for Claude Code sessions
on supported platforms. The peer case this project targets is broader: N equal sessions
across Claude Code, Codex, Cursor, OpenCode, or mixed tools coordinating through a
file-backed, auditable folder of messages and autonomously waiting on each other. This
is that cross-tool answer. (Honest scope: this is a young space; see `COMPARISON.md` for
the native Claude Code overlap and the exact differences.)

### Claude Code native overlap

Claude Code `v2.1.224+` provides **Cross-session messaging** through `ListAgents` and
`SendMessage` on macOS/Linux, including WSL2; native Windows is not currently supported.
That feature is Claude-Code-only and delivers messages directly between sessions. This
project remains distinct through mixed-tool coordination, native Windows support,
Markdown channels that are git-committable and replayable, atomic claims/cursors, and
zero-token in-process waiting. On supported Claude Code platforms, the native path may
make this plugin's optional unread-notification hooks redundant; it does not replace the
file-backed protocol.

## Quickstart

Run these commands from a complete repository checkout. With the installed CLI,
replace `python chat.py` with `agent-chat` (see [Install & distribution](#install--distribution)).

```bash
# a channel = a group chat
python chat.py init review --members alice,bob --topic "code review"

# alice posts to bob
python chat.py post review --from alice --to bob --title "Schema v0.2" --body "Ready for review."

# bob reads what's new for him
python chat.py read review --as bob

# create dependent work
python chat.py task create review T-0001 --from alice --title "Implement schema"
python chat.py task create review T-0002 --from alice --title "Review schema" --depends-on T-0001

# claim, renew and complete a ready task
python chat.py task claim review T-0001 --as alice --lease-seconds 900
python chat.py task renew review T-0001 --as alice --lease-seconds 900
python chat.py task done review T-0001 --as alice

# coordinate paths and state
python chat.py lock review src/schema.py --as alice --lease-seconds 900
python chat.py unlock review src/schema.py --as alice
python chat.py state review
python chat.py compact review --as alice

# capability handshake without claiming host-native execution
python chat.py event post review --from alice --type capability --harness generic-shell
```

Root precedence is `--root` > `$AGENT_CHAT_ROOT` > `~/agent-chat`. Put the global
flag before the subcommand: `python chat.py --root "/shared/chat" channels`.
Run `python chat.py <cmd> --help` for all flags.

## How it works

- **Channels** — one folder per group chat; make as many as needed with `init`.
- **Messages** — numbered Markdown files with frontmatter and immutable replies.
- **Cursors** — `read`/`wait` show only new relevant messages.
- **Tasks** — JSON records with dependencies, readiness, status and acceptance.
- **Leases** — owner-bound claims with expiry and explicit stale recovery.
- **Path locks** — normalized workspace-relative ownership records with conflict checks.
- **State** — deterministic derived `state.md`; compaction never replaces source records.
- **Events** — versioned capability/status JSON carried through ordinary messages.
- **Atomicity** — filesystem transactions, audit events and recovery markers protect concurrent work.

Agent Chat is a coordination data layer. It does not execute agents, assign models,
approve permissions, run MCP/ACP, or wake another process. No command or hook
calls an LLM, embedding/rerank provider, graph service, relay, or Cloudflare gateway.
`state`/`compact` derive summaries from local records, not model-generated text;
capability/status events describe a peer and do not invoke it.

## Two modes, two budgets

- **Live swarm** — N sessions run concurrently and use `wait` for wall-clock parallelism.
- **Async handoff / audit** — a session posts an artifact summary for the next session.

Both modes use the same file-backed protocol and remain auditable.

## Install & distribution

- **As a CLI** — `pipx install agent-chat-plugin`, then run `agent-chat <cmd>`.
  For one-off execution use `uvx --from agent-chat-plugin agent-chat <cmd>` on
  each invocation; `uvx` does not install a persistent `agent-chat` command.
- **As a standalone Skill** — copy the root `SKILL.md`, `chat.py`, and the
  entire `agent_chat/` directory together into a compatible Skills directory.
  Copying only `chat.py` breaks task, lease, path-lock, and state commands.
- **As a Claude Code plugin** — install the marketplace package from
  [claude-plugins](https://github.com/n24q02m/claude-plugins). Keep
  `.claude-plugin/`, `hooks/`, `commands/`, `skills/`, `chat.py`, and
  `agent_chat/` together; the plugin skill is `skills/agent-chat/SKILL.md`.

PyPI installs the CLI and its Python modules, not the skill, slash command, or
lifecycle hooks. Use the checkout/plugin distribution for those assets.

All participants must address the same channel root on a filesystem with the
required atomic replacement and locking semantics. Separate home/company
`~/agent-chat` directories are separate inboxes; this package does not sync
machines or install a background service. Give each participant a distinct
`AGENT_CHAT_NAME` for hooks; CLI identities are explicit `--from`/`--as` flags.
Set environment values before starting the host, not by changing its model or
MCP configuration.

### Optional inbox hooks

`hooks/hooks.json` registers three Claude Code lifecycle commands. Python hook
scripts can be invoked by absolute checkout path in another host, but that host
must explicitly support or adapt their lifecycle/output contract:

| Hook | Output when messages are unread |
|---|---|
| `SessionStart` / `hooks/session_inbox.py` | Plain-text channel/count notice; warns about unset identity when channels exist. |
| `UserPromptSubmit` / `hooks/prompt_inbox.py` | Plain-text channel/count notice; unset identity is silent. |
| `Stop` / `hooks/stop_inbox.py` | Claude-compatible JSON with `systemMessage`; unset identity is silent. |

Set `AGENT_CHAT_ROOT` and optionally comma-separated `AGENT_CHAT_CHANNELS`
to restrict checks to relevant channels (empty means all discovered channels).
Malformed channel names are skipped without suppressing other configured inboxes.
Hooks only print when unread messages are relevant to the current identity,
bound each notice to a small stdout budget, and never advance cursors, read
message bodies into notices, reply, block a turn, or wake a peer. `read` and
successful `wait` advance cursors.

The scripts prefer non-empty `CLAUDE_PLUGIN_ROOT`; otherwise they resolve
`chat.py` beside their own `hooks/` directory. An unresolved plugin root skips
with a one-line stderr diagnostic; hook failures always exit 0. Quote paths:
`python "/path/to/agent-chat-plugin/hooks/session_inbox.py"`.

A portable script is not an installed OMP/native integration. Verify each host's
explicit invocation and rendered notice; CLI installation or a successful
source check alone does not prove hooks are loaded on home or company.

See [CONTRIBUTING.md](CONTRIBUTING.md) for developer setup and runtime layout.

## Status

The reference implementation covers file-backed messages, cursors, token-free wait,
structured tasks/dependencies, leases, normalized path locks, derived state and
adapter-neutral capability/status events. MCP wrappers, ACP/wake bridges and agent
execution remain separate future designs.

## License

Apache-2.0.
