agent-coexist

Help agents find each other, catch up, and work together.

agent-coexist is a small command-line tool for projects that more than one AI agent works on. It keeps their threads, directory claims, reading lists, and profiles as plain Markdown files in the project, where any agent with file access can find them.

Why

Agents on the same project usually cannot see each other’s context. Most harnesses do not talk to one another, main sessions rarely see each other, subagents rarely see their siblings, and a session that resumes or moves to another harness often has no record of what came before.

agent-coexist does not monitor harness chat transcripts, sync across networks, or automatically capture session histories. Instead, agents explicitly write messages, directory claims, and reading routes to Markdown files (*.agent-coexist.md) in the workspace. Any agent with file access can inspect them with standard file tools or the CLI.

Install

Cargo (Recommended)

Requires Rust 1.89 or newer:

cargo install agent-coexist --locked

If you use cargo-binstall, you can install precompiled binaries directly:

cargo binstall agent-coexist

Prebuilt Binaries

Precompiled standalone binaries for Linux (static musl), macOS, and Windows are available on the latest release page. Download the archive for your platform, extract agent-coexist (Windows: agent-coexist.exe), and place it on your PATH.

Every release includes SHA-256 checksums in SHA256SUMS and cryptographic build provenance attestations verifiable via gh attestation verify -R RatmmmhSquishyRat/agent-coexist.

Build from Source

git clone https://github.com/RatmmmhSquishyRat/agent-coexist.git
cd agent-coexist
cargo install --path . --locked

Check the installation with agent-coexist --version. Run agent-coexist guide for the built-in tutorial written for agents.

Getting started

Run agent-coexist guide for the complete onboarding tutorial, or inspect existing records in your project:

# Check for existing records
agent-coexist list .

# Post a message or review request
agent-coexist post parser-review --as alice -m 'Error mapping updated. Please review.'

For the complete walkthrough covering multiple agents, mentions, replies, and notifications, see the built-in guide.

Use it with your agents

To run commands, an agent needs agent-coexist on PATH (or its full path).

To teach agents when and how to look for project records, copy the bundled skill in .agents/skills/agent-coexist/ into your project’s .agents/skills/ (or .claude/skills/ for Claude Code). It instructs an agent to check for existing records upon arrival and run agent-coexist guide. Reading records or editing them by hand needs only standard file tools; the CLI keeps writes consistent and checks records across a directory tree.

What gets recorded

Each record type serves a specific coordination need:

Every record is stored as a Markdown file ending in .agent-coexist.md. Commands accept paths with or without that suffix. See the file format reference for disk layout.

Operating boundaries

• Explicit workspace files, not chat logs: agent-coexist does not hook into agent conversations, sync across a network, or maintain an automatic activity feed. Agents explicitly write to .agent-coexist.md files; other agents see them when they inspect the directory: read a post for its discussion, use read-notification to find relevant updates in a chosen time window, or run a wait command to watch for changes.
• Coordination and locking: --as is a self-declared identifier, not an authenticated login. A locked directory declaration asks other agents to avoid editing that area. The CLI enforces this by blocking profile and brief writes in that directory unless --as names the lock holder; it does not block post, subscribe, state, or ordinary file tools. See docs/usage.md and SECURITY.md.
• Shared filesystem: Agents must share access to the same workspace directory. File locking on network filesystems is not guaranteed.
• warn exits 0, like ok: Scripts should inspect the output status lines, not just the process exit code. See docs/usage.md#exit-codes.

Documentation

• Built-in guide: agent-coexist guide, with topics start, read, write, and wait. The same pages are in src/guide/.
• Command reference: complete reference for commands, flags, exit codes, and output formats.
• Output summary: representative catalog of actual commands and captured outputs, including the full stdout of the five built-in guide pages.
• File format reference: disk structure for each record type.
• Project skill: bundled agent skill instructions.
• Contributing · Security policy · Changelog · CI workflow

License

The project’s own code and documentation are licensed under the MIT License. The vendored copy of ignore in src/vendor_ignore/ keeps its upstream notices and license (Unlicense OR MIT). The cover artwork under docs/assets/ is not part of the MIT grant and remains with its creator.