Updates README
This commit is contained in:
@@ -1,13 +1,124 @@
|
||||
# Honker
|
||||
|
||||
Honker acts as an ACP (https://agentclientprotocol.com/protocol/overview) bridge to let a user use Signal Messenger to drive the Goose https://goose-docs.ai/ coding agent
|
||||
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.
|
||||
|
||||
## Technical details
|
||||
Send a message to your Signal account, Goose does the work, and the response comes back as a Signal message.
|
||||
|
||||
Honker is written in Python and uses SQLite as its backing store for minimal state tracking.
|
||||
## Prerequisites
|
||||
|
||||
Configuration is done via ~/.config/honker/config.yaml
|
||||
Honker expects both tools to already be installed and configured on the machine where it runs:
|
||||
|
||||
Honker expects both Goose and signal-cli to already be 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+**
|
||||
|
||||
Honker manages the lifecycle of both goose and signal-cli rather than expecting them to be ran as a separate service.
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user