764a7502a3
- CLAUDE.md with commands, structure, key constraints - .claude/rules/ coding standards + workflows - docs/architecture.md with design decisions - .github/ CI workflow, issue templates, PR template - LICENSE (MIT) - .fire-tools.json initialization stamp - README.md rewritten with features, quick start, stack table
98 lines
2.8 KiB
Markdown
98 lines
2.8 KiB
Markdown
# Honcho UI
|
|
|
|
A clean, fast frontend for browsing and chatting with a self-hosted [Honcho](https://github.com/plastic-labs/honcho) instance.
|
|
|
|
> **Privacy-first**: all connection details (base URL, optional token) are stored locally in your browser — never sent anywhere except directly to your Honcho instance.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Dashboard** — workspace count and queue status at a glance, auto-refreshes every 10 s
|
|
- **Workspaces** — paginated list with per-workspace navigation
|
|
- **Peers** — browse peers, view representations, context, and peer cards
|
|
- **Sessions** — paginated message history with summaries and context
|
|
- **Conclusions** — semantic search across conclusions with observer/subject display
|
|
- **Chat** — conversational interface that sends messages through Honcho's chat endpoint with memory context
|
|
- **Dark / light mode** — persisted per browser, instant toggle
|
|
- **Optional auth** — token field is optional; a connection health check auto-detects whether auth is required
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js ≥ 20
|
|
- pnpm ≥ 9
|
|
- A running Honcho instance (local or remote)
|
|
|
|
### Install & run
|
|
|
|
```bash
|
|
git clone https://github.com/offendingcommit/honcho-ui.git
|
|
cd honcho-ui
|
|
pnpm install
|
|
pnpm dev
|
|
```
|
|
|
|
Open http://localhost:5173 — you'll be prompted to enter your Honcho URL.
|
|
|
|
### Connect to your instance
|
|
|
|
1. Enter the base URL of your Honcho instance (e.g. `http://localhost:8000`)
|
|
2. Optionally enter an API token if your instance requires auth
|
|
3. Click **Test connection** — the UI will tell you if auth is needed
|
|
4. Click **Save** — you're in
|
|
|
|
### Build for production
|
|
|
|
```bash
|
|
pnpm build
|
|
# Output in dist/ — serve with any static host
|
|
```
|
|
|
|
## Stack
|
|
|
|
| Layer | Library |
|
|
|-------|---------|
|
|
| Framework | React 19 + Vite 8 |
|
|
| Routing | TanStack Router v1 (file-based) |
|
|
| Data fetching | TanStack Query v5 |
|
|
| API client | openapi-fetch (typed from `openapi.json`) |
|
|
| Styling | Tailwind CSS v4 + CSS custom properties |
|
|
| Animation | framer-motion |
|
|
| Icons | lucide-react |
|
|
| Lint / format | Biome |
|
|
| Tests | Vitest + Testing Library |
|
|
|
|
## Development
|
|
|
|
```bash
|
|
pnpm dev # dev server with HMR
|
|
pnpm lint:fix # Biome lint + format
|
|
pnpm test # run tests
|
|
pnpm generate:api # regenerate src/api/schema.d.ts from openapi.json
|
|
```
|
|
|
|
## Regenerating API types
|
|
|
|
If your Honcho instance is updated, grab a fresh `openapi.json` and run:
|
|
|
|
```bash
|
|
curl http://your-honcho-url/openapi.json -o openapi.json
|
|
pnpm generate:api
|
|
```
|
|
|
|
## Privacy
|
|
|
|
- Base URL and token are stored in `localStorage` under `honcho-ui:config`
|
|
- Theme preference is stored in `localStorage` under `honcho-ui:theme`
|
|
- No telemetry, no analytics, no external requests beyond your configured Honcho instance
|
|
|
|
## Contributing
|
|
|
|
Issues and PRs welcome. Open an issue first for significant changes.
|
|
|
|
## License
|
|
|
|
MIT
|