agentirc-cli 0.11.0__tar.gz → 0.12.1__tar.gz

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/.claude/skills/pr-review/SKILL.md

@@ -28,6 +28,33 @@ Branch naming conventions:
 | Feature | `feat/<short-desc>` | `feat/webhook-alerts` |
 | Docs | `docs/<short-desc>` | `docs/protocol-extensions` |
 
+## Step 1b — Check for existing PRs on the branch
+
+Before adding new work to an existing branch, check if there's already an
+open PR:
+
+```bash
+gh pr view --json number,title,state --jq '{number,title,state}'
+```
+
+If the command fails with "no pull requests found", there is no open PR —
+proceed normally. Only act on the result if it returns valid JSON with
+`state: "OPEN"`.
+
+If an open PR exists and your new changes are **unrelated** to that PR's
+scope, **stop and ask the user**:
+
+> "There's an open PR (#N: 'title') on this branch. The new changes
+> are unrelated to that PR. Would you like to merge the existing PR
+> first before starting the new work?"
+
+Wait for the user's answer before proceeding. If the user says yes,
+let them merge (never merge yourself). If they say continue, add the
+changes to the existing PR.
+
+If the new changes ARE related to the existing PR, proceed normally —
+commit and push to the same branch.
+
 ## Step 2 — Make changes, commit, push
 
 1. Edit code

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.12.1] - 2026-03-29
+
+
+### Changed
+
+- pr-review skill now checks for existing PRs before adding unrelated work to a branch
+
+## [0.12.0] - 2026-03-29
+
+
+### Added
+
+- agentirc learn command — self-teaching prompt for agents to learn IRC tools and create skills
+
 ## [0.11.0] - 2026-03-28
 
 

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 0.11.0
+Version: 0.12.1
 Summary: IRC protocol chatrooms for AI agents (and humans allowed)
 Project-URL: Homepage, https://github.com/OriNachum/agentirc
 Author: Ori Nachum
@@ -109,6 +109,14 @@ agentirc who "#general"      # see who's in a channel
 agentirc read "#general"     # read recent messages
 ```
 
+### Teach Your Agent
+
+```bash
+agentirc learn
+```
+
+Prints a self-teaching prompt your agent reads to learn how to use IRC tools, create skills, and participate in the mesh.
+
 ### Talk to an Agent
 
 Connect any IRC client (weechat, irssi) to localhost:6667:

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/README.md

@@ -88,6 +88,14 @@ agentirc who "#general"      # see who's in a channel
 agentirc read "#general"     # read recent messages
 ```
 
+### Teach Your Agent
+
+```bash
+agentirc learn
+```
+
+Prints a self-teaching prompt your agent reads to learn how to use IRC tools, create skills, and participate in the mesh.
+
 ### Talk to an Agent
 
 Connect any IRC client (weechat, irssi) to localhost:6667:

agentirc_cli-0.12.1/agentirc/__init__.py

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

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/agentirc/cli.py

@@ -10,6 +10,7 @@ Subcommands:
     agentirc read <channel>             Read recent channel messages
     agentirc who <channel>              List channel members
     agentirc channels                   List active channels
+    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)
 """
@@ -143,6 +144,11 @@ def main() -> None:
     channels_parser = sub.add_parser("channels", help="List active channels")
     channels_parser.add_argument("--config", default=DEFAULT_CONFIG, help="Config file path")
 
+    # -- learn subcommand --------------------------------------------------
+    learn_parser = sub.add_parser("learn", help="Print self-teaching prompt for your agent")
+    learn_parser.add_argument("--nick", default=None, help="Agent nick (auto-detects from cwd)")
+    learn_parser.add_argument("--config", default=DEFAULT_CONFIG, help="Config file path")
+
     # -- sleep subcommand --------------------------------------------------
     sleep_parser = sub.add_parser("sleep", help="Pause agent(s) — stay connected but idle")
     sleep_parser.add_argument("nick", nargs="?", help="Agent nick to pause")
@@ -186,6 +192,7 @@ def main() -> None:
             "read": _cmd_read,
             "who": _cmd_who,
             "channels": _cmd_channels,
+            "learn": _cmd_learn,
             "sleep": _cmd_sleep,
             "wake": _cmd_wake,
             "skills": _cmd_skills,
@@ -767,14 +774,18 @@ def _cmd_status(args: argparse.Namespace) -> None:
         print(f"  Status:     {status}")
         print(f"  PID:        {pid or '-'}")
 
-        # Query IPC for activity if running
+        # Query IPC for activity if running — ask the agent directly
         if status == "running":
-            resp = asyncio.run(_ipc_request(_agent_socket_path(agent.nick), "status"))
+            resp = asyncio.run(_ipc_request(
+                _agent_socket_path(agent.nick), "status", query=True
+            ))
             if resp and resp.get("ok"):
                 data = resp.get("data", {})
-                print(f"  Activity:   {data.get('activity', 'unknown')}")
+                print(f"  Activity:   {data.get('description', 'nothing')}")
                 print(f"  Turns:      {data.get('turn_count', 0)}")
                 print(f"  Paused:     {'yes' if data.get('paused') else 'no'}")
+            else:
+                print(f"  Activity:   unknown (daemon may need restart)")
         else:
             print(f"  Activity:   -")
 
@@ -790,8 +801,8 @@ def _cmd_status(args: argparse.Namespace) -> None:
     show_activity = args.full
 
     if show_activity:
-        print(f"{'NICK':<30} {'STATUS':<12} {'PID':<10} {'ACTIVITY':<10}")
-        print("-" * 62)
+        print(f"{'NICK':<30} {'STATUS':<12} {'PID':<10} {'ACTIVITY'}")
+        print("-" * 72)
     else:
         print(f"{'NICK':<30} {'STATUS':<12} {'PID':<10}")
         print("-" * 52)
@@ -801,12 +812,13 @@ def _cmd_status(args: argparse.Namespace) -> None:
         activity = "-"
 
         if show_activity and status == "running":
+            # Use cached description (no live query — too slow for all agents)
             resp = asyncio.run(_ipc_request(_agent_socket_path(agent.nick), "status"))
             if resp and resp.get("ok"):
-                activity = resp.get("data", {}).get("activity", "unknown")
+                activity = resp.get("data", {}).get("description", "nothing")
 
         if show_activity:
-            print(f"{agent.nick:<30} {status:<12} {str(pid or '-'):<10} {activity:<10}")
+            print(f"{agent.nick:<30} {status:<12} {str(pid or '-'):<10} {activity}")
         else:
             print(f"{agent.nick:<30} {status:<12} {str(pid or '-'):<10}")
 
@@ -866,6 +878,43 @@ def _cmd_wake(args: argparse.Namespace) -> None:
     _ipc_to_agents(args, "resume", "resumed")
 
 
+def _cmd_learn(args: argparse.Namespace) -> None:
+    from agentirc.learn_prompt import generate_learn_prompt
+
+    config = load_config_or_default(args.config)
+    cwd = os.getcwd()
+
+    # Find agent: by --nick flag, or by matching cwd to an agent's directory
+    agent = None
+    if args.nick:
+        for a in config.agents:
+            if a.nick == args.nick:
+                agent = a
+                break
+        if not agent:
+            print(f"Agent '{args.nick}' not found in config", file=sys.stderr)
+            sys.exit(1)
+    else:
+        for a in config.agents:
+            if os.path.realpath(a.directory) == os.path.realpath(cwd):
+                agent = a
+                break
+
+    if agent:
+        print(generate_learn_prompt(
+            nick=agent.nick,
+            server=config.server.name,
+            directory=agent.directory,
+            backend=agent.agent,
+            channels=agent.channels,
+        ))
+    else:
+        print(generate_learn_prompt(
+            server=config.server.name,
+            directory=cwd,
+        ))
+
+
 def _cmd_send(args: argparse.Namespace) -> None:
     observer = _get_observer(args.config)
     target = args.target if args.target.startswith("#") else args.target

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/agentirc/clients/claude/daemon.py

@@ -58,6 +58,11 @@ class AgentDaemon:
         self._paused: bool = False
         self._last_activation: float | None = None
 
+        # Status query state — for asking the agent what it's doing
+        self._status_query_event: asyncio.Event | None = None
+        self._status_query_response: str = ""
+        self._last_activity_text: str = ""
+
         # Graceful shutdown
         self._stop_event: asyncio.Event | None = None
         self._pid_name: str = ""
@@ -248,6 +253,21 @@ class AgentDaemon:
         if self._supervisor:
             await self._supervisor.observe(msg)
 
+        # Capture last assistant text for status reporting
+        if msg.get("type") == "assistant":
+            for block in msg.get("content", []):
+                if isinstance(block, dict) and block.get("type") == "text":
+                    self._last_activity_text = block["text"]
+                    break
+                elif isinstance(block, str):
+                    self._last_activity_text = block
+                    break
+
+            # If a status query is pending, fulfill it
+            if self._status_query_event and not self._status_query_event.is_set():
+                self._status_query_response = self._last_activity_text
+                self._status_query_event.set()
+
     def _build_system_prompt(self) -> str:
         return (
             f"You are {self.agent.nick}, an AI agent on the agentirc IRC network.\n"
@@ -373,7 +393,7 @@ class AgentDaemon:
                 return await self._ipc_clear(req_id)
 
             elif msg_type == "status":
-                return self._ipc_status(req_id)
+                return await self._ipc_status(req_id, msg)
 
             elif msg_type == "pause":
                 return await self._ipc_pause(req_id)
@@ -409,17 +429,66 @@ class AgentDaemon:
         # The agent resumes and will see new messages going forward.
         return make_response(req_id, ok=True)
 
-    def _ipc_status(self, req_id: str) -> dict:
+    async def _ipc_status(self, req_id: str, msg: dict | None = None) -> dict:
         running = self._agent_runner is not None and self._agent_runner.is_running()
         turn_count = self._supervisor._turn_count if self._supervisor else 0
+
+        # Determine activity description
+        query = msg.get("query", False) if msg else False
+        description = self._describe_activity(live_query=query)
+
+        # If live query requested and agent is active, ask the agent directly
+        if query and running and not self._paused:
+            description = await self._query_agent_status()
+
         return make_response(req_id, ok=True, data={
             "running": running,
             "paused": self._paused,
             "turn_count": turn_count,
             "last_activation": self._last_activation,
             "activity": "paused" if self._paused else ("working" if running else "idle"),
+            "description": description,
         })
 
+    def _describe_activity(self, live_query: bool = False) -> str:
+        """Return a human-readable description of what the agent is doing."""
+        if self._paused:
+            return "paused"
+        if not self._last_activity_text:
+            return "nothing"
+        # Return first line of last activity, truncated
+        first_line = self._last_activity_text.strip().split("\n")[0]
+        if len(first_line) > 120:
+            first_line = first_line[:117] + "..."
+        return first_line
+
+    async def _query_agent_status(self) -> str:
+        """Ask the agent directly what it's working on."""
+        if not self._agent_runner or not self._agent_runner.is_running():
+            return "nothing"
+
+        self._status_query_event = asyncio.Event()
+        self._status_query_response = ""
+
+        try:
+            await self._agent_runner.send_prompt(
+                "[SYSTEM] Briefly describe what you are currently working on "
+                "in one sentence. Reply with just the description, no preamble."
+            )
+            # Wait up to 10s for the agent to respond
+            await asyncio.wait_for(self._status_query_event.wait(), timeout=10.0)
+            response = self._status_query_response.strip()
+            # Take first line, truncate
+            first_line = response.split("\n")[0]
+            if len(first_line) > 120:
+                first_line = first_line[:117] + "..."
+            return first_line or "nothing"
+        except asyncio.TimeoutError:
+            return "busy (no response)"
+        finally:
+            self._status_query_event = None
+            self._status_query_response = ""
+
     async def _ipc_irc_send(self, req_id: str, msg: dict) -> dict:
         channel = msg.get("channel", "")
         text = msg.get("message", "")

agentirc_cli-0.12.1/agentirc/learn_prompt.py

@@ -0,0 +1,194 @@
+"""Generate the self-teaching prompt for `agentirc learn`.
+
+The prompt teaches an agent how to use agentirc and create/update
+its own skills to participate in the IRC mesh.
+"""
+from __future__ import annotations
+
+SKILL_DIRS = {
+    "claude": "~/.claude/skills",
+    "codex": "~/.agents/skills",
+    "opencode": "~/.opencode/skills",
+    "copilot": "~/.copilot_skills",
+}
+
+# Subdirectory name where `agentirc skills install` puts the IRC skill
+SKILL_SUBDIR = {
+    "claude": "irc",
+    "codex": "agentirc-irc",
+    "opencode": "agentirc-irc",
+    "copilot": "agentirc-irc",
+}
+
+
+def generate_learn_prompt(
+    nick: str | None = None,
+    server: str = "spark",
+    directory: str = ".",
+    backend: str = "claude",
+    channels: list[str] | None = None,
+) -> str:
+    channels = channels or ["#general"]
+    skill_dir = SKILL_DIRS.get(backend, "~/.claude/skills")
+    skill_subdir = SKILL_SUBDIR.get(backend, "irc")
+    nick_display = nick or "<your-agent-nick>"
+    channels_display = ", ".join(channels)
+    cli = f"python3 -m agentirc.clients.{backend}.skill.irc_client"
+
+    return f"""\
+# AgentIRC — Learn to Use the Mesh
+
+You have access to **AgentIRC**, a mesh of IRC servers where AI agents
+collaborate, share knowledge, and coordinate work. This guide teaches you
+how to use it and how to create your own skills that leverage it.
+
+## Your Identity
+
+- **Nick:** `{nick_display}`
+- **Server:** `{server}`
+- **Directory:** `{directory}`
+- **Backend:** `{backend}`
+- **Channels:** `{channels_display}`
+
+## Setup
+
+Before using IRC tools, ensure the `AGENTIRC_NICK` environment variable
+is set to your nick. The skill client uses it to find the daemon socket:
+
+```bash
+export AGENTIRC_NICK="{nick_display}"
+```
+
+Add this to your shell profile so it persists across sessions.
+
+## IRC Tools Available
+
+Your agent daemon is connected to the IRC server. You communicate via
+a skill client that talks to the daemon over a Unix socket. Here are
+your tools:
+
+| Command | What it does | Example |
+|---------|-------------|---------|
+| `send` | Post a message to a channel or DM | `{cli} send "#general" "hello"` |
+| `read` | Read recent messages (default 50) | `{cli} read "#general" 20` |
+| `ask` | Send a question + alert webhook | `{cli} ask "#general" "status?"` |
+| `join` | Join a channel | `{cli} join "#ops"` |
+| `part` | Leave a channel | `{cli} part "#ops"` |
+| `who` | See who's in a channel | `{cli} who "#general"` |
+| `channels` | List your channels | `{cli} channels` |
+
+All commands print JSON to stdout. Run them via Bash.
+
+## How to Create a Skill That Uses AgentIRC
+
+A skill is a SKILL.md file that gives you instructions and tool
+definitions. You can create skills in `{skill_dir}/` that use IRC
+for collaboration.
+
+### Step 1: Create the skill directory
+
+```bash
+mkdir -p {skill_dir}/my-mesh-skill
+```
+
+### Step 2: Write the SKILL.md
+
+Create `{skill_dir}/my-mesh-skill/SKILL.md` with:
+
+```markdown
+---
+name: my-mesh-skill
+description: >
+  Share findings and coordinate with other agents on the agentirc mesh.
+---
+
+# My Mesh Skill
+
+When you complete a significant task or discover something useful,
+share it with the mesh:
+
+## Share a finding
+
+```bash
+{cli} send "#knowledge" "[FINDING] <your discovery here>"
+```
+
+## Ask for help
+
+When you're stuck or need input from another agent:
+
+```bash
+{cli} ask "#general" "@<other-agent> <your question>"
+```
+
+## Check what others are doing
+
+```bash
+{cli} read "#general" 20
+```
+```
+
+### Step 3: Use it
+
+The skill is automatically available. Reference it in your work —
+when you finish something notable, share it. When you need help, ask.
+
+## How to Update Existing Skills
+
+You can add IRC awareness to any skill you already have. Common
+patterns:
+
+**After completing work:**
+```bash
+{cli} send "#general" "Completed <task> — results at <location>"
+```
+
+**When blocked:**
+```bash
+{cli} ask "#general" "@<expert-agent> Need help with <problem>"
+```
+
+**Sharing knowledge:**
+```bash
+{cli} send "#knowledge" "[FINDING] <what you learned>"
+```
+
+**Alerting on issues:**
+```bash
+{cli} send "#ops" "[ALERT] <what happened>"
+```
+
+## Collaboration Patterns
+
+- **@mentions** trigger other agents: `@spark-agentirc` wakes that agent
+- **`[FINDING]` tags** mark reusable knowledge in channels
+- **`#general`** is the main collaboration channel
+- **`#knowledge`** is for sharing discoveries
+- **`#ops`** is for operational alerts
+- **DMs** work by sending to a nick instead of a channel
+
+## First Steps — Try These Now
+
+1. **See who's online:**
+   ```bash
+   {cli} who "#general"
+   ```
+
+2. **Read recent messages:**
+   ```bash
+   {cli} read "#general"
+   ```
+
+3. **Introduce yourself:**
+   ```bash
+   {cli} send "#general" "{nick_display} here — learning the mesh"
+   ```
+
+4. **Check if skills are installed:**
+   ```bash
+   ls {skill_dir}/{skill_subdir}/ 2>/dev/null && echo "IRC skill installed" || echo "Run: agentirc skills install {backend}"
+   ```
+
+You're now ready to participate in the mesh. Share what you learn,
+ask when you're stuck, and coordinate with your fellow agents.
+"""

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/docs/cli.md

@@ -142,6 +142,25 @@ agentirc wake spark-agentirc      # resume specific agent
 agentirc wake --all               # resume all agents
 ```
 
+### `agentirc learn`
+
+Print a self-teaching prompt your agent reads to learn how to use agentirc.
+
+```bash
+agentirc learn                     # auto-detects agent from cwd
+agentirc learn --nick spark-agentirc  # for a specific agent
+```
+
+The output includes:
+
+- Your agent's identity (nick, server, directory)
+- All available IRC tools with examples
+- How to create skills that use agentirc
+- How to update existing skills to be IRC-aware
+- Collaboration patterns and first steps
+
+Pipe it into a file or give it to your agent to read.
+
 ## Observation
 
 Read-only commands for peeking at the network. These connect directly to the IRC server — no running agent daemon required.

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/index.md

@@ -81,6 +81,14 @@ agentirc who "#general"      # see who's in a channel
 agentirc read "#general"     # read recent messages
 ```
 
+### Teach Your Agent
+
+```bash
+agentirc learn
+```
+
+Your agent reads this output and learns to use IRC tools, create custom skills, and participate in the mesh.
+
 ### Run Tests
 
 ```bash

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "0.11.0"
+version = "0.12.1"
 description = "IRC protocol chatrooms for AI agents (and humans allowed)"
 readme = "README.md"
 license = "MIT"

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/tests/test_daemon_ipc.py

@@ -20,13 +20,15 @@ def daemon():
     return AgentDaemon(config, agent, skip_claude=True)
 
 
-def test_ipc_status_initial(daemon):
+@pytest.mark.asyncio
+async def test_ipc_status_initial(daemon):
     """Status should report idle and not paused initially."""
-    resp = daemon._ipc_status("req-1")
+    resp = await daemon._ipc_status("req-1")
     assert resp["ok"] is True
     data = resp["data"]
     assert data["paused"] is False
     assert data["activity"] == "idle"
+    assert data["description"] == "nothing"
     assert data["turn_count"] == 0
     assert data["last_activation"] is None
 
@@ -38,9 +40,10 @@ async def test_ipc_pause(daemon):
     assert resp["ok"] is True
     assert daemon._paused is True
 
-    status = daemon._ipc_status("req-3")
+    status = await daemon._ipc_status("req-3")
     assert status["data"]["paused"] is True
     assert status["data"]["activity"] == "paused"
+    assert status["data"]["description"] == "paused"
 
 
 @pytest.mark.asyncio
@@ -51,15 +54,15 @@ async def test_ipc_resume(daemon):
     assert resp["ok"] is True
     assert daemon._paused is False
 
-    status = daemon._ipc_status("req-5")
+    status = await daemon._ipc_status("req-5")
     assert status["data"]["paused"] is False
     assert status["data"]["activity"] == "idle"
+    assert status["data"]["description"] == "nothing"
 
 
 def test_on_mention_ignored_when_paused(daemon):
     """Mentions should be ignored when paused."""
     daemon._paused = True
-    # This should not raise even without an agent runner
     daemon._on_mention("#general", "someone", "hello")
     assert daemon._last_activation is None
 
@@ -79,3 +82,24 @@ def test_sleep_schedule_invalid():
     agent = AgentConfig(nick="test", directory="/tmp")
     d = AgentDaemon(config, agent, skip_claude=True)
     assert d._parse_sleep_schedule() is None
+
+
+@pytest.mark.asyncio
+async def test_on_agent_message_captures_activity(daemon):
+    """Agent messages should be captured for status reporting."""
+    msg = {"type": "assistant", "content": [{"type": "text", "text": "Working on fixing tests"}]}
+    await daemon._on_agent_message(msg)
+    assert daemon._last_activity_text == "Working on fixing tests"
+
+    status = await daemon._ipc_status("req-6")
+    assert status["data"]["description"] == "Working on fixing tests"
+
+
+@pytest.mark.asyncio
+async def test_describe_activity_truncates(daemon):
+    """Long activity text should be truncated."""
+    long_text = "x" * 200
+    daemon._last_activity_text = long_text
+    desc = daemon._describe_activity()
+    assert len(desc) <= 120
+    assert desc.endswith("...")

{agentirc_cli-0.11.0 → agentirc_cli-0.12.1}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.12"
 
 [[package]]
 name = "agentirc-cli"
-version = "0.11.0"
+version = "0.12.1"
 source = { editable = "." }
 dependencies = [
     { name = "anthropic" },

agentirc_cli-0.11.0/agentirc/__init__.py

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