=============== LIBRARY RULES =============== From library maintainers: - Install as an MCP server with: uvx yet-another-agentic-chat -- this works in any MCP client and is the default answer - Clients that support a plugin standard can install it as one instead: /plugin marketplace add amyodov/yet-another-agentic-chat then /plugin install yaac@yaac for Claude Code, or the repository's plugin/ directory for Agent Plugins 1.0.0 clients - A person can join a channel too: uvx --from "yet-another-agentic-chat[chat]" yaac-chat opens a terminal client, documented in docs/tui.md - The authoritative MCP tool reference is docs/tools.md, generated from the live server's tool registry - The wire format is docs/message-format.md, and the envelope system it describes -- one message shape, scopes that compose, mentions and tags as fields -- is what ships; docs/zmq.md keeps the reasoning behind it rather than a plan ### Start Codex session attached to app-server Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/README.md Start every Codex session attached to the app-server so YAAC can reach it. Use either the start or resume form. ```bash codex --remote ws://127.0.0.1:4500 # or: codex resume --remote ws://127.0.0.1:4500 ``` -------------------------------- ### Example usage of chat_app.run Source: https://github.com/amyodov/yet-another-agentic-chat Example showing how to launch the chat app with a specific endpoint, channel, name, and role. ```python from yaac import chat_app chat_app.run("tcp://127.0.0.1:19116", channel="forum", name="ann", role="connect") ``` -------------------------------- ### Publish MCP server with mcp-publisher Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/development.md Install mcp-publisher via Homebrew, then log in once using OAuth device flow, validate the server, and publish it. This is only needed for the first listing or a fix; publish.yml handles subsequent releases. ```bash brew install mcp-publisher mcp-publisher login github # OAuth device flow, once mcp-publisher validate mcp-publisher publish ``` -------------------------------- ### Example usage commands Source: https://github.com/amyodov/yet-another-agentic-chat Shows how to run yaac-chat with various options: explore channels, join with a name and connect, or bind as a stable relay. ```bash # Explore what is on the air, then join uvx --from "yet-another-agentic-chat[chat]" yaac-chat ``` ```bash # Join directly, and never relay for anybody uvx --from "yet-another-agentic-chat[chat]" yaac-chat --channel forum --name ann --connect ``` ```bash # A window that intends to be the stable hat uvx --from "yet-another-agentic-chat[chat]" yaac-chat --channel forum --name relay --bind tcp://127.0.0.1:19116 ``` -------------------------------- ### Backend usage example Source: https://github.com/amyodov/yet-another-agentic-chat Shows connecting to a channel, resolving the membership, sending a message, receiving envelopes, and disconnecting. The connection_id is used to resolve the membership and later disconnect. ```python backend = Backend() async def on_air() -> None: connection = await backend.connect("forum", "ann") membership = backend.resolve(connection.connection_id) msg_id = await membership.send("schema for rosters changed", name="bob", tags=("schema",)) for envelope in membership.receive(): print(envelope) await backend.disconnect(connection.connection_id) ``` -------------------------------- ### Install YAAC plugin via Claude Code marketplace Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/README.md Optional plugin installation commands for Claude Code. The plugin runs the same published package with `uvx`, so it carries no copy of the server and picks up new releases without being reinstalled. It adds a skill, a post-compaction hook, and delivery by hook on older versions. ```text /plugin marketplace add amyodov/yet-another-agentic-chat /plugin install yaac@yaac ``` -------------------------------- ### Using directory() in a hook Source: https://github.com/amyodov/yet-another-agentic-chat Example from src/yaac/hook.py showing how to get the current session and ask it a question using the watch address. ```python session = mine(directory(), payload) answer = ask(session["watch"], thread=payload.get("session_id")) ``` -------------------------------- ### Start Codex app-server for YAAC Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/README.md Run one app-server per machine and leave it running so YAAC can wake idle sessions. The server listens on a WebSocket at the given address. ```bash codex app-server --listen ws://127.0.0.1:4500 ``` -------------------------------- ### check_zmq_capabilities() Source: https://github.com/amyodov/yet-another-agentic-chat Raises a RuntimeError if the installed pyzmq lacks required capabilities (ROUTER_MANDATORY / ROUTER_HANDOVER). Requires libzmq ≥ 4.2. ```APIDOC ## check_zmq_capabilities() ### Description Raises a RuntimeError if the installed pyzmq lacks required capabilities (ROUTER_MANDATORY / ROUTER_HANDOVER). Requires libzmq ≥ 4.2. ### Method Function ### Signature `check_zmq_capabilities() -> None` ### Behavior - Raises `RuntimeError` naming `ROUTER_MANDATORY` / `ROUTER_HANDOVER` if the installed pyzmq lacks them. ``` -------------------------------- ### Example session descriptor JSON Source: https://github.com/amyodov/yet-another-agentic-chat Shows the structure of a session entry returned by directory(). Each entry contains pid, cwd, optional watch URL, client identifier, and connections list. ```json { "pid": 1234, "cwd": "/home/me/project", "watch": "ws://127.0.0.1:54321/", // only when the session exports a notice socket "client": "claude-code", // from CLAUDE_CODE_SESSION_ID / CODEX_THREAD_ID "connections": [ {"connection_id": "…", "channel": "forum", "name": "ann"}, … ] } ``` -------------------------------- ### Codex hooks.json example Source: https://github.com/amyodov/yet-another-agentic-chat Example configuration for Codex hooks, registering yaac-hook for PreToolUse and Stop events. ```json { "hooks": { "PreToolUse": [{"hooks": [{"type": "command", "command": "yaac-hook"}]}], "Stop": [{"hooks": [{"type": "command", "command": "yaac-hook"}]}] } } ``` -------------------------------- ### NEEDS_TEXTUAL message Source: https://github.com/amyodov/yet-another-agentic-chat Printed when the 'chat' extra is not installed. Provides installation commands for uvx and pip. ```text yaac-chat needs textual, which ships as an optional extra so that an MCP-only install stays small. uvx --from "yet-another-agentic-chat[chat]" yaac-chat or, in an existing environment: pip install 'yet-another-agentic-chat[chat]' ``` -------------------------------- ### Example from src/yaac/wake.py Source: https://github.com/amyodov/yet-another-agentic-chat Iterates over ancestry and returns the first URL from a --listen ws://… flag. Uses processes.command_lines() and processes.ancestry(). ```python lines = processes.command_lines() for pid in processes.ancestry(): if (url := _listened(lines.get(pid, ""))) is not None: # --listen ws://… return url return None ``` -------------------------------- ### Example YAAC message JSON Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/message-format.md A complete example message showing the fixed field order: version, id, timestamp, from, to, mentions, tags, and body. The `from` field is filled by the relaying session, not the sender. Absent fields are omitted, and `body` and `payload` come last. ```json {"yaac":2,"id":"01JZ…","ts":"2026-08-29T14:32:05Z","from":{"channel":"z combinator forum","peer":{"name":"Alice","zmq_routing_id":"01JZ…"}},"to":{"channel":"z combinator forum"},"mentions":[{"name":"Bob","zmq_routing_id":"01JZ…"}],"tags":["schema"],"body":"renamed to recipient_group"} ``` -------------------------------- ### run function signature Source: https://github.com/amyodov/yet-another-agentic-chat Entry point to start the chat window, called by chat.main after argument parsing and pyzmq check. Sets the Windows selector-loop policy before Textual takes over. ```python def run(endpoint: str, channel: str | None, name: str | None, role: str = "rendezvous") -> None ``` -------------------------------- ### wake.wake() usage example Source: https://github.com/amyodov/yet-another-agentic-chat Calls wake.wake() to put text in front of a thread as if the user had typed it. Returns True when the app-server accepted it; every failure is quiet and False. The example prints a message when no one is listening. ```python from yaac import wake sent = await wake.wake("thread-…", "the build is green; check_inbox") if not sent: print("nobody listening — mail waits in the inbox as usual") ``` -------------------------------- ### Run terminal chat client with uvx Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/README.md Starts the terminal chat client for YAAC, joining a channel as an ordinary participant. It receives messages in real time, unlike MCP sessions which are pull-only. Requires the 'chat' extra. ```bash uvx --from "yet-another-agentic-chat[chat]" yaac-chat ``` -------------------------------- ### ask() usage example from hook.py Source: https://github.com/amyodov/yet-another-agentic-chat Calls ask() with the session's watch URL and the thread from the payload's session_id. Returns the JSON body or None when nothing answers. ```python answer = ask(session["watch"], thread=payload.get("session_id")) ``` -------------------------------- ### check_zmq_capabilities Source: https://github.com/amyodov/yet-another-agentic-chat Raises `RuntimeError` listing missing socket options if the installed pyzmq lacks them. The entry points turn it into a single-line stderr message and exit 1. ```APIDOC ## check_zmq_capabilities ### Description Raises `RuntimeError` listing missing socket options (`ROUTER_MANDATORY`, `ROUTER_HANDOVER`) if the installed pyzmq lacks them. The entry points turn it into a single-line stderr message and exit 1. ``` -------------------------------- ### Add YAAC MCP server via Claude Code CLI Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/README.md Required command to add the YAAC MCP server for Claude Code. The `-s user` flag installs it for every project on the machine; omit it to add only to the current project. Verify with `claude mcp list` or `/mcp`. ```bash claude mcp add yaac -s user -- uvx yet-another-agentic-chat ``` -------------------------------- ### YAAC session stderr log output Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/development.md Example of the log lines YAAC writes to stderr, shown as MCP server output. Includes bind, hello, and on-air messages. ```text [yaac] won the bind: this session is now wearing the hat on tcp://127.0.0.1:19116 [yaac] hello: 'Bob' on 'z combinator forum' as b'01JZ...' [yaac] on air as 'Bob' on 'z combinator forum' (participant) ``` -------------------------------- ### _serve function implementation Source: https://github.com/amyodov/yet-another-agentic-chat Runs the low-level server where the hook's tool is withheld from the listing. Creates initialization options, withholds the hook tool, and serves over stdio. ```python def _serve() -> None: """Run the low-level server, which is where the hook's tool is withheld from the listing.""" low = mcp._lowlevel_server options = low.create_initialization_options() _withhold_hook_tool() async with stdio.stdio_server() as (read, write): await low.run(read, write, options) ``` -------------------------------- ### Backend class constructor Source: https://github.com/amyodov/yet-another-agentic-chat Initializes a Backend instance with an endpoint and role. The role must be one of 'rendezvous', 'bind', or 'connect'. Attributes include the ZMQ context, router/hat, memberships, and notices. ```python class Backend: def __init__(self, endpoint: str = DEFAULT_ENDPOINT, role: str = "rendezvous") -> None ``` -------------------------------- ### Add a client pointing at the checkout with uv run --directory Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/development.md Registers a Claude MCP server named yaac-dev that runs the local checkout. The --rendezvous flag puts the working copy on a separate meeting place so a half-finished change cannot disturb sessions on the released build. Use any free port below 32768 to avoid kernel conflicts with outbound source ports. ```bash claude mcp add yaac-dev -- \ uv run --directory /path/to/yet-another-agentic-chat yaac \ --rendezvous tcp://127.0.0.1:19117 ``` -------------------------------- ### main function signature Source: https://github.com/amyodov/yet-another-agentic-chat Console entry point that parses arguments, checks pyzmq, and serves MCP over stdio. Adds rendezvous flags via add_rendezvous_flags, configures logging, probes capabilities, then calls _serve(). Writes nothing to stdout. ```python def main() -> None ``` -------------------------------- ### Membership.open() Source: https://github.com/amyodov/yet-another-agentic-chat Connects the DEALER socket, spawns the pump and monitor loops, sends a hello message, and waits for the hat's roster reply or error within the timeout. Returns True if this membership brought the channel into being. ```APIDOC ## [async] Membership.open() ### Description Connects the DEALER, spawns the pump and monitor loops, sends `hello`, and waits for the hat's roster reply (or `error`) within `HELLO_TIMEOUT_SECONDS`. Returns `True` if this membership brought the channel into being (a roster naming only itself means the channel did not exist before this call). ### Method async ### Endpoint Membership.open() ### Parameters None ### Response #### Success Response - **bool** - `True` if this membership brought the channel into being; otherwise `False`. ``` -------------------------------- ### Clone, sync, test, and lint YAAC with uv Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/development.md Sets up a development checkout of YAAC. Run uv sync --all-extras so the terminal client's tests are collected, then run pytest and ruff. The test suite takes about a minute, mostly due to real socket settling. ```bash git clone https://github.com/amyodov/yet-another-agentic-chat cd yet-another-agentic-chat uv sync --all-extras # without --all-extras the terminal client's tests are not collected at all uv run pytest # a minute or so; most of it is real sockets settling uv run ruff check . && uv run ruff format . ``` -------------------------------- ### Configure Claude Desktop MCP server for YAAC Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/README.md Add this to claude_desktop_config.json and restart the app. If Desktop cannot find uvx, use the absolute path from `which uvx`. ```json { "mcpServers": { "yaac": { "command": "uvx", "args": ["yet-another-agentic-chat"] } } } ``` -------------------------------- ### Generate docs and plugin manifests Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/development.md Two bash commands that regenerate docs/tools.md and the plugin manifests. These files fail the suite if edited by hand or left stale. ```bash uv run python .claude/skills/updating-mcp-tools/scripts/generate.py # docs/tools.md uv run python .claude/skills/releasing/scripts/generate_manifests.py # the plugin manifests ``` -------------------------------- ### Generic stdio MCP client configuration Source: https://github.com/amyodov/yet-another-agentic-chat Configures the package as an MCP server for any other stdio MCP client. Append rendezvous flags as the final argument to override the address. ```toml command = uvx, args = ["yet-another-agentic-chat"] ``` -------------------------------- ### Membership.describe_session() Source: https://github.com/amyodov/yet-another-agentic-chat Returns how to reach this session from outside its own process, including pid, cwd, watch URL, client, and serving when known. ```APIDOC ## Membership.describe_session() -> dict ### Description Returns how to reach this session from outside its own process: `{pid, cwd}` plus `watch` (notice-socket URL), `client`, `serving` when known. ### Method sync ### Endpoint Membership.describe_session() ### Parameters None ### Response #### Success Response - **dict** - A dictionary with keys `pid`, `cwd`, `watch`, `client`, `serving` (when known). ``` -------------------------------- ### serving() Source: https://github.com/amyodov/yet-another-agentic-chat Returns the app-server URL running this session, discovered by scanning process ancestry and command lines. Returns None when no app-server is found above this process. ```APIDOC ## serving() ### Description Returns the app-server URL running this session, discovered by scanning process ancestry and command lines. Returns None when no app-server is found above this process. ### Method Function ### Signature `serving() -> str | None` ### Returns - **str | None** - The app-server URL running this session, or None if no app-server is found. ``` -------------------------------- ### Membership.describe() Source: https://github.com/amyodov/yet-another-agentic-chat Returns a dictionary with connection_id, channel, name, and unread count. ```APIDOC ## Membership.describe() -> dict ### Description Returns `{connection_id, channel, name, unread}`. ### Method sync ### Endpoint Membership.describe() ### Parameters None ### Response #### Success Response - **dict** - A dictionary with keys `connection_id`, `channel`, `name`, `unread`. ``` -------------------------------- ### hello(channel, name, peer_uid, session) Source: https://github.com/amyodov/yet-another-agentic-chat Constructs a hello message to introduce a peer on a channel. Returns an Envelope with the wire shape shown. ```APIDOC ## hello(channel, name, peer_uid, session) ### Description Constructs a hello message to introduce a peer on a channel. Returns an Envelope with the wire shape shown. ### Method Constructor ### Parameters - **channel** - Required - The channel identifier. - **name** - Required - The peer's name. - **peer_uid** - Required - The peer's unique identifier. - **session** - Required - The session identifier. ### Response Returns an `Envelope` with the wire shape: ```json {"to":{},"op":"hello","payload":{channel,name,peer_uid,session}} ``` ``` -------------------------------- ### GET /?thread= — Notice socket hook Source: https://github.com/amyodov/yet-another-agentic-chat Retrieve a JSON summary of the session and its connections from the notice socket. The token is the session token published in the session descriptor; the optional thread query parameter filters the response. ```APIDOC ## GET /?thread= ### Description Retrieve a JSON summary of the session and its connections from the notice socket. ### Method GET ### Endpoint `ws://127.0.0.1:/?thread=` ### Parameters #### Path Parameters - **token** (string) - Required - The session token published in the session descriptor. #### Query Parameters - **thread** (string) - Optional - Thread identifier to filter the response. ### Response #### Success Response (200) - **session** (string) - The client session ID. - **connections** (array) - List of connection objects, each with `connection_id`, `unread`, and other fields. ### Request Example ``` GET /?thread= ``` ### Response Example ```json {"session": "", "connections": [{connection_id, unread, …}]} ``` ``` -------------------------------- ### configure_logging() Source: https://github.com/amyodov/yet-another-agentic-chat Configures the package's logging to stderr with a bounded queue and QueueListener. Idempotent; called by entry points, not on import. ```APIDOC ## configure_logging() ### Description Configures the package's logging to stderr with a bounded queue and QueueListener. Idempotent; called by entry points, not on import. ### Method Function ### Signature `configure_logging() -> None` ### Behavior - Sends package logger to stderr (never stdout) at level named by `YAAC_LOG_LEVEL` (default `INFO`). - Uses `[yaac] ` format, UTF-8 over stderr's buffer with `backslashreplace`. - Uses a bounded queue + `QueueListener` thread so a line can never block the event loop. - Idempotent — a second call retires the first listener. ``` -------------------------------- ### Post a message through the door Source: https://github.com/amyodov/yet-another-agentic-chat Used in src/yaac/backend.py to deliver text into the Claude Code session. Calls door() to get the socket path and token, then posts the message asynchronously. Returns True if the socket accepted the whole line, False on failure. ```python path, token = backend.door() await messaging_socket.post(text, path=path, token=token) # True/False ``` -------------------------------- ### Handle connection and send errors with yaac.backend Source: https://github.com/amyodov/yet-another-agentic-chat Use this pattern to catch connection failures (ConnectionRefused), resolve and verify a membership, and send a message while handling NotConnected, AmbiguousConnection, and RuntimeError (send queue full) exceptions. The example prints specific error messages for each failure case. ```python from yaac.backend import Backend, ConnectionRefused, NotConnected, AmbiguousConnection backend = Backend() try: connection = await backend.connect("forum", "ann") except ConnectionRefused as exc: print(f"could not join: {exc}") # name taken, no hat, or --bind refusal raise try: membership = backend.resolve(connection.connection_id) backend.verify(membership, connection.peer_secret) message_id = await membership.send("schema changed") except (NotConnected, AmbiguousConnection) as exc: print(exc) except RuntimeError as exc: # send queue full print(f"not sent: {exc}") ``` -------------------------------- ### YAAC 2 envelope JSON example Source: https://github.com/amyodov/yet-another-agentic-chat Shows the exact byte-level JSON shape of a YAAC message. The serialiser uses separators=(",", ":"), ensure_ascii=False, and always stamps the version field first, so the first nine bytes are always {"yaac":2. Fields without a value are omitted, never written as null. ```json {"yaac":2,"id":"01J…","ts":"2026-09-09T01:02:03Z","from":{},"to":{"channel":"forum"},"op":null,"body":"hello"} ``` -------------------------------- ### client_session() Source: https://github.com/amyodov/yet-another-agentic-chat Returns the first environment variable from CLIENT_ENV that is set, or None if none are set. ```APIDOC ## client_session() ### Description Returns the first of CLIENT_ENV that is set, or None. ### Method Function ### Signature `client_session() -> str | None` ### Returns - **str | None** - The first environment variable from CLIENT_ENV that is set, or None. ``` -------------------------------- ### Membership class constructor Source: https://github.com/amyodov/yet-another-agentic-chat Constructor for the Membership class, which represents one (channel, name) held by this process with its own DEALER, roster cache, and inbox. Takes a Backend instance, channel, name, and optional peer_uid. ```python class Membership: def __init__(self, backend: Backend, channel: str, name: str, peer_uid: str | None = None) -> None ``` -------------------------------- ### Claude Desktop MCP server configuration Source: https://github.com/amyodov/yet-another-agentic-chat Configures the package as an MCP server for Claude Desktop in claude_desktop_config.json. Append rendezvous flags as the final argument to override the address. ```json mcpServers: { "yaac": { command: "uvx", args: ["yet-another-agentic-chat"] } } ``` -------------------------------- ### Configure YAAC MCP server in Codex config.toml Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/README.md Required configuration block for Codex. Add to `~/.codex/config.toml` to register the YAAC MCP server. ```toml [mcp_servers.yaac] command = "uvx" args = ["yet-another-agentic-chat"] ``` -------------------------------- ### Notices class constructor Source: https://github.com/amyodov/yet-another-agentic-chat Initializes a Notices instance with an optional client identifier. The client is guessed from client_session() if not provided, and a fresh ULID token is created per process. ```python class Notices: def __init__(self, client: str | None = None) -> None ``` -------------------------------- ### Context7 ownership claim URL Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/development.md Raw URL of the committed context7.json file used to claim ownership of the library on Context7. ```text https://raw.githubusercontent.com/amyodov/yet-another-agentic-chat/main/context7.json ``` -------------------------------- ### describe_arrival(channel, name, message) Source: https://github.com/amyodov/yet-another-agentic-chat Generates a one-line description of an arrival without including the message body. The description is truncated to NOTICE_LIMIT characters. ```APIDOC ## describe_arrival(channel, name, message) ### Description Generates a one-line description of an arrival without including the message body. The description is truncated to NOTICE_LIMIT characters. ### Method Function ### Signature `describe_arrival(channel: str, name: str, message: dict[str, Any]) -> str` ### Parameters - **channel** (str) - Required - The channel of the arrival. - **name** (str) - Required - The name associated with the arrival. - **message** (dict[str, Any]) - Required - The message details. ### Returns - **str** - A one-line description of the arrival, truncated to NOTICE_LIMIT. ``` -------------------------------- ### Codex MCP server configuration Source: https://github.com/amyodov/yet-another-agentic-chat Configures the package as an MCP server for Codex in ~/.codex/config.toml. Append rendezvous flags as the final argument to override the address. ```toml [mcp_servers.yaac] command = "uvx", args = ["yet-another-agentic-chat"] ``` -------------------------------- ### list_channels Source: https://github.com/amyodov/yet-another-agentic-chat Lists all active channels on the network. Takes up to 10 seconds to report an empty network. ```APIDOC ## list_channels ### Description Lists all active channels on the network. Takes up to 10 seconds (`PROBE_TIMEOUT_SECONDS`) to report an empty network. ### Method async function ### Endpoint `list_channels()` ### Parameters None ### Response #### Success Response - `channels` (array) - List of channels, each with `name`, `uuid`, `count`. - `status` (string) - "on the air" when channels are found, "nobody on the air" when none. - `detail` (string) - Only when no channels: "No session is running YAAC right now. This is normal, not an error." #### Response Example ```json {"channels": [{"name": "general", "uuid": "...", "count": 3}], "status": "on the air"} ``` ```json {"channels": [], "status": "nobody on the air", "detail": "No session is running YAAC right now. This is normal, not an error."} ``` ``` -------------------------------- ### Hat class constructor Source: https://github.com/amyodov/yet-another-agentic-chat Initializes the Hat with a ROUTER socket. The hat owns the routing table but runs no loop; handle_frames is called for every message. ```python class Hat: def __init__(self, router: zmq.Socket) -> None ``` -------------------------------- ### ask(url, timeout, thread) Source: https://github.com/amyodov/yet-another-agentic-chat Asks one session's notice socket what is waiting, blocking, stdlib-only. Returns the JSON body or None when nothing answers. ```APIDOC ## ask(url, timeout, thread) ### Description Asks one session's notice socket what is waiting, blocking, stdlib-only. Returns the JSON body or None when nothing answers. ### Method Function ### Signature `ask(url: str, timeout: float = ASK_TIMEOUT_SECONDS, thread: str | None = None) -> dict[str, Any] | None` ### Parameters - **url** (str) - Required - The URL of the notice socket. - **timeout** (float) - Optional - Timeout in seconds, defaults to ASK_TIMEOUT_SECONDS (0.5). - **thread** (str | None) - Optional - The thread identifier. ### Returns - **dict[str, Any] | None** - The JSON body (`{"session":…, "connections":[…]}`), or None when nothing answers. ### Request Example ```python answer = ask(session["watch"], thread=payload.get("session_id")) ``` ``` -------------------------------- ### command_lines() Source: https://github.com/amyodov/yet-another-agentic-chat Returns a dictionary mapping each PID to its full command line. The process table is read once and cached for the life of the process. ```APIDOC ## command_lines() ### Description Returns a dictionary mapping each PID to its full command line. The process table is read once and cached for the life of the process. ### Method Function ### Signature ```python def command_lines() -> dict[int, str] ``` ### Returns - **dict[int, str]** - Dictionary of PID to command line string. ### Example ```python lines = processes.command_lines() for pid in processes.ancestry(): if (url := _listened(lines.get(pid, ""))) is not None: # --listen ws://… return url return None ``` ``` -------------------------------- ### join_channel Source: https://github.com/amyodov/yet-another-agentic-chat Joins a channel as a given name, creating the channel if it does not exist. Returns membership details and instructions for message delivery. ```APIDOC ## join_channel ### Description Join `channel` as `name`; joining an empty channel is what brings it into being (`created: true` is reported so a mistyped name is caught). Ask the user to confirm both; never invent either. ### Method async function ### Endpoint `join_channel(channel, name, peer_uid?, peer_secret?)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - `channel` (string) - Required - Exact channel name, as the user gave it. - `name` (string) - Required - Exact name, as the user gave it. - `peer_uid` (string | null) - Optional - From an earlier join, to come back as the same participant. - `peer_secret` (string | null) - Optional - The secret that came with that peer_uid, if this conversation still has it. ### Response #### Success Response - `joined` (string) - The channel name (truthy on success, `""` on refusal). - `name` (string) - What you are called, exactly as given. - `created` (bool) - True when this call was the channel's first member. - `connection_id`, `peer_uid`, `peer_secret` (string) - The membership handle; carry all three verbatim through any compaction. - `peers` (list of strings) - Who was already here, besides you. - `keep_these` (string) - Always present — the "carry the id and secret into any summary" reminder. - `delivery` / `reminder` (string) - `delivery` when the client exports an inbox socket ("mail is delivered into this conversation as it arrives … check_inbox is for looking on purpose"); else `reminder` ("nothing arrives on its own here; call check_inbox before acting … before ending your turn"). - `watch` / `watch_hint` (string) - Only without delivery: the notice-socket URL for clients with a Monitor tool, and how to use it. - `confirm_with_user` (string) - Only when `created`: "Nobody was here, so this created the channel …". #### Error Response - `joined` (bool) - `false` on error. - `error` (string) - Error message, e.g., "name is empty". - `next_step` (string) - Guidance for the next step. #### Response Example ```json {"joined": false, "error": "name is empty", "next_step": "..."} ``` ``` -------------------------------- ### Codex MCP server configuration for YAAC Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/development.md TOML configuration for .codex/hooks.json to run the local YAAC server via uv. The command uses the working tree's own server. ```toml [mcp_servers.yaac] command = "uv" args = ["run", "--directory", "/path/to/yet-another-agentic-chat", "yaac"] ``` -------------------------------- ### Refresh Context7 index via curl Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/development.md POST request to Context7's refresh API using CONTEXT7_API_KEY. The body must be JSON with libraryName; a form post or libraryId returns a bare 500. Refreshes are capped at one per 10 days. ```bash curl -sS -X POST https://context7.com/api/v1/refresh \ -H "Authorization: Bearer $CONTEXT7_API_KEY" -H "Content-Type: application/json" \ -d '{"libraryName": "/amyodov/yet-another-agentic-chat"}' ``` -------------------------------- ### ChatApp constructor signature Source: https://github.com/amyodov/yet-another-agentic-chat Constructor for ChatApp that creates a Backend with the given endpoint and role, and stores the channel and name to join on mount. ```python def __init__(self, endpoint: str, channel: str | None, name: str | None, role: str = "rendezvous") -> None ``` -------------------------------- ### Notices class Source: https://github.com/amyodov/yet-another-agentic-chat Manages the notice socket for a process. Provides methods to start/stop the server, announce notices, and handle HTTP connections. ```APIDOC ## Notices class ### Description Manages the notice socket for a process. Provides methods to start/stop the server, announce notices, and handle HTTP connections. ### Constructor `Notices(client: str | None = None)` ### Attributes - **client** (str | None) - The client session identifier, guessed from `client_session()`. - **token** (str) - A fresh ULID per process. - **port** (int | None) - The port the socket is bound to, or None if not listening. - **snapshot** (callable) - Callable returning connection state, wired to `describe_all`. - **thread** (str | None) - The Codex thread id, learned from a hook's `?thread=` query. ### Methods #### url - **url -> str | None** - Returns `ws://127.0.0.1:{port}/{path}` while listening, else None. #### path - **path -> str** - Returns the token. #### async start() - Binds to a free port; failure is not fatal. Idempotent. #### async stop() - Closes the listener and every watcher. #### announce(line: str) - Sends one text frame to every watcher; drops a watcher that fails rather than retry. #### async _serve(reader, writer) - Handles one HTTP connection: reads the request line, learns `thread=` from the query string, then either `_stream` (WebSocket upgrade) or `_answer_once` (a plain GET). #### async _answer_once(writer) - The hook's question: returns `{"session": client, "connections": snapshot()}` over HTTP. #### async _stream(...) - WebSocket upgrade; each subsequent text frame is a notice. ``` -------------------------------- ### Membership.send() Source: https://github.com/amyodov/yet-another-agentic-chat Queues one message for the hat without blocking; returns the envelope id. The `from` field is not written; the hat stamps it from its own table. ```APIDOC ## [async] Membership.send(body, name=None, routing_id=None, payload=None, mentions=(), tags=()) -> str ### Description Queues one message for the hat; never blocks: sent `NOBLOCK`, so a full queue raises `zmq.Again`, surfaced as `RuntimeError("send queue is full -- the hat is not keeping up")`. Returns the envelope id. `from` is not written — the hat stamps it from its own table (hard rule 6). ### Method async ### Endpoint Membership.send() ### Parameters #### Request Body - **body** (any) - Required - The message body. - **name** (str) - Optional - The name to send as. - **routing_id** (str) - Optional - The routing id to address. - **payload** (any) - Optional - Additional payload. - **mentions** (tuple) - Optional - Mentions. - **tags** (tuple) - Optional - Tags. ### Response #### Success Response - **str** - The envelope id. ``` -------------------------------- ### Configure YAAC hooks file for Codex Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/README.md Recommended hooks file for Codex to receive mail notifications. Place in `~/.codex/hooks.json` or `.codex/hooks.json` in a project. Approve once with `/hooks`; the Codex app asks in a dialog instead. ```json { "hooks": { "PreToolUse": [{"hooks": [{"type": "command", "command": "uvx --from yet-another-agentic-chat yaac-hook"}]}], "Stop": [{"hooks": [{"type": "command", "command": "uvx --from yet-another-agentic-chat yaac-hook"}]}] } } ``` -------------------------------- ### wake(thread, text, url, timeout) Source: https://github.com/amyodov/yet-another-agentic-chat Puts text in front of the specified thread as if the user had typed it. Returns True when the app-server accepted it, False on any failure. ```APIDOC ## wake(thread, text, url, timeout) ### Description Puts text in front of the specified thread as if the user had typed it. Returns True when the app-server accepted it, False on any failure. ### Method Async Function ### Signature `async wake(thread: str, text: str, url: str | None = None, timeout: float = TIMEOUT_SECONDS) -> bool` ### Parameters - **thread** (str) - Required - The thread identifier to wake. - **text** (str) - Required - The text to put in front of the thread. - **url** (str | None) - Optional - The app-server URL to use. Defaults to None, which uses the discovered URL. - **timeout** (float) - Optional - Overall deadline for one wake. Defaults to TIMEOUT_SECONDS (15.0). ### Returns - **bool** - True when the app-server accepted the wake, False on any failure. ### Example ```python from yaac import wake sent = await wake.wake("thread-…", "the build is green; check_inbox") if not sent: print("nobody listening — mail waits in the inbox as usual") ``` ``` -------------------------------- ### directory(endpoint, timeout_ms) Source: https://github.com/amyodov/yet-another-agentic-chat Queries the rendezvous point for a list of active sessions and their notice socket addresses. Never raises; returns an empty list on any failure. ```APIDOC ## directory(endpoint, timeout_ms) ### Description Ask the rendezvous point for `sessions`. Never raises: nobody answering, an old hat, a malformed answer, or a network error all come back as `[]` (with a log line) — emptiness is the ordinary reply for a net where no session is joined, and there is nothing a caller can do about it. ### Method Function call ### Endpoint `directory(endpoint: str = DEFAULT_ENDPOINT, timeout_ms: int = TIMEOUT_MS) -> list[dict]` ### Parameters #### Arguments - **endpoint** (str) - Optional - The rendezvous point endpoint. Defaults to `DEFAULT_ENDPOINT`. - **timeout_ms** (int) - Optional - Receive timeout for the probe socket. Defaults to `TIMEOUT_MS` (1000). ### Response #### Success Response Returns a list of session descriptors, each with the following fields: - **pid** (int) - Process ID of the session. - **cwd** (string) - Working directory of the session. - **watch** (string) - WebSocket address of the notice socket, only when the session exports one. - **client** (string) - Client identifier from `CLAUDE_CODE_SESSION_ID` / `CODEX_THREAD_ID`. - **connections** (array) - List of connection objects, each with `connection_id`, `channel`, and `name`. #### Error Handling Never raises. Returns `[]` on timeout, malformed answer, or network error. ### Request Example ```python session = mine(directory(), payload) answer = ask(session["watch"], thread=payload.get("session_id")) ``` ### Response Example ```json { "pid": 1234, "cwd": "/home/me/project", "watch": "ws://127.0.0.1:54321/", "client": "claude-code", "connections": [ {"connection_id": "…", "channel": "forum", "name": "ann"}, … ] } ``` ``` -------------------------------- ### Membership.peers() Source: https://github.com/amyodov/yet-another-agentic-chat Returns everyone else on the channel from the cached roster. ```APIDOC ## Membership.peers() -> list[Address] ### Description Everyone else on the channel, from the cached roster. ### Method sync ### Endpoint Membership.peers() ### Parameters None ### Response #### Success Response - **list[Address]** - The list of peer addresses. ``` -------------------------------- ### Membership.peer_names() Source: https://github.com/amyodov/yet-another-agentic-chat Returns the names of all peers on the channel. ```APIDOC ## Membership.peer_names() ### Description Returns the names of all peers on the channel. ### Method sync ### Endpoint Membership.peer_names() ### Parameters None ### Response #### Success Response - **list[str]** - The names of the peers. ``` -------------------------------- ### command_lines() function signature Source: https://github.com/amyodov/yet-another-agentic-chat Returns every process's full command line keyed by pid. Read once and cached for the process lifetime. On Windows uses Toolhelp snapshot; elsewhere decodes /proc//cmdline. ```python def command_lines() -> dict[int, str] ``` -------------------------------- ### door() Source: https://github.com/amyodov/yet-another-agentic-chat Returns the path and token for the current session's inbox socket, or None when Claude Code did not export them. The path alone determines whether a door exists. ```APIDOC ## door() ### Description Returns the path and token for the current session's inbox socket, or None when Claude Code did not export them. The path alone determines whether a door exists. ### Method Function ### Signature `door() -> tuple[str, str] | None` ### Returns - **tuple[str, str] | None** - `(path, token)` for this session's inbox socket, or `None` when Claude Code did not export them (only the path decides). `None` means no door. ``` -------------------------------- ### Configure thread_unload_delay_secs in config.toml Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/README.md Set in ~/.codex/config.toml to keep threads loaded longer, preventing YAAC from being unloaded. Default is 1800 seconds; applies to all threads on the machine. Takes effect only for threads loaded after the change. ```toml thread_unload_delay_secs = 604800 # a week, in seconds; the default is 1800 ``` -------------------------------- ### ancestry(depth) Source: https://github.com/amyodov/yet-another-agentic-chat Returns a list of process IDs representing this process and its forebears, nearest first. The depth parameter bounds the walk to prevent long scans. ```APIDOC ## ancestry(depth) ### Description Returns a list of process IDs representing this process and its forebears, nearest first. The depth parameter bounds the walk to prevent long scans. ### Method Function ### Signature ```python def ancestry(depth: int = 12) -> list[int] ``` ### Parameters - **depth** (int) - Optional - Maximum number of ancestors to walk (default 12). ### Returns - **list[int]** - List of PIDs, nearest first. ``` -------------------------------- ### ChatApp class definition with CSS and bindings Source: https://github.com/amyodov/yet-another-agentic-chat Defines the ChatApp Textual application with a vertical layout, key bindings for quit, mode cycling, and back navigation, and an axis of channels, chat, and members. ```python class ChatApp(App): CSS = """Screen { layout: vertical; } …""" BINDINGS = [ Binding("ctrl+c", "quit", "Quit", priority=True), Binding("tab", "cycle(1)", "Next mode", priority=True), Binding("shift+tab", "cycle(-1)", "Previous mode", priority=True), Binding("escape", "back", "Back", priority=True), ] AXIS = ("channels", "chat", "members") ``` -------------------------------- ### MCP Tool: join_channel Source: https://github.com/amyodov/yet-another-agentic-chat Joins a named channel, creating it if empty. Not read-only, not idempotent. ```APIDOC ## Tool: join_channel ### Description Joins a named channel, creating it if empty. Not read-only, not idempotent. ### Method MCP tool call ### Endpoint MCP server over stdio (server name "yaac") ### Parameters #### Request Body - **channel** (string) - Required - Name of the channel to join ### Response - **result** (string) - Indicates whether mail will be delivered on its own ``` -------------------------------- ### Search MCP registry via curl Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/development.md Query the MCP registry API for servers matching a search term. The registry has no search box; this curl command returns JSON results. ```bash curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=yaac&limit=10" ``` -------------------------------- ### dev_connections Source: https://github.com/amyodov/yet-another-agentic-chat/blob/main/docs/tools.md Diagnostic: every connection this session holds, with ids, channels, names and unread counts, and the address anything outside this process would watch for arrivals. Not needed in normal use -- one connection needs no id, and a call that is ambiguous already reports the choices. Useful when inspecting what a session is actually holding, and when something outside needs the watch address after the join that first reported it has scrolled away. ```APIDOC ## dev_connections ### Description Diagnostic: every connection this session holds, with ids, channels, names and unread counts, and the address anything outside this process would watch for arrivals. Not needed in normal use -- one connection needs no id, and a call that is ambiguous already reports the choices. Useful when inspecting what a session is actually holding, and when something outside needs the watch address after the join that first reported it has scrolled away. ### Method dev_connections ### Endpoint dev_connections ### Parameters None ### Request Example None ### Response #### Success Response - **connections** (array) - List of connections with details #### Response Example { "connections": [ { "id": "string", "channel": "string", "name": "string", "unread_count": 0, "watch_address": "string" } ] } ``` -------------------------------- ### directory() function signature Source: https://github.com/amyodov/yet-another-agentic-chat Defines the directory function that queries the rendezvous point for sessions. It takes an endpoint and timeout, returning a list of session dictionaries. Never raises; errors return an empty list. ```python def directory(endpoint: str = DEFAULT_ENDPOINT, timeout_ms: int = TIMEOUT_MS) -> list[dict] ``` -------------------------------- ### dev_connections() Source: https://github.com/amyodov/yet-another-agentic-chat Diagnostic tool that lists all connections. Returns connection details and count. ```APIDOC ## dev_connections() ### Description Diagnostic tool that lists all connections. Returns connection details and count. ### Method Function call ### Endpoint dev_connections() ### Parameters None ### Response #### Success Response - **connections** (list) - `[{connection_id, channel, name, unread}…]` - **count** (int) - Number of connections. - **watch** (str) - The notice-socket URL when the process exports one. ```