125 lines
3.8 KiB
Markdown
125 lines
3.8 KiB
Markdown
# Honker
|
|
|
|
Honker is an [ACP](https://agentclientprotocol.com/protocol/overview) bridge that lets you drive the [Goose](https://goose-docs.ai/) coding agent from Signal Messenger.
|
|
|
|
Send a message to your Signal account, Goose does the work, and the response comes back as a Signal message.
|
|
|
|
## Prerequisites
|
|
|
|
Honker expects both tools to already be installed and configured on the machine where it runs:
|
|
|
|
- **[Goose](https://goose-docs.ai/)** — installed and configured with an AI provider (`goose configure`)
|
|
- **[signal-cli](https://github.com/AsamK/signal-cli)** — installed and registered/linked to a Signal account
|
|
- **[uv](https://docs.astral.sh/uv/)** — Python package manager
|
|
- **Python 3.12+**
|
|
|
|
## Quick Start
|
|
|
|
1. **Clone and install**
|
|
|
|
```bash
|
|
git clone <repo-url> honker
|
|
cd honker
|
|
uv sync
|
|
```
|
|
|
|
2. **Create a config file**
|
|
|
|
```bash
|
|
mkdir -p ~/.config/honker
|
|
cp config.sample.yaml ~/.config/honker/config.yaml
|
|
```
|
|
|
|
Edit `~/.config/honker/config.yaml` with your details:
|
|
|
|
```yaml
|
|
account: "+15551234567"
|
|
|
|
trusted_contacts:
|
|
- name: "Alice"
|
|
number: "+15559876543"
|
|
|
|
working_directory: "/home/user/projects"
|
|
```
|
|
|
|
3. **Run honker**
|
|
|
|
```bash
|
|
uv run honker
|
|
```
|
|
|
|
That's it. Honker starts signal-cli and Goose, connects them, and waits for messages from your trusted contacts.
|
|
|
|
## Configuration
|
|
|
|
All configuration lives in `~/.config/honker/config.yaml` (or pass `--config <path>`).
|
|
|
|
| Option | Default | Description |
|
|
|---|---|---|
|
|
| `account` | *(required)* | Your Signal phone number (e.g. `"+15551234567"`) |
|
|
| `trusted_contacts` | `[]` | List of contacts allowed to interact with Goose. Each has a `name` and `number`. |
|
|
| `working_directory` | `.` | Working directory for Goose sessions. Use an absolute path. |
|
|
| `auto_approve_tools` | `false` | When `true`, Goose runs tools without asking. When `false`, each tool call prompts you for approval over Signal. |
|
|
| `forward_thoughts` | `false` | When `true`, forwards Goose's chain-of-thought reasoning to Signal. Can be noisy. |
|
|
|
|
See [config.sample.yaml](config.sample.yaml) for a complete example.
|
|
|
|
## Usage
|
|
|
|
Send a regular text message from a trusted contact's Signal account. Honker forwards it to Goose, waits for the response, and sends it back.
|
|
|
|
### Slash Commands
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `/cancel` | Cancel the current in-progress request |
|
|
| `/new` | Close the current session and start a fresh one |
|
|
| `/help` | Show available commands |
|
|
|
|
### Tool Approval
|
|
|
|
When `auto_approve_tools` is `false` (the default), Goose asks for permission before running tools. You'll receive a message like:
|
|
|
|
```
|
|
🔐 *Permission requested*
|
|
|
|
shell · rm -rf /tmp/old-stuff
|
|
|
|
1. allow_always
|
|
2. allow_once
|
|
3. reject_once
|
|
4. reject_always
|
|
|
|
Reply with a number to choose:
|
|
```
|
|
|
|
Reply with a number or the option name (e.g. `2` or `allow`).
|
|
|
|
### Images
|
|
|
|
You can send images to Goose via Signal — they're forwarded as part of the prompt. Useful for asking about screenshots, diagrams, etc.
|
|
|
|
## Debugging
|
|
|
|
```bash
|
|
uv run honker --debug ./logs
|
|
```
|
|
|
|
This enables verbose logging and writes per-process output to the given directory:
|
|
|
|
- `logs/signal-cli.stdout.log` / `logs/signal-cli.stderr.log`
|
|
|
|
Goose maintains its own logs at `~/.local/state/goose/logs/`.
|
|
|
|
## Technical Details
|
|
|
|
- Honker manages the lifecycle of both Goose and signal-cli rather than expecting them as separate services
|
|
- Goose is launched via `goose acp` (stdio-based ACP protocol) using the [agent-client-protocol](https://pypi.org/project/agent-client-protocol/) Python library
|
|
- signal-cli runs as a daemon with a Unix socket JSON-RPC interface
|
|
- Each trusted contact gets their own Goose session with separate conversation history
|
|
- Only one prompt per user is processed at a time — additional messages get a "please wait" reply
|
|
|
|
## License
|
|
|
|
TBD
|