From 38014aaeb6793c0bfca90cd69ec4522dc88d3c29 Mon Sep 17 00:00:00 2001
From: James Brechtel <git@jamesbrechtel.com>
Date: Sat, 9 May 2026 16:39:25 -0400
Subject: [PATCH] Updates README

---
 README.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 117 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 8d50505..c0fa4a1 100644
--- a/README.md
+++ b/README.md
@@ -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