{"id":45025434,"url":"https://github.com/visorcraft/idlehands","last_synced_at":"2026-03-03T08:51:58.484Z","repository":{"id":340160306,"uuid":"1164424285","full_name":"visorcraft/IdleHands","owner":"visorcraft","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-25T05:17:02.000Z","size":1400,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T10:57:10.336Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/visorcraft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T04:09:56.000Z","updated_at":"2026-02-25T05:16:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/visorcraft/IdleHands","commit_stats":null,"previous_names":["visorcraft/idlehands"],"tags_count":56,"template":false,"template_full_name":null,"purl":"pkg:github/visorcraft/IdleHands","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visorcraft%2FIdleHands","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visorcraft%2FIdleHands/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visorcraft%2FIdleHands/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visorcraft%2FIdleHands/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/visorcraft","download_url":"https://codeload.github.com/visorcraft/IdleHands/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visorcraft%2FIdleHands/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29959284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T01:47:18.291Z","status":"online","status_checked_at":"2026-03-01T02:00:07.437Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-19T03:08:37.030Z","updated_at":"2026-03-01T04:24:04.826Z","avatar_url":"https://github.com/visorcraft.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Idle Hands\n\n**Local-first coding agent CLI for OpenAI-compatible endpoints.**  \nFast in the terminal, practical in production, and built to run close to your code.\n\n📚 Full docs: https://visorcraft.github.io/IdleHands/\n\n---\n\n## Why Idle Hands\n\nIdle Hands is built for people who want an agent that can actually ship work, not just chat:\n\n- **TUI-first UX** for real daily use (streaming output, slash commands, approvals)\n- **Runtime orchestration** (hosts/backends/models) for local + remote model stacks\n- **Safety + approvals** with explicit modes (`plan`, `reject`, `default`, `auto-edit`, `yolo`)\n- **Headless mode** for CI and scripts (`json`, `stream-json`, `--fail-on-error`, `--diff-only`)\n- **Bot frontends** (Telegram + Discord) with service management\n- **Trifecta subsystem** (Vault + Replay + Lens) for durable memory, reversibility, and context shaping\n\n---\n\n## What makes Idle Hands unique: Trifecta\n\nTrifecta is the integrated core of Idle Hands:\n\n- **Vault** → persistent memory + notes (`/vault`, `/note`, `/notes`)\n- **Replay** → file checkpoints and rewind/diff (`/checkpoints`, `/rewind`, `/diff`, `/undo`)\n- **Lens** → structural compression/indexing for better context usage\n\nRuntime controls:\n\n```bash\n--no-trifecta\n--no-vault\n--no-lens\n--no-replay\n--vault-mode active|passive|off\n```\n\nDetailed docs: [Trifecta guide](https://visorcraft.github.io/IdleHands/guide/trifecta)\n\n---\n\n## Install\n\n### npm (recommended)\n\n```bash\nnpm i -g @visorcraft/idlehands@latest\nidlehands --help\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/visorcraft/idlehands.git\ncd idlehands\nnpm i\nnpm run build\nnode dist/index.js --help\n```\n\nRequirements:\n\n- Node.js **24+**\n- Linux (recommended target environment)\n\n---\n\n## Quick start\n\n```bash\nidlehands setup\nidlehands\n```\n\nOne-shot mode:\n\n```bash\nidlehands -p \"run npm test and fix failures\"\n```\n\nProject-scoped session:\n\n```bash\nidlehands --dir ~/projects/myapp\n```\n\nResume/fresh controls:\n\n```bash\nidlehands --continue\nidlehands --resume\nidlehands --resume my-session\nidlehands --fresh\n```\n\n---\n\n## Linux hardening (recommended)\n\nIf you run Idle Hands regularly on Linux, use a dedicated low-privilege account.\n\n### 1) Create a restricted user\n\n```bash\nsudo useradd --system --create-home --home-dir /home/idlehands --shell /bin/bash idlehands\nsudo passwd -l idlehands\n```\n\n### 2) Give it only the project dirs it needs\n\n```bash\nsudo mkdir -p /home/idlehands/work\nsudo chown -R idlehands:idlehands /home/idlehands\n```\n\n### 3) Run Idle Hands as that user\n\n```bash\nsudo -u idlehands -H bash -lc 'idlehands setup'\nsudo -u idlehands -H bash -lc 'idlehands --dir /home/idlehands/work'\n```\n\nThis limits blast radius if the agent runs bad commands, and keeps your main user environment cleaner.\n\n---\n\n## Running bots as a service\n\nIdle Hands can manage a user-level systemd service for bot frontends.\n\n```bash\nidlehands service install\nidlehands service status\nidlehands service start\nidlehands service logs\n```\n\nTo keep user services running after logout:\n\n```bash\nsudo loginctl enable-linger \u003cuser\u003e\n```\n\nIf you use a dedicated `idlehands` account, install/manage the service while logged in as that user.\n\n---\n\n## Approval modes at a glance\n\n- `plan` → dry plan only, no mutations\n- `reject` → non-interactive safe mode, rejects mutating operations\n- `default` → asks before risky actions\n- `auto-edit` → allows normal code-edit flow, still safety-aware\n- `yolo` / `--no-confirm` → no confirmations (fastest, riskiest)\n\n---\n\n## Documentation map\n\n- [Getting Started](https://visorcraft.github.io/IdleHands/guide/getting-started)\n- [Trifecta Guide](https://visorcraft.github.io/IdleHands/guide/trifecta)\n- [Runtime Orchestration](https://visorcraft.github.io/IdleHands/guide/runtime)\n- [Bots + Service](https://visorcraft.github.io/IdleHands/guide/bots)\n- [CLI Reference](https://visorcraft.github.io/IdleHands/reference/cli)\n- [Config Reference](https://visorcraft.github.io/IdleHands/reference/config)\n- [Safety Model](https://visorcraft.github.io/IdleHands/reference/safety)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvisorcraft%2Fidlehands","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvisorcraft%2Fidlehands","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvisorcraft%2Fidlehands/lists"}