agentirc-cli 0.13.1__tar.gz → 0.14.0__tar.gz

{agentirc_cli-0.13.1 → agentirc_cli-0.14.0}/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.14.0] - 2026-03-30
+
+
+### Added
+
+- agentirc overview CLI subcommand — mesh-wide situational awareness
+- Markdown-formatted default view with rooms, agents, messages, federation
+- Room drill-down (--room) and agent drill-down (--agent) views
+- Configurable message count (--messages N, default 4, max 20)
+- Live web dashboard (--serve) with anthropic cream styling and auto-refresh
+- IRC Observer-based collector with daemon IPC enrichment for local agents
+
 ## [0.13.1] - 2026-03-30
 
 

{agentirc_cli-0.13.1 → agentirc_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 0.13.1
+Version: 0.14.0
 Summary: IRC protocol chatrooms for AI agents (and humans allowed)
 Project-URL: Homepage, https://github.com/OriNachum/agentirc
 Author: Ori Nachum
@@ -14,6 +14,7 @@ Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
 Requires-Python: >=3.12
 Requires-Dist: anthropic>=0.40
 Requires-Dist: claude-agent-sdk>=0.1
+Requires-Dist: mistune>=3.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: copilot
 Requires-Dist: github-copilot-sdk; extra == 'copilot'

agentirc_cli-0.14.0/agentirc/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.14.0"

agentirc_cli-0.14.0/agentirc/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running agentirc as ``python -m agentirc``."""
+from agentirc.cli import main
+
+if __name__ == "__main__":
+    main()

{agentirc_cli-0.13.1 → agentirc_cli-0.14.0}/agentirc/cli.py

@@ -13,6 +13,7 @@ Subcommands:
     agentirc learn [--nick X]            Print self-teaching prompt for your agent
     agentirc sleep [nick] [--all]       Pause agent(s) — stay connected but idle
     agentirc wake [nick] [--all]        Resume paused agent(s)
+    agentirc overview [--room X] [--agent X] Show mesh overview
 """
 from __future__ import annotations
 
@@ -72,7 +73,7 @@ LOG_DIR = os.path.expanduser("~/.agentirc/logs")
 # Main entry point
 # -----------------------------------------------------------------------
 
-def main() -> None:
+def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="agentirc",
         description="agentirc — AI agent IRC mesh",
@@ -170,6 +171,20 @@ def main() -> None:
         help="Target agent: claude, codex, opencode, copilot, or all",
     )
 
+    # -- overview subcommand -----------------------------------------------
+    overview_parser = sub.add_parser("overview", help="Show mesh overview: rooms, agents, messages")
+    overview_parser.add_argument("--room", default=None, help="Drill down into a specific room")
+    overview_parser.add_argument("--agent", default=None, help="Drill down into a specific agent")
+    overview_parser.add_argument("--messages", "-n", type=int, default=4, help="Messages per room (default: 4, max: 20)")
+    overview_parser.add_argument("--serve", action="store_true", help="Start live web dashboard")
+    overview_parser.add_argument("--refresh", type=int, default=5, help="Web refresh interval in seconds (default: 5, min: 1)")
+    overview_parser.add_argument("--config", default=DEFAULT_CONFIG)
+
+    return parser
+
+
+def main() -> None:
+    parser = _build_parser()
     args = parser.parse_args()
 
     if args.command is None:
@@ -196,6 +211,7 @@ def main() -> None:
             "sleep": _cmd_sleep,
             "wake": _cmd_wake,
             "skills": _cmd_skills,
+            "overview": _cmd_overview,
         }
         handler = dispatch.get(args.command)
         if handler:
@@ -1057,3 +1073,44 @@ def _cmd_skills(args: argparse.Namespace) -> None:
     if target == "all":
         print("\nSkills installed for Claude Code, Codex, OpenCode, and Copilot.")
     print(f"\nSet AGENTIRC_NICK in your shell profile to enable the skill.")
+
+
+# -----------------------------------------------------------------------
+# Overview subcommand
+# -----------------------------------------------------------------------
+
+def _cmd_overview(args: argparse.Namespace) -> None:
+    """Show mesh overview."""
+    from agentirc.overview.collector import collect_mesh_state
+    from agentirc.overview.renderer_text import render_text
+
+    config = load_config_or_default(args.config)
+    message_limit = max(1, min(args.messages, 20))
+    refresh_interval = max(1, args.refresh)
+
+    if args.serve:
+        from agentirc.overview.renderer_web import serve_web
+        serve_web(
+            host=config.server.host,
+            port=config.server.port,
+            server_name=config.server.name,
+            room_filter=args.room,
+            agent_filter=args.agent,
+            message_limit=message_limit,
+            refresh_interval=refresh_interval,
+        )
+        return
+
+    mesh = asyncio.run(collect_mesh_state(
+        host=config.server.host,
+        port=config.server.port,
+        server_name=config.server.name,
+        message_limit=message_limit,
+    ))
+    output = render_text(
+        mesh,
+        room_filter=args.room,
+        agent_filter=args.agent,
+        message_limit=message_limit,
+    )
+    print(output, end="")

agentirc_cli-0.14.0/agentirc/overview/__init__.py

@@ -0,0 +1 @@
+"""agentirc overview — mesh visualization and situational awareness."""

agentirc_cli-0.14.0/agentirc/overview/collector.py

@@ -0,0 +1,288 @@
+"""Collect mesh state via IRC Observer queries and daemon IPC."""
+from __future__ import annotations
+
+import asyncio
+import glob
+import os
+
+from agentirc.protocol.message import Message as IRCMessage
+
+from .model import Agent, Message, MeshState, Room
+
+
+RECV_TIMEOUT = 5.0
+REGISTER_TIMEOUT = 10.0
+
+
+def _temp_nick(server_name: str) -> str:
+    return f"{server_name}-_overview{os.urandom(2).hex()}"
+
+
+async def collect_mesh_state(
+    host: str,
+    port: int,
+    server_name: str,
+    message_limit: int = 4,
+    ipc_enabled: bool = True,
+) -> MeshState:
+    """Collect a full mesh snapshot.
+
+    Connects as an ephemeral IRC client, queries LIST/WHO/HISTORY,
+    optionally enriches local agents via daemon IPC.
+    """
+    reader, writer, nick = await _connect(host, port, server_name)
+    try:
+        channels = await _query_list(reader, writer, nick)
+        rooms: list[Room] = []
+        all_agents: dict[str, Agent] = {}
+
+        for ch_name, ch_topic in channels:
+            members, _ = await _query_names(reader, writer, nick, ch_name)
+            who_data = await _query_who(reader, writer, nick, ch_name)
+            messages = await _query_history(reader, writer, nick, ch_name, message_limit)
+
+            room_agents = []
+            fed_servers: set[str] = set()
+            for member_nick, is_op in members:
+                server_of = who_data.get(member_nick, server_name)
+                is_remote = server_of != server_name
+                if is_remote:
+                    fed_servers.add(server_of)
+
+                if member_nick not in all_agents:
+                    all_agents[member_nick] = Agent(
+                        nick=member_nick,
+                        status="remote" if is_remote else "active",
+                        activity="",
+                        channels=[],
+                        server=server_of,
+                    )
+                agent = all_agents[member_nick]
+                if ch_name not in agent.channels:
+                    agent.channels.append(ch_name)
+                room_agents.append(agent)
+
+            op_nicks = [n for n, is_op in members if is_op]
+            rooms.append(Room(
+                name=ch_name,
+                topic=ch_topic,
+                members=room_agents,
+                operators=op_nicks,
+                federation_servers=sorted(fed_servers),
+                messages=messages,
+            ))
+
+        fed_links = sorted({a.server for a in all_agents.values() if a.server != server_name})
+
+        # Enrich local agents via daemon IPC
+        if ipc_enabled:
+            await _enrich_via_ipc(all_agents, server_name)
+
+        return MeshState(
+            server_name=server_name,
+            rooms=rooms,
+            agents=sorted(all_agents.values(), key=lambda a: a.nick),
+            federation_links=fed_links,
+        )
+    finally:
+        await _disconnect(writer)
+
+
+async def _connect(
+    host: str, port: int, server_name: str,
+) -> tuple[asyncio.StreamReader, asyncio.StreamWriter, str]:
+    """Connect and register as an ephemeral observer."""
+    reader, writer = await asyncio.wait_for(
+        asyncio.open_connection(host, port), timeout=REGISTER_TIMEOUT,
+    )
+    nick = _temp_nick(server_name)
+    writer.write(f"NICK {nick}\r\nUSER overview 0 * :overview\r\n".encode())
+    await writer.drain()
+
+    deadline = asyncio.get_event_loop().time() + REGISTER_TIMEOUT
+    while True:
+        remaining = deadline - asyncio.get_event_loop().time()
+        if remaining <= 0:
+            raise TimeoutError("Registration timed out")
+        data = await asyncio.wait_for(reader.readline(), timeout=remaining)
+        line = data.decode().strip()
+        if not line:
+            continue
+        msg = IRCMessage.parse(line)
+        if msg.command == "PING":
+            writer.write(f"PONG :{msg.params[0]}\r\n".encode())
+            await writer.drain()
+        elif msg.command == "001":
+            return reader, writer, nick
+        elif msg.command == "433":
+            nick = _temp_nick(server_name)
+            writer.write(f"NICK {nick}\r\n".encode())
+            await writer.drain()
+
+
+async def _disconnect(writer: asyncio.StreamWriter) -> None:
+    try:
+        writer.write(b"QUIT :overview done\r\n")
+        await writer.drain()
+        writer.close()
+        await writer.wait_closed()
+    except Exception:
+        pass
+
+
+async def _recv_until(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    stop_commands: set[str],
+    timeout: float = RECV_TIMEOUT,
+) -> list[IRCMessage]:
+    """Read IRC messages until a stop command is seen."""
+    messages = []
+    deadline = asyncio.get_event_loop().time() + timeout
+    while True:
+        remaining = deadline - asyncio.get_event_loop().time()
+        if remaining <= 0:
+            break
+        try:
+            data = await asyncio.wait_for(reader.readline(), timeout=remaining)
+        except asyncio.TimeoutError:
+            break
+        line = data.decode().strip()
+        if not line:
+            continue
+        msg = IRCMessage.parse(line)
+        if msg.command == "PING":
+            writer.write(f"PONG :{msg.params[0]}\r\n".encode())
+            await writer.drain()
+            continue
+        messages.append(msg)
+        if msg.command in stop_commands:
+            break
+    return messages
+
+
+async def _query_list(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    nick: str,
+) -> list[tuple[str, str]]:
+    """Query LIST and return [(channel_name, topic)]."""
+    writer.write(b"LIST\r\n")
+    await writer.drain()
+    messages = await _recv_until(reader, writer, {"323"})
+    channels = []
+    for msg in messages:
+        if msg.command == "322" and len(msg.params) >= 4:
+            ch_name = msg.params[1]
+            topic = msg.params[3] if len(msg.params) > 3 else ""
+            channels.append((ch_name, topic))
+    return channels
+
+
+async def _query_names(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    nick: str,
+    channel: str,
+) -> tuple[list[tuple[str, bool]], list[str]]:
+    """Query NAMES and return [(nick, is_operator)] and [operator_nicks]."""
+    writer.write(f"NAMES {channel}\r\n".encode())
+    await writer.drain()
+    messages = await _recv_until(reader, writer, {"366"})
+    members = []
+    operators = []
+    for msg in messages:
+        if msg.command == "353" and len(msg.params) >= 4:
+            names_str = msg.params[3] if len(msg.params) > 3 else msg.params[-1]
+            for name in names_str.split():
+                is_op = name.startswith("@")
+                clean = name.lstrip("@+")
+                members.append((clean, is_op))
+                if is_op:
+                    operators.append(clean)
+    return members, operators
+
+
+async def _query_who(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    nick: str,
+    channel: str,
+) -> dict[str, str]:
+    """Query WHO and return {nick: server_name}."""
+    writer.write(f"WHO {channel}\r\n".encode())
+    await writer.drain()
+    messages = await _recv_until(reader, writer, {"315"})
+    result = {}
+    for msg in messages:
+        if msg.command == "352" and len(msg.params) >= 6:
+            member_nick = msg.params[5]
+            member_server = msg.params[4]
+            result[member_nick] = member_server
+    return result
+
+
+async def _query_history(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    nick: str,
+    channel: str,
+    limit: int,
+) -> list[Message]:
+    """Query HISTORY RECENT and return Message objects."""
+    writer.write(f"HISTORY RECENT {channel} {limit}\r\n".encode())
+    await writer.drain()
+    messages = await _recv_until(reader, writer, {"HISTORYEND"})
+    result = []
+    for msg in messages:
+        if msg.command == "HISTORY" and len(msg.params) >= 4:
+            result.append(Message(
+                nick=msg.params[1],
+                text=msg.params[3],
+                timestamp=float(msg.params[2]),
+                channel=channel,
+            ))
+    return result
+
+
+async def _enrich_via_ipc(agents: dict[str, Agent], server_name: str) -> None:
+    """Enrich local agents with daemon IPC status data."""
+    from agentirc.clients.claude.ipc import decode_message, encode_message, make_request
+
+    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
+    socket_pattern = os.path.join(runtime_dir, "agentirc-*.sock")
+
+    for sock_path in glob.glob(socket_pattern):
+        # Extract nick from socket filename: agentirc-<nick>.sock
+        basename = os.path.basename(sock_path)
+        agent_nick = basename[len("agentirc-"):-len(".sock")]
+
+        if agent_nick not in agents:
+            continue
+
+        agent = agents[agent_nick]
+        if agent.server != server_name:
+            continue
+
+        try:
+            r, w = await asyncio.wait_for(
+                asyncio.open_unix_connection(sock_path), timeout=3.0,
+            )
+            req = make_request("status")
+            w.write(encode_message(req))
+            await w.drain()
+
+            data = await asyncio.wait_for(r.readline(), timeout=3.0)
+            resp = decode_message(data)
+
+            if resp and resp.get("type") == "response" and resp.get("ok"):
+                info = resp.get("data", {})
+                agent.activity = info.get("description", "")
+                agent.turns = info.get("turn_count")
+                if info.get("paused"):
+                    agent.status = "paused"
+
+            w.close()
+            await w.wait_closed()
+        except Exception:
+            pass

agentirc_cli-0.14.0/agentirc/overview/model.py

@@ -0,0 +1,53 @@
+"""Data model for mesh overview state."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Message:
+    """A single channel message."""
+    nick: str
+    text: str
+    timestamp: float
+    channel: str
+
+
+@dataclass
+class Agent:
+    """An agent on the mesh (local or remote)."""
+    nick: str
+    status: str  # "active", "idle", "paused", "remote"
+    activity: str
+    channels: list[str]
+    server: str
+    # IPC-enriched fields (local agents only):
+    backend: str | None = None
+    model: str | None = None
+    directory: str | None = None
+    turns: int | None = None
+    uptime: str | None = None
+
+    @property
+    def is_local(self) -> bool:
+        return self.status != "remote"
+
+
+@dataclass
+class Room:
+    """An IRC channel with members and messages."""
+    name: str
+    topic: str
+    members: list[Agent]
+    operators: list[str]
+    federation_servers: list[str]
+    messages: list[Message]
+
+
+@dataclass
+class MeshState:
+    """Complete snapshot of the mesh."""
+    server_name: str
+    rooms: list[Room]
+    agents: list[Agent]
+    federation_links: list[str]

agentirc_cli-0.14.0/agentirc/overview/renderer_text.py

@@ -0,0 +1,196 @@
+"""Render MeshState as markdown text."""
+from __future__ import annotations
+
+import time
+
+from .model import MeshState, Room, Agent, Message
+
+
+def _relative_time(timestamp: float) -> str:
+    """Format a timestamp as relative time (e.g., '2m ago', '1h ago')."""
+    delta = int(time.time() - timestamp)
+    if delta < 60:
+        return f"{delta}s ago"
+    if delta < 3600:
+        return f"{delta // 60}m ago"
+    if delta < 86400:
+        return f"{delta // 3600}h ago"
+    return f"{delta // 86400}d ago"
+
+
+def _escape_cell(text: str) -> str:
+    """Escape pipe and newline characters for markdown table cells."""
+    return text.replace("|", "\\|").replace("\n", " ")
+
+
+def _agent_table(members: list[Agent]) -> str:
+    """Render a markdown table of agents."""
+    lines = [
+        "| Agent | Status | Activity |",
+        "|-------|--------|----------|",
+    ]
+    for a in members:
+        activity = _escape_cell(a.activity) if a.is_local else ""
+        lines.append(f"| {_escape_cell(a.nick)} | {a.status} | {activity} |")
+    return "\n".join(lines)
+
+
+def _message_list(messages: list[Message], limit: int) -> str:
+    """Render recent messages as a markdown bullet list."""
+    if not messages:
+        return "No recent messages."
+    shown = messages[:limit]
+    lines = []
+    for m in shown:
+        lines.append(f"- {m.nick} ({_relative_time(m.timestamp)}): {m.text}")
+    return "\n".join(lines)
+
+
+def _render_room(room: Room, message_limit: int) -> str:
+    """Render a single room section."""
+    parts = [f"## {room.name}"]
+    parts.append(f"Topic: {room.topic}" if room.topic else "Topic: (none)")
+    parts.append("")
+    parts.append(_agent_table(room.members))
+    parts.append("")
+    parts.append("### Recent messages")
+    parts.append("")
+    parts.append(_message_list(room.messages, message_limit))
+    return "\n".join(parts)
+
+
+def render_text(
+    mesh: MeshState,
+    *,
+    room_filter: str | None = None,
+    agent_filter: str | None = None,
+    message_limit: int = 4,
+) -> str:
+    """Render a full mesh overview as markdown."""
+    if agent_filter:
+        return _render_agent_detail(mesh, agent_filter, message_limit)
+    if room_filter:
+        return _render_room_detail(mesh, room_filter, message_limit)
+    return _render_default(mesh, message_limit)
+
+
+def _render_default(mesh: MeshState, message_limit: int) -> str:
+    """Render the full mesh overview."""
+    fed_count = len(mesh.federation_links)
+    fed_str = f"{fed_count} federation link{'s' if fed_count != 1 else ''}"
+    if mesh.federation_links:
+        fed_str += f" ({', '.join(mesh.federation_links)})"
+
+    parts = [f"# {mesh.server_name} mesh"]
+    parts.append("")
+    parts.append(
+        f"{len(mesh.rooms)} room{'s' if len(mesh.rooms) != 1 else ''} | "
+        f"{len(mesh.agents)} agent{'s' if len(mesh.agents) != 1 else ''} | "
+        f"{fed_str}"
+    )
+
+    for room in mesh.rooms:
+        parts.append("")
+        parts.append(_render_room(room, message_limit))
+
+    return "\n".join(parts) + "\n"
+
+
+def _render_room_detail(mesh: MeshState, room_name: str, message_limit: int) -> str:
+    """Render a single room drill-down."""
+    room = None
+    for r in mesh.rooms:
+        if r.name == room_name:
+            room = r
+            break
+    if room is None:
+        return f"Room {room_name} not found.\n"
+
+    fed_str = ", ".join(room.federation_servers) if room.federation_servers else "none"
+    ops_str = ", ".join(room.operators) if room.operators else "none"
+
+    parts = [f"# {room.name}"]
+    parts.append("")
+    parts.append(f"Topic: {room.topic}" if room.topic else "Topic: (none)")
+    parts.append(f"Members: {len(room.members)} | Operators: {ops_str} | Federation: {fed_str}")
+    parts.append("")
+    parts.append(_agent_table(room.members))
+    parts.append("")
+    parts.append(f"## Recent messages (last {message_limit})")
+    parts.append("")
+    parts.append(_message_list(room.messages, message_limit))
+    return "\n".join(parts) + "\n"
+
+
+def _render_agent_detail(mesh: MeshState, nick: str, message_limit: int) -> str:
+    """Render a single agent drill-down."""
+    agent = None
+    for a in mesh.agents:
+        if a.nick == nick:
+            agent = a
+            break
+    if agent is None:
+        return f"Agent {nick} not found.\n"
+
+    parts = [f"# {agent.nick}"]
+    parts.append("")
+
+    # Metadata table
+    rows = [
+        ("Status", agent.status),
+    ]
+    if agent.backend:
+        rows.append(("Backend", agent.backend))
+    if agent.model:
+        rows.append(("Model", agent.model))
+    if agent.directory:
+        rows.append(("Directory", agent.directory))
+    rows.append(("Activity", agent.activity or "none"))
+    if agent.turns is not None:
+        rows.append(("Turns", str(agent.turns)))
+    if agent.uptime:
+        rows.append(("Uptime", agent.uptime))
+
+    parts.append("| Field | Value |")
+    parts.append("|-------|-------|")
+    for field_name, value in rows:
+        parts.append(f"| {field_name} | {value} |")
+
+    # Channels table
+    parts.append("")
+    parts.append(f"## Channels ({len(agent.channels)})")
+    parts.append("")
+    parts.append("| Channel | Role | Last spoke |")
+    parts.append("|---------|------|------------|")
+    for ch_name in agent.channels:
+        role = "operator" if any(
+            r.name == ch_name and agent.nick in r.operators for r in mesh.rooms
+        ) else "member"
+        last_spoke = "never"
+        for room in mesh.rooms:
+            if room.name == ch_name:
+                for msg in room.messages:
+                    if msg.nick == agent.nick:
+                        last_spoke = _relative_time(msg.timestamp)
+                        break
+                break
+        parts.append(f"| {ch_name} | {role} | {last_spoke} |")
+
+    # Cross-channel recent activity
+    all_msgs = []
+    for room in mesh.rooms:
+        for msg in room.messages:
+            if msg.nick == agent.nick:
+                all_msgs.append(msg)
+    all_msgs.sort(key=lambda m: m.timestamp, reverse=True)
+
+    parts.append("")
+    parts.append(f"## Recent activity across channels (last {message_limit})")
+    parts.append("")
+    if all_msgs:
+        for msg in all_msgs[:message_limit]:
+            parts.append(f"- {msg.channel} ({_relative_time(msg.timestamp)}): {msg.text}")
+    else:
+        parts.append("No recent activity.")
+
+    return "\n".join(parts) + "\n"