# 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