# Verify

Build, launch, and drive a local Honcho stack to verify a change at its runtime surface...

- Repository: https://github.com/plastic-labs/honcho (7877 stars)
- Category: Engineering
- License: AGPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add plastic-labs/honcho --skill verify -g -a claude-code -y`
Codex: `npx skills add plastic-labs/honcho --skill verify -g -a codex -y`
Cursor: `npx skills add plastic-labs/honcho --skill verify -g -a cursor -y`
Gemini CLI: `npx skills add plastic-labs/honcho --skill verify -g -a gemini-cli -y`

## Description

Build, launch, and drive a local Honcho stack to verify a change at its runtime surface (the /v3 HTTP API and the deriver queue). Use when verifying a diff or confirming a change works in the running app.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Verifying changes in Honcho

## Prerequisites

Docker Compose is the preferred way to run the stack, `docker-compose.yml` at
the repo root brings up Postgres (pgvector), Redis, the API server, and the
deriver worker together. If Docker Compose isn't available, the stack can also
run directly on the host (see Launch below); you'll need Postgres with pgvector
and Redis reachable, plus a `.env` with connection strings and an LLM provider
key for any flow that hits a model (deriver, dialectic, dreamer).

Working in a worktree? It carries neither `.env` nor `node_modules`. Copy
`.env` from the main checkout (that's where the provider keys live), and run
`bun install` in `sdks/typescript` if you'll run the full test suite, otherwise the pre-push gate fails on a phantom `Cannot find package 'zod'`.

## Launch

First check whether the stack is already running via Docker Compose:

```bash
docker compose ps          # look for api / deriver / database / redis
docker compose up -d       # start it if not
```

A running stack is not the same as *your branch's code* running, check the
CREATED column; the images may be weeks old. For verifying a diff, the cheap
path is to reuse the stack's Postgres/Redis containers but run the branch's
API as a host process on a spare port:

```bash
uv run uvicorn src.main:app --port 8901   # branch code, stack's DB/Redis
uv run python -m src.deriver              # if the diff touches the worker
```

This avoids both an image rebuild and the port/project-name conflicts a second
compose stack in a worktree would cause. Without Docker at all, run the two
processes the same way against host Postgres + Redis (API default port 8000
via `uv run fastapi dev src/main.py`).

When reading server logs, note that with the main `.env` the telemetry emitter
spams connection warnings at an unreachable endpoint, `grep -v
telemetry.emitter` before looking for the real error.

## Drive it

The rest: https://github.com/plastic-labs/honcho/blob/HEAD/skills/verify/SKILL.md