An autonomous AI coding agent built for running local LLMs.
Connect your self-hosted model to your codebase and let it loose — reading files, writing code, running tests, executing commands — all without touching the cloud.
Local-first · agent autonomy · Telegram · Discord · CLI · TUI
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.
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:
/upgradechecks GitHub for the latest release, installs it, and restarts — from any chat surface
This is the flagship feature. Inspired by the movie, /anton is what happens when you chop the hand off and let it go.
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.
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
Anton supports two modes, configurable per-deployment:
Single agent per task. Fast, simple, good for straightforward changes:
Task → Agent → Done
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.
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 preflightWhen 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
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 statusfor on-demand checks;/anton stopto halt gracefully
| 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 |
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 statusSupports:
- 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
npm install -g @visorcraft/idlehandsidlehands configurePoint it at your local model endpoint (e.g., http://localhost:8082/v1).
# From CLI
idlehands agents add --workspace /path/to/your/repo
# Or from any chat surface
/dir /path/to/your/repoidlehands botSend 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
Idle Hands works best with llama-server from the visorcraft/llama.cpp fork, which includes fixes for hybrid Mamba-Transformer models.
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- Template matters:
qwen3.jinjais 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.
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 |
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
- 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.
Idle Hands is licensed under the MIT License — see LICENSE for the full text.
© 2025 Peter Steinberger. Idle Hands is a fork of OpenClaw; the original copyright and MIT terms are retained.