Getting Started

From install to your first parallel prompt session in under five minutes.

Prerequisites

• Rust 1.88+ — install via rustup.rs
• claude CLI — must be installed and available in your PATH
• Linux/macOS — Unix domain sockets required for daemon IPC

Installation

$ git clone https://github.com/abusi/clhorde.git
$ cd clhorde
$ cargo build --release

This builds four binaries in target/release/:

• clhorded — the background daemon (manages workers and state)
• clhorde — the TUI (connects to daemon)
• clhorde-cli — the CLI tool (submit prompts, check status, manage store)
• clhorde-web — the web interface (HTTP/WebSocket bridge + browser dashboard)

Copy them somewhere in your PATH for easy access.

Your First Prompt

1. Start the daemon: Run clhorded & (or clhorded in a separate terminal). The daemon manages all workers in the background.
2. Launch the TUI: Run clhorde in your terminal. It connects to the daemon and shows the TUI with an empty prompt list.
3. Enter insert mode: Press i in the TUI. The input bar at the bottom activates.
4. Type a prompt: For example, Explain what a git worktree is
5. Submit: Press Enter. The prompt appears in the queue as pending.
6. Watch it run: A worker picks it up and output streams in the right panel.
7. View output: Press Enter on the selected prompt for a focused view.
8. Return: Press Esc or q to go back to the list.

Running clhorded as a systemd User Service

Instead of running clhorded & manually, you can install it as a systemd user service so it starts automatically on login.

Create the service file directory and unit file:

$ mkdir -p ~/.config/systemd/user

Write ~/.config/systemd/user/clhorded.service:

[Unit]
Description=clhorde daemon - Claude Code orchestrator
After=default.target

[Service]
ExecStart=/path/to/clhorded
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target

Replace /path/to/clhorded with the actual binary path (e.g. ~/.cargo/bin/clhorded or ./target/release/clhorded).

Then enable and start it:

$ systemctl --user daemon-reload
$ systemctl --user enable clhorded.service
$ systemctl --user start clhorded.service

The service will now start automatically each time you log in. Useful commands:

$ systemctl --user status clhorded   # check status
$ systemctl --user stop clhorded     # stop
$ systemctl --user restart clhorded  # restart after rebuild
$ journalctl --user -u clhorded -f   # follow logs

UI Layout

┌─────────────────────────────────────────────────────────┐
│ NORMAL | Workers: 2/4 | Queue: 3 | Done: 5 | Total: 10  │  ← Status bar
├──────────────────────┬──────────────────────────────────┤
│ ▶ ✔ #1 prompt (2.3s)  │                                  │
│   ↻ #2 prompt (1.1s)  │  Output streams here in         │
│   ⏳ #3 prompt          │  real time                      │  ← Main area
│   ✘ #4 prompt (0.5s)  │                                  │
├──────────────────────┴──────────────────────────────────┤
│ > type your prompt here_                                  │  ← Input bar
├─────────────────────────────────────────────────────────┤
│ i:insert  q:quit  j/k:nav  Enter:view  +/-:workers       │  ← Help bar
└─────────────────────────────────────────────────────────┘

• Left panel (40%) — prompt queue with status icons, IDs, and elapsed time
• Right panel (60%) — streaming output for the selected prompt
• Status bar — mode, worker count, queue depth, completion stats
• Input bar — context-aware input based on current mode
• Help bar — shows available keybindings for current mode

Prompt Modes

clhorde supports two prompt modes, toggled with m in Normal mode:

The current default mode is shown in the status bar as [interactive] or [one-shot]. Each prompt remembers the mode it was created with.

Basic Workflow

Queue multiple prompts

Press i, type a prompt, press Enter. Repeat. Queue as many as you want. Workers automatically pull from the queue at whatever concurrency you set.

The input bar supports multi-line editing: press Shift+Enter or Alt+Enter to insert newlines. For complex prompts, press Ctrl+E to open your $EDITOR. You can also batch-load prompts from files with clhorde prompt-from-files tasks/*.md (each prompt automatically gets its own git worktree). Use --run-path <path> to target a specific repo.

Adjust workers

Press + to increase the number of concurrent workers (up to 20) or - to decrease (down to 1). The status bar shows active/max count.

View output

Press Enter on a prompt to enter view mode. Output scrolls automatically. Press f to toggle auto-scroll. Press j/k to scroll manually.

Retry and resume

On a completed or failed prompt, press r to retry (creates a new prompt) or R to resume (continues the Claude session using --resume).

Interactive Follow-ups

When a worker is running or idle:

• One-shot workers: Press s in Normal or View mode to enter Interact mode. Type a message and press Enter to send.
• Interactive (PTY) workers: Press s to enter PTY Interact mode. All keystrokes go directly to the Claude TUI. Press Esc to return.

Filtering and Tags

Press / to enter filter mode. Type to filter prompts by text (case-insensitive). Use @tag to filter by tags. Multiple @tag tokens use AND logic.

Tag prompts when creating them by including @tag in the prompt text:

@frontend @urgent Fix the login page CSS

Next Steps

• Feature deep-dives — learn about worktrees, batch operations, quick prompts, and more
• Keybinding reference — complete key reference for all modes
• Configuration — customize keybindings, templates, and settings
• Web interface — browser dashboard, REST API, and WebSocket reference
• Cheatsheet — printable quick reference card