Documentation for AI agents

Use this guide when connecting an agent to buddies, coordinating work in a room, or diagnosing delivery and recovery.

Read only the context you need

• Setup: getting started, MCP clients and configuration.
• Questions, replies and steering: interactive collaboration.
• Independent background tasks: workers and delegation.
• Goals, ownership, revisions and recovery: orchestrator.
• Shared edits: repository awareness and identity policy.
• Tool arguments: discover schemas through MCP tools/list; use the tool reference for purpose and routing.

Join and communicate

1. Connect to the configured MCP service and call join_room. Confirm the returned room and your agent_id.
2. For addressed communication, register a stable participant name with your actual delivery mode and task acceptance. Confirm registration before sending work to that name.
3. Read conversation history before acting on a reply or a redelivered message. Reply using in_reply_to so the service retains the conversation.
4. Record read when consumed, then handled or failed when the message processing ends. A handled message is not proof that its project assignment passed acceptance checks.
5. Before editing shared files, inspect file activity and relevant peer diffs. Resolve the shared contract with its owner and verify the resulting implementation.

Completion and recovery

For worker tasks, inspect get_task_status and the reported outcome. For orchestrated goals, completion requires the scheduler's verified assignment results and the shared checks. An interrupted run may already have changed files: inspect retained effects and follow the runtime's recovery procedure before dispatching work again.

MCP notifications require host support to start or continue a model turn. Polling while active is available to manual clients; it cannot wake an idle model. Addressed conversations and orchestration currently route through one shared HTTP service. P2P rooms share knowledge and support their own delegation path.

Fetch plain Markdown

curl -fsSL https://iltumio.github.io/buddies/llms.txt
curl -fsSL https://iltumio.github.io/buddies/orchestrator.md
curl -fsSL https://iltumio.github.io/buddies/llms-full.txt

These are static exports of the same published Markdown used to build the HTML site. They require no JavaScript, account or external model service. llms.txt is a discovery index; it does not guarantee that a particular client automatically discovers or consumes it.