nbclaw 0.1.0__tar.gz

nbclaw-0.1.0/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"1e776140-e63d-4779-bc4e-98c7f710c1ff","pid":77930,"procStart":"Thu Jun 25 23:11:53 2026","acquiredAt":1782429113867}

nbclaw-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.swival
+tmp
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.venv
+*~

nbclaw-0.1.0/LOG.md

@@ -0,0 +1,17 @@
+# Log
+
+## Switch swival to the PyPI release
+
+The user asked to depend on the published swival release rather than the relative
+local path. Removed the `[tool.uv.sources]` override in `pyproject.toml` that pointed
+swival at `../swival` as an editable install, then re-ran `uv lock` so the lockfile
+resolves swival 1.0.33 from PyPI. Confirmed with `uv sync` that the editable install
+was replaced by the registry wheel and that `import swival` still works.
+
+## Add a Makefile
+
+The user asked for a convenient Makefile modeled on the one in `~/src/swival`. Adapted
+that file to nbclaw: kept the `install`, `test`, `lint`, `format`, `check`, `clean`, and
+`dist` targets but pointed them at the `nbclaw/` package, and dropped swival's `website`
+and Homebrew-formula steps since this project has no `build.py` or `scripts/`. Verified
+`make check` and `make test` both pass.

nbclaw-0.1.0/Makefile

@@ -0,0 +1,25 @@
+.PHONY: all install test lint format check clean dist
+
+all: check
+
+install:
+	uv sync
+
+test:
+	uv run python -m pytest tests/ -v --durations=25
+
+lint:
+	uv run ruff check nbclaw/ tests/
+
+format:
+	uv run ruff format nbclaw/ tests/
+
+check: lint
+	uv run ruff format --check nbclaw/ tests/
+
+clean:
+	rm -rf dist/ build/ __pycache__ nbclaw/__pycache__ tests/__pycache__ .pytest_cache .ruff_cache
+	find . -name '*.pyc' -delete
+
+dist: clean
+	uv build

nbclaw-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: nbclaw
+Version: 0.1.0
+Summary: No Bullshit Claw — a 24/7 Signal-driven Swival agent daemon
+Requires-Python: >=3.13
+Requires-Dist: croniter>=3.0.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: swival
+Description-Content-Type: text/markdown
+
+# nbclaw
+
+No Bullshit Claw: a small daemon that puts a [Swival](https://swival.dev/) agent  n the other end of a Signal conversation.
+
+You text it. It does the work and texts back. You can also tell it to do things on a schedule ("every weekday at 9, summarize the git log") and cancel those later.
+
+## Prerequisites
+
+- Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+- A running model. Anything Swival supports works; the quickest is to use [LM Studio](https://lmstudio.ai/) with a tool-calling model loaded.
+- `signal-cli` registered to a phone number and running as an HTTP daemon:
+
+  ```sh
+  signal-cli --account XXXXXXXXX daemon --http 127.0.0.1:3080
+  ```
+
+## Quick start
+
+```sh
+cd nbclaw
+uv sync
+
+uv run nbclaw \
+    --allow YOURPHONE \
+    --model ornith-1.0-9b \
+    --notify YOURPHONE
+```
+
+`--allow` is the number that's permitted to drive the agent (your phone).
+`--notify` is optional and just sends a "nbclaw is online" message on start.
+
+Now message the signal-cli number from your phone:
+
+```text
+you   :  list the python files in ~/src and count them
+nbclaw:  There are 42 .py files under ~/src. ...
+```
+
+## Authorization (read this)
+
+By default the agent runs in **autonomous** mode: it can run shell commands and read or edit files anywhere the account it runs as can reach. The workspace is just where it starts, not a fence. But it means **anyone on the allowlist effectively has a shell on this machine**.
+
+- Always set `--allow` to the specific numbers you trust. With no allowlist set, every incoming message is ignored (fail closed).
+- `--allow-all` exists for testing only. Don't use it on a machine you care about.
+- `--safe` makes the agent read-only: no shell commands, no file edits. Good for a "just answer questions" bot.
+- In a group chat, authorization is checked against the **sender**, but the reply goes to the **whole group**. So one allowed member can make the bot post agent output to everyone in that group. Keep the allowlist to people you trust with that, or only message the bot in 1:1 chats / Note to Self.
+
+## Commands
+
+Send these as Signal messages. Anything not starting with `/` goes to the agent.
+
+| Command                 | What it does                          |
+| ----------------------- | ------------------------------------- |
+| `/help`                 | List the commands.                    |
+| `/status`               | Model, mode, uptime, number of crons. |
+| `/reset`                | Forget this conversation's context.   |
+| `/cron <plain English>` | Schedule a task, described naturally. |
+| `/cron list`            | Show scheduled tasks.                 |
+| `/cron del <name>`      | Cancel a scheduled task.              |
+| `/cron run <name>`      | Run a scheduled task right now.       |
+
+### Scheduling
+
+Just say it after `/cron` in plain English. The model works out the timing and gives the task a short name:
+
+```text
+/cron every weekday at 9am summarize my git log in ~/src/app
+/cron remind me to stretch every 2 hours
+/cron tomorrow at 8am say good morning
+```
+
+Both recurring schedules and one-time reminders ("in 10 minutes…", "tomorrow at 8am…") are understood; one-time jobs delete themselves after they fire.
+
+Results are delivered to the conversation that created the cron, prefixed with its name. Crons run as independent one-shots, so they never pollute your chat's context.
+
+Use `/cron list` to see names, then `/cron del <name>` to cancel.
+
+If you'd rather be exact, the power-user form takes a literal schedule:
+
+```text
+/cron add standup 0 9 * * 1-5 | summarize today's commits in ~/src/myrepo
+```
+
+where the schedule is a 5-field cron expression, `@every 30m` (`30s`/`5m`/`2h`/`1d`), or `@hourly` / `@daily` / `@weekly` / `@monthly`.
+
+## Configuration file
+
+Flags cover the common cases. For anything else, point `--config` at a TOML file.
+
+Top-level keys mirror the settings; a `[swival]` table is passed straight through to `swival.Session`, so the full agent is configurable.
+
+```toml
+# nbclaw.toml
+signal_url = "http://127.0.0.1:3080"
+allow = ["YOURPHONE"]
+notify = "YOURPHONE"
+
+provider = "lmstudio"
+model = "ornith-1.0-9b"
+# base_url = "http://127.0.0.1:1234"   # only if not the provider default
+max_turns = 60
+
+state_dir = "~/.nbclaw"
+
+# MCP servers, in swival's format.
+[mcp_servers.fetch]
+command = "uvx"
+args = ["mcp-server-fetch"]
+
+# Anything here is forwarded verbatim to swival.Session.
+[swival]
+temperature = 0.2
+reasoning_effort = "medium"
+```
+
+Run it:
+
+```sh
+uv run nbclaw --config nbclaw.toml
+```
+
+CLI flags override the file.
+
+## Running 24/7
+
+The agent is meant to stay up.
+
+On macOS, a launchd job keeps it alive across logouts and reboots. A template is in `deploy/com.nbclaw.daemon.plist`; edit the paths and numbers, then:
+
+```sh
+cp deploy/com.nbclaw.daemon.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/com.nbclaw.daemon.plist
+```
+
+On Linux, a user systemd unit does the same job; the plist documents the same command line.
+
+## State
+
+Everything lives under `state_dir` (default `~/.nbclaw`):
+
+- `crons.json` — scheduled tasks, written atomically.
+- `workspace/` — the agent's working directory (its `base_dir`).
+
+## Environment variables
+
+- `NBCLAW_LOG` sets the log level (default `INFO`; try `DEBUG`).
+
+## But why this since there's already XYZ?
+
+NBClaw uses Swival as a Python library, so the CLI isn't required. This lets it work well even with small, local models and short context windows. No large models needed.
+
+More importantly, NBClaw is ridiculously lightweight and incredibly easy to install and use.
+
+No bloat. It intentionally ships with a minimal set of tools, but it gets the job done. And if you need more, you can extend it with skills, MCP servers, and whatever else fits your workflow.
+
+It may not be for you, but this is the minimal claw-style agent I always wanted.

nbclaw-0.1.0/README.md

@@ -0,0 +1,156 @@
+# nbclaw
+
+No Bullshit Claw: a small daemon that puts a [Swival](https://swival.dev/) agent  n the other end of a Signal conversation.
+
+You text it. It does the work and texts back. You can also tell it to do things on a schedule ("every weekday at 9, summarize the git log") and cancel those later.
+
+## Prerequisites
+
+- Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+- A running model. Anything Swival supports works; the quickest is to use [LM Studio](https://lmstudio.ai/) with a tool-calling model loaded.
+- `signal-cli` registered to a phone number and running as an HTTP daemon:
+
+  ```sh
+  signal-cli --account XXXXXXXXX daemon --http 127.0.0.1:3080
+  ```
+
+## Quick start
+
+```sh
+cd nbclaw
+uv sync
+
+uv run nbclaw \
+    --allow YOURPHONE \
+    --model ornith-1.0-9b \
+    --notify YOURPHONE
+```
+
+`--allow` is the number that's permitted to drive the agent (your phone).
+`--notify` is optional and just sends a "nbclaw is online" message on start.
+
+Now message the signal-cli number from your phone:
+
+```text
+you   :  list the python files in ~/src and count them
+nbclaw:  There are 42 .py files under ~/src. ...
+```
+
+## Authorization (read this)
+
+By default the agent runs in **autonomous** mode: it can run shell commands and read or edit files anywhere the account it runs as can reach. The workspace is just where it starts, not a fence. But it means **anyone on the allowlist effectively has a shell on this machine**.
+
+- Always set `--allow` to the specific numbers you trust. With no allowlist set, every incoming message is ignored (fail closed).
+- `--allow-all` exists for testing only. Don't use it on a machine you care about.
+- `--safe` makes the agent read-only: no shell commands, no file edits. Good for a "just answer questions" bot.
+- In a group chat, authorization is checked against the **sender**, but the reply goes to the **whole group**. So one allowed member can make the bot post agent output to everyone in that group. Keep the allowlist to people you trust with that, or only message the bot in 1:1 chats / Note to Self.
+
+## Commands
+
+Send these as Signal messages. Anything not starting with `/` goes to the agent.
+
+| Command                 | What it does                          |
+| ----------------------- | ------------------------------------- |
+| `/help`                 | List the commands.                    |
+| `/status`               | Model, mode, uptime, number of crons. |
+| `/reset`                | Forget this conversation's context.   |
+| `/cron <plain English>` | Schedule a task, described naturally. |
+| `/cron list`            | Show scheduled tasks.                 |
+| `/cron del <name>`      | Cancel a scheduled task.              |
+| `/cron run <name>`      | Run a scheduled task right now.       |
+
+### Scheduling
+
+Just say it after `/cron` in plain English. The model works out the timing and gives the task a short name:
+
+```text
+/cron every weekday at 9am summarize my git log in ~/src/app
+/cron remind me to stretch every 2 hours
+/cron tomorrow at 8am say good morning
+```
+
+Both recurring schedules and one-time reminders ("in 10 minutes…", "tomorrow at 8am…") are understood; one-time jobs delete themselves after they fire.
+
+Results are delivered to the conversation that created the cron, prefixed with its name. Crons run as independent one-shots, so they never pollute your chat's context.
+
+Use `/cron list` to see names, then `/cron del <name>` to cancel.
+
+If you'd rather be exact, the power-user form takes a literal schedule:
+
+```text
+/cron add standup 0 9 * * 1-5 | summarize today's commits in ~/src/myrepo
+```
+
+where the schedule is a 5-field cron expression, `@every 30m` (`30s`/`5m`/`2h`/`1d`), or `@hourly` / `@daily` / `@weekly` / `@monthly`.
+
+## Configuration file
+
+Flags cover the common cases. For anything else, point `--config` at a TOML file.
+
+Top-level keys mirror the settings; a `[swival]` table is passed straight through to `swival.Session`, so the full agent is configurable.
+
+```toml
+# nbclaw.toml
+signal_url = "http://127.0.0.1:3080"
+allow = ["YOURPHONE"]
+notify = "YOURPHONE"
+
+provider = "lmstudio"
+model = "ornith-1.0-9b"
+# base_url = "http://127.0.0.1:1234"   # only if not the provider default
+max_turns = 60
+
+state_dir = "~/.nbclaw"
+
+# MCP servers, in swival's format.
+[mcp_servers.fetch]
+command = "uvx"
+args = ["mcp-server-fetch"]
+
+# Anything here is forwarded verbatim to swival.Session.
+[swival]
+temperature = 0.2
+reasoning_effort = "medium"
+```
+
+Run it:
+
+```sh
+uv run nbclaw --config nbclaw.toml
+```
+
+CLI flags override the file.
+
+## Running 24/7
+
+The agent is meant to stay up.
+
+On macOS, a launchd job keeps it alive across logouts and reboots. A template is in `deploy/com.nbclaw.daemon.plist`; edit the paths and numbers, then:
+
+```sh
+cp deploy/com.nbclaw.daemon.plist ~/Library/LaunchAgents/
+launchctl load ~/Library/LaunchAgents/com.nbclaw.daemon.plist
+```
+
+On Linux, a user systemd unit does the same job; the plist documents the same command line.
+
+## State
+
+Everything lives under `state_dir` (default `~/.nbclaw`):
+
+- `crons.json` — scheduled tasks, written atomically.
+- `workspace/` — the agent's working directory (its `base_dir`).
+
+## Environment variables
+
+- `NBCLAW_LOG` sets the log level (default `INFO`; try `DEBUG`).
+
+## But why this since there's already XYZ?
+
+NBClaw uses Swival as a Python library, so the CLI isn't required. This lets it work well even with small, local models and short context windows. No large models needed.
+
+More importantly, NBClaw is ridiculously lightweight and incredibly easy to install and use.
+
+No bloat. It intentionally ships with a minimal set of tools, but it gets the job done. And if you need more, you can extend it with skills, MCP servers, and whatever else fits your workflow.
+
+It may not be for you, but this is the minimal claw-style agent I always wanted.

nbclaw-0.1.0/deploy/com.nbclaw.daemon.plist

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  launchd template for running nbclaw 24/7 on macOS.
+
+  Edit the paths and phone numbers below, then:
+    cp deploy/com.nbclaw.daemon.plist ~/Library/LaunchAgents/
+    launchctl load ~/Library/LaunchAgents/com.nbclaw.daemon.plist
+
+  KeepAlive restarts nbclaw if it ever exits. It assumes signal-cli and the
+  model server are already running (run those as their own launchd jobs).
+
+  The equivalent command line for a Linux systemd user unit is:
+    ExecStart=/opt/homebrew/bin/uv run --project %h/src/nbclaw nbclaw --config %h/.nbclaw/nbclaw.toml
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.nbclaw.daemon</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/homebrew/bin/uv</string>
+        <string>run</string>
+        <string>--project</string>
+        <string>/Users/YOU/src/nbclaw</string>
+        <string>nbclaw</string>
+        <string>--config</string>
+        <string>/Users/YOU/.nbclaw/nbclaw.toml</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>/Users/YOU/src/nbclaw</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>NBCLAW_LOG</key>
+        <string>INFO</string>
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/Users/YOU/.nbclaw/nbclaw.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/YOU/.nbclaw/nbclaw.log</string>
+</dict>
+</plist>

nbclaw-0.1.0/nbclaw/__init__.py

@@ -0,0 +1,10 @@
+"""nbclaw — No Bullshit Claw.
+
+A 24/7 daemon that drives a swival agent from Signal: send it commands, get
+answers, and schedule or cancel recurring tasks.
+"""
+
+from .config import Config
+
+__all__ = ["Config"]
+__version__ = "0.1.0"

nbclaw-0.1.0/nbclaw/__main__.py

@@ -0,0 +1,28 @@
+"""Entry point: ``python -m nbclaw`` / ``nbclaw``."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+
+from .config import build_config
+from .daemon import Daemon
+
+
+def main() -> None:
+    logging.basicConfig(
+        level=os.environ.get("NBCLAW_LOG", "INFO").upper(),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+    config = build_config()
+    daemon = Daemon(config)
+    try:
+        asyncio.run(daemon.run())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

nbclaw-0.1.0/nbclaw/agent_runner.py

@@ -0,0 +1,83 @@
+"""Bridges Signal conversations to the swival agent.
+
+``swival.Session`` is synchronous and CPU/IO heavy, so every call is run in a
+thread pool. Because the target here is a single local model, the daemon funnels
+all agent work through one worker (see daemon.py); this class is therefore not
+trying to be concurrency-safe across many simultaneous runs.
+
+Each conversation keeps its own long-lived ``Session`` so chat context carries
+across messages. Cron jobs run as independent one-shots and never touch chat
+context.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from swival import AgentError, Result, Session
+
+log = logging.getLogger("nbclaw.agent")
+
+
+def _safe_close(session: Session) -> None:
+    try:
+        session.close()
+    except Exception as exc:  # pragma: no cover - cleanup best effort
+        log.debug("session close error: %s", exc)
+
+
+class AgentRunner:
+    def __init__(self, session_kwargs: dict[str, Any]) -> None:
+        self._kwargs = session_kwargs
+        self._sessions: dict[str, Session] = {}
+
+    def _session_for(self, key: str) -> Session:
+        session = self._sessions.get(key)
+        if session is None:
+            log.info("creating session for %s", key)
+            session = Session(**self._kwargs)
+            self._sessions[key] = session
+        return session
+
+    def reset(self, key: str) -> bool:
+        """Drop a conversation's context. Returns True if there was one."""
+        session = self._sessions.pop(key, None)
+        if session is None:
+            return False
+        _safe_close(session)
+        return True
+
+    # --- blocking primitives (run inside the executor) -----------------
+    def _ask_blocking(self, key: str, prompt: str) -> str:
+        session = self._session_for(key)
+        result = session.ask(prompt)
+        return _answer_text(result)
+
+    def _once_blocking(self, prompt: str) -> str:
+        session = Session(**self._kwargs)
+        try:
+            return _answer_text(session.run(prompt))
+        finally:
+            _safe_close(session)
+
+    # --- async wrappers ------------------------------------------------
+    async def chat(self, key: str, prompt: str) -> str:
+        return await asyncio.to_thread(self._ask_blocking, key, prompt)
+
+    async def once(self, prompt: str) -> str:
+        return await asyncio.to_thread(self._once_blocking, prompt)
+
+    def close_all(self) -> None:
+        for session in self._sessions.values():
+            _safe_close(session)
+        self._sessions.clear()
+
+
+def _answer_text(result: Result) -> str:
+    if result.answer:
+        return result.answer
+    if result.exhausted:
+        raise AgentError("agent ran out of turns without an answer")
+    raise AgentError("agent returned no answer")

nbclaw-0.1.0/nbclaw/commands.py

@@ -0,0 +1,56 @@
+"""Parsing helpers and help text for the slash-command interface.
+
+Anything that doesn't start with ``/`` is treated as a prompt for the agent.
+The command dispatch itself lives in :mod:`nbclaw.daemon` because it needs the
+daemon's live state (scheduler, sessions, start time).
+"""
+
+from __future__ import annotations
+
+HELP_TEXT = """nbclaw — commands
+
+Plain text is sent to the agent. Slash commands:
+
+/help              show this help
+/status            model, uptime, active crons
+/reset             forget this conversation's context
+
+Scheduling — just say it in plain English after /cron:
+  /cron every weekday at 9am summarize my git log in ~/src/app
+  /cron remind me to stretch every 2 hours
+  /cron tomorrow at 8am say good morning
+
+/cron list         list scheduled tasks
+/cron del <name>   cancel a scheduled task
+/cron run <name>   run a scheduled task right now
+
+Power-user form (exact cron expression):
+  /cron add <name> <schedule> | <prompt>
+  schedules: 0 9 * * 1-5  ·  @every 30m  ·  @hourly @daily @weekly @monthly
+""".strip()
+
+
+class CronAddError(ValueError):
+    pass
+
+
+def parse_cron_add(args: str) -> tuple[str, str, str]:
+    """Parse the body of ``/cron add`` into (name, schedule, prompt).
+
+    Grammar: ``<name> <schedule...> | <prompt>``
+    The ``|`` separates the (space-containing) schedule from the prompt.
+    """
+    if "|" not in args:
+        raise CronAddError("missing '|' separating the schedule from the prompt")
+    head, prompt = args.split("|", 1)
+    prompt = prompt.strip()
+    head_parts = head.split()
+    if len(head_parts) < 2:
+        raise CronAddError("expected: <name> <schedule> | <prompt>")
+    name = head_parts[0]
+    schedule = " ".join(head_parts[1:])
+    if not prompt:
+        raise CronAddError("the prompt is empty")
+    if not schedule:
+        raise CronAddError("the schedule is empty")
+    return name, schedule, prompt