Metadata-Version: 2.4
Name: nbclaw
Version: 0.1.3
Summary: No Bullshit Claw — a 24/7 Signal-driven Swival agent daemon
License-File: LICENSE
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.

## Dependencies

- 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.

The allowlist controls *who* can drive the agent. It does nothing to limit *what* the agent can reach once it's driven. For that, put the whole thing in a sandbox — see below.

## Sandboxing with nono

The agent runs shell commands and edits files with the privileges of the account nbclaw runs as. The workspace is where it starts, not a fence. If you want a hard boundary — so a confused model, a bad cron, or a prompt-injected web page can't wander off and read your SSH keys or wipe a directory — run the daemon inside [nono](https://nono.sh).

nono is a capability-based sandbox that enforces filesystem and network access at the kernel level: Landlock on Linux, Seatbelt on macOS. The denial happens in the kernel, not in the agent's own guards, so it holds even if the model misbehaves.

### Running it 24/7 under nono

The launchd and systemd setups in [Running 24/7](#running-247) work the same way — just make the wrapper the program they launch. In the plist, the `ProgramArguments` become `nono run … -- …/.venv/bin/nbclaw …` instead of bare nbclaw. One wrinkle: launchd and systemd don't expand `$TMPDIR`, so pass a literal temp path there (the value of `echo $TMPDIR`).

For the full picture of nono's flags, profiles, and credential brokering, see Swival's [nono guide](https://swival.dev/pages/nono.html).

## 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. |
| `/clear`                | Forget this conversation's context.   |
| `/queue`                | Show running and queued work.         |
| `/cancel [id\|all]`     | Cancel queued work.                   |
| `/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.chrome]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest", "--isolated", "--no-usage-statistics", "--no-performance-crux"]

# 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.

To keep the daemon sandboxed while it runs unattended, wrap that command in `nono run` — see [Sandboxing with nono](#sandboxing-with-nono).

## 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.
