Guide & Docs

Quick Start

1

Get Credentials

Contact toollysoft@gmail.com to receive your username and password.

2

Run Install Script

Install the Harness Engine from the official repository:

curl -fsSL https://mytoolly.com/install.sh | sudo bash -s -- <username> <password>

3

Run Setup

Generate harness.local.json by providing your user, session name, and project root:

bash setup-env.sh

4

Start the Harness

Launch the 4-Pane tmux session and start the daemon:

bash scripts/harness-start.sh start

Architecture

The default configuration is 4-Pane. Each pane runs a dedicated Claude Code instance with a fixed role. The auto-chain flow connects panes automatically without human intervention.

Pane 0

Opus

Orchestrator

Designs the pipeline, decomposes tasks, delegates to sub-workers, and performs final review.

Pane 1

Sonnet

Backend Engineer

Implements PHP, API, and database logic. Reports completion once, then waits for ACK.

Pane 2

Haiku

Runtime Guardian

Runs syntax checks and response verification. Replies PASS or FAIL. Never modifies code directly.

Pane 3

Sonnet

Frontend Engineer

Handles HTML, CSS, and JavaScript. Runs in parallel with the backend pane.

User → Opus (design & delegate) → Sonnet (implement & report) → Auto-Chain → Haiku (verify) → Opus (close or re-delegate)

Core Features

Declarative Auto-Chain

Declarative rules in the config file automatically trigger the next pipeline step when specific tags and keywords are detected. Built-in cooldown and signature-based deduplication prevent redundant executions.

Periodic Health Check + Auto-Restart

The daemon periodically inspects each pane's process status. On anomaly, it attempts automatic restarts before escalating to the orchestrator.

Task Queue + ACK

Each task carries a unique ID. Workers acknowledge receipt immediately to prevent duplicate execution. After verification, the orchestrator sends CLOSE to finalize the task.

Auto Verification

The verifier automatically runs syntax checks, response validation, and regression tests after each implementation. Returns PASS or FAIL without modifying any code.

Log Rotation

Log files are rotated automatically when they exceed the configured size threshold, preventing disk exhaustion on long-running sessions.

Fallback Routing

If a message fails after retries, it is routed to a designated fallback pane. If the fallback also fails, the message escalates to the orchestrator as a last resort.

Deduplication

Duplicate chain triggers are suppressed via signature matching. The same task cannot be re-triggered within the cooldown window.

Configuration Reference

A single JSON config file serves as the source of truth. A local override file lets you customize values per environment without touching the base config.

{
  "session":        "harness",
  "project_root":   "/path/to/your/project",
  "poll_interval":  <seconds>,
  "timeout":        <seconds>,
  "health_interval": <seconds>,
  "panes":          [ { "id": 0, "role": "orchestrator" }, ... ],
  "auto_chain":     [ ... ],
  "fallback_panes": { ... }
}

Key Fields

Field	Description
session	session name
project_root	absolute path to project root
poll_interval	daemon polling interval (seconds)
timeout	message send timeout (seconds)
panes[]	pane definitions (id, role, responsibility)
auto_chain[]	auto-chain trigger rules
fallback_panes	fallback routing map
health_interval	health check interval (seconds)

Operations Scripts

All scripts live in the scripts/ directory. Run them from the project root.

Script	Purpose
harness-start.sh start	Launch the 4-Pane session and start the daemon
harness-start.sh stop	Gracefully stop the daemon and session
harness-start.sh status	Show daemon status and pane health
harness-report.sh	Print resolved harness config values
setup-env.sh	Generate harness.local.json interactively
install-check.sh	Verify all 5 dependencies are present
log-rotate.sh	Rotate and archive log files
regression-test.sh	Run regression test suite
pane-msg.sh	Send a tagged message to a target pane

Installation Details

Debian / Ubuntu (apt)

curl -fsSL https://mytoolly.com/install.sh | sudo bash -s -- <username> <password>

RHEL / Rocky Linux (rpm)

curl -fsSL https://mytoolly.com/install.sh | sudo bash -s -- <username> <password>

Update Command

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install --only-upgrade toolly-harness

# RHEL/Rocky
sudo yum update toolly-harness

GPG Key	All packages are signed with RSA/SHA256. The public key is fetched automatically by the install script.
Runtime Dependencies	`python3`, `tmux`, `jq`, `claude` CLI

Downloads & Resources

Intermediate