honker/README.md

Honker

Honker is an ACP bridge that lets you drive the Goose 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 — installed and configured with an AI provider (goose configure)
• signal-cli — installed and registered/linked to a Signal account
• uv — Python package manager
• Python 3.12+

Quick Start

1. Clone and install

   git clone <repo-url> honker
   cd honker
   uv sync
   

2. Create a config file

   mkdir -p ~/.config/honker
   cp config.sample.yaml ~/.config/honker/config.yaml
   

   Edit ~/.config/honker/config.yaml with your details:

   account: "+15551234567"
   
   trusted_contacts:
     - name: "Alice"
       number: "+15559876543"
   
   working_directory: "/home/user/projects"
   

3. Run honker

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

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