@visorcraft/idlehands

🤚 Idle Hands

"The devil finds work for idle hands."

Idle Hands is an autonomous AI coding agent built for running local LLMs. It connects your self-hosted model to your codebase and lets it loose — reading files, writing code, running tests, executing commands — all without touching the cloud.

Named after the 1999 cult classic where Anton's possessed hand develops a mind of its own, Idle Hands gives your local model a hand that acts autonomously on your codebase. You define the work. The hand does the rest.

✋ What Makes Idle Hands Different

Your model. Your hardware. Your rules.

Idle Hands is purpose-built for local inference. No API keys to OpenAI. No token metering. No data leaving your network. Just your GPU, your model, and a codebase that needs work done.

• Local-first: Designed around llama-server, ollama, lmstudio, and any OpenAI-compatible local endpoint
• Agent autonomy: The model reads your code, edits files, runs tests, and iterates — hands-free
• Multi-surface: Control it from Telegram, Discord, CLI, TUI, or any supported chat platform
• Self-upgrading: /upgrade checks GitHub for the latest release, installs it, and restarts — from any chat surface

🔪 /anton — The Possessed Hand

This is the flagship feature. Inspired by the movie, /anton is what happens when you chop the hand off and let it go.

How It Works

You write a task document — a simple markdown checklist:

# TASKS.md

## Phase 1: Core refactor

- [ ] Extract shared dispatcher from telegram callback handler
- [ ] Wire retry_fast, retry_heavy, cancel through shared dispatcher
- [ ] Add unit tests for all 3 dispatch actions

## Phase 2: Bot commands

- [ ] Add /upgrade command to all bot surfaces
- [ ] Add /dir command to view and set workspace
- [x] Set up CI pipeline (already done)

Then invoke it:

/anton TASKS.md

The Idle Hands Orchestrator takes over:

• Parses the task document and finds the first incomplete task (- [ ])
• Spawns a fresh, isolated agent session for that single task
• The agent reads your codebase, makes targeted edits, runs tests
• On success: marks the task - [x] in the document and moves to the next
• On failure: skips the task, logs the error, continues to the next
• Each task gets its own clean agent — no context bleed, no accumulated confusion
• When no incomplete tasks remain, the orchestrator completes and returns final run stats

The task document is the single source of truth. You can check it mid-run to see exactly where things stand. Every [x] was earned by a real agent execution with real test results.

Live Progress

Anton pushes real-time updates to whatever surface you invoked it from:

🤚 Anton activated
📄 Task file: TASKS.md
📋 5 tasks pending

🔪 Task 1/5: Extract shared dispatcher from telegram callback handler
🤖 Agent spawned (session: anton-impl-1740829200000-1)
✅ Task 1/5 complete: Extract shared dispatcher

🔪 Task 2/5: Wire retry_fast, retry_heavy, cancel through shared dispatcher
🤖 Agent spawned (session: anton-impl-1740829260000-2)
❌ Task 2/5 failed: Wire retry_fast...
└ Agent timed out after 1200s

🏁 Anton finished
✅ Completed: 4/5
⏭️ Skipped: 1
⏱️ Duration: 42m 15s

Two Execution Modes

Anton supports two modes, configurable per-deployment:

Direct Mode (default)

Single agent per task. Fast, simple, good for straightforward changes:

Task → Agent → Done

Preflight Mode

Two-phase pipeline inspired by how senior engineers work — plan first, then execute:

Task → Discovery Agent (writes spec) → Review Agent (refines spec) → Implementation Agent (follows spec) → Done

Phase 1: Discovery. A planning agent reads your codebase and writes a detailed implementation spec to .agents/tasks/. It identifies what files need to change, what the approach should be, and how to verify the result. The discovery agent is restricted from modifying source files — it can only write the plan.

Phase 1.5: Requirements Review (optional). A review agent reads the plan, tightens it, catches edge cases, and improves it in-place. Think of it as an automated code review of the spec before any code is written.

Phase 2: Implementation. A fresh agent receives the task and the spec file. It follows the plan to write code, run tests, and verify the result. Because it has a clear spec to follow, it's far less likely to drift or loop.

If discovery fails after retries, Anton automatically falls back to direct execution — the hand keeps moving.

Configuration

In your config file:

{
  "anton": {
    "mode": "preflight",
    "requirementsReview": true,
    "taskTimeoutSec": 1200,
    "discoveryTimeoutSec": 600,
    "reviewTimeoutSec": 300,
    "preflightMaxRetries": 2,
    "planDir": ".agents/tasks"
  }
}

Or override per-run from CLI:

idlehands anton run TASKS.md --mode preflight

Preflight Progress in Chat

When running in preflight mode, you get granular updates for every phase:

🔪 Task 1/3: Refactor session manager
🔎 Discovery: analyzing codebase for task 1/3...
🤖 Agent spawned (session: anton-discovery-1740829200000-1-0)
📝 Plan written: task-1-1740829200000.md
🧪 Reviewing plan: task-1-1740829200000.md...
🤖 Agent spawned (session: anton-review-1740829215000-1)
✅ Plan reviewed and refined
🛠️ Implementation: following spec task-1-1740829200000.md
🤖 Agent spawned (session: anton-impl-1740829230000-1)
✅ Task 1/3 complete: Refactor session manager

Why This Matters

Most AI coding tools give you a chat window and hope for the best. /anton gives you:

• Structured autonomy — the model works through a defined plan, not freestyle
• Task isolation — each task starts with a fresh context, preventing the drift and confusion that kills long agent sessions
• Plan-then-execute — preflight mode means the implementation agent has a clear spec to follow, dramatically reducing read-loops and aimless exploration
• Persistent progress — if the process stops, your task document shows exactly what's done and what's left
• Graceful failure — failed tasks are skipped, not fatal; the hand keeps moving
• Observable execution — live progress updates to your chat surface; /anton status for on-demand checks; /anton stop to halt gracefully

Commands

Command	Surface	Description
/anton TASKS.md	Telegram, Discord, TUI	Start the orchestrator on a task document
/anton status	All	Show current task progress
/anton stop	All	Stop after current task completes
idlehands anton run TASKS.md	CLI	Run from terminal
idlehands anton run TASKS.md --mode preflight	CLI	Run with discovery → implementation pipeline
idlehands anton run TASKS.md --dry-run	CLI	Preview tasks without executing

🎛️ Runtime Orchestrator

For those running multiple models across multiple machines, the Runtime Orchestrator manages your inference infrastructure:

# Initialize runtime config
idlehands orchestrator init

# Plan a model switch (dry run)
idlehands orchestrator plan --model qwen3-coder-next --json

# Apply — stops current server, switches backend, starts model, probes health
idlehands orchestrator apply --model qwen3-coder-next

# Check what's running
idlehands orchestrator status

Supports:

• Local and remote hosts (SSH transport)
• Backend switching (Vulkan, ROCm, CPU)
• Health probing with configurable timeouts
• Lock-based safety — no concurrent applies
• Deterministic plans — preview every step before execution

⚡ Quick Start

1. Install

npm install -g @visorcraft/idlehands

2. Configure

idlehands configure

Point it at your local model endpoint (e.g., http://localhost:8082/v1).

3. Set workspace

# From CLI
idlehands agents add --workspace /path/to/your/repo

# Or from any chat surface
/dir /path/to/your/repo

4. Start the bot

idlehands bot

5. Start coding

Send a message from Telegram, Discord, or the TUI:

Read the codebase and fix the failing tests in src/utils.ts

Or go autonomous with /anton:

/anton TASKS.md

🛠️ Local LLM Setup (Recommended)

Idle Hands works best with llama-server from the visorcraft/llama.cpp fork, which includes fixes for hybrid Mamba-Transformer models.

Recommended flags

llama-server \
  -m /path/to/model.gguf \
  --port 8082 \
  --host 0.0.0.0 \
  --chat-template-file /path/to/qwen3.jinja \
  --jinja \
  -ngl 99 \
  -fa on \
  -dio \
  --no-warmup \
  -ctk q4_0 \
  -ctv q4_0 \
  -np 4 \
  -c 800000 \
  -cb \
  --ctx-checkpoints 0 \
  --cache-reuse 64 \
  --slots

Key notes

• Template matters: qwen3.jinja is critical for proper tool-call generation with Qwen3-Coder models
• KV cache quantization (-ctk q4_0 -ctv q4_0): Keeps VRAM usage manageable for large contexts
• Flash attention (-fa on): Required for performance
• Direct I/O (-dio): Recommended for the visorcraft fork

See docs/SETUP_LOCAL_QWEN3_CODER_NEXT.md for the complete setup guide.

💬 Bot Commands (All Surfaces)

These work in Telegram, Discord, TUI, and every other connected chat surface:

Command	Description
/anton <file>	Start autonomous task execution
/anton status	Check orchestrator progress
/anton stop	Stop after current task
/dir	Show current workspace
/dir /path	Set workspace directory
/upgrade	Self-upgrade to latest version
/update	Update dependencies and CLI
/status	Show session info
/model	View/change active model
/new	Start fresh session
/compact	Compress context
/stop	Cancel current operation

📂 Project Structure

src/
├── commands/
│   ├── anton.ts              # /anton orchestrator core (direct + preflight modes)
│   ├── orchestrator.ts       # Runtime orchestrator (host/backend/model)
│   └── ...
├── auto-reply/reply/
│   ├── commands-anton.ts     # /anton bot command handler + progress routing
│   ├── commands-dir.ts       # /dir command handler
│   ├── commands-upgrade.ts   # /upgrade command handler
│   └── commands-core.ts      # Universal command dispatch
├── bot/
│   └── upgrade-command.ts    # Self-upgrade engine
└── cli/program/
    └── register.orchestrator-anton.ts  # CLI registration

🔒 Security

• No telemetry. No analytics. No call-home behavior.
• No cloud dependency. Your model, your data, your network.
• Diagnostic events are local in-process only.
• Agent tool execution is sandboxed with configurable safety profiles.
• Anti-obfuscation detection blocks suspicious commands from the AI.

📜 Attribution

Idle Hands is a fork of OpenClaw, licensed under the MIT License. See LICENSE for details.

🎬

"I'm not possessed! My hand is!" — Anton Tobias, Idle Hands (1999)

Your hand. Your model. Let it loose. 🤚