HunesFox CLI

Multi-provider AI coding CLI with autonomous execution, guardrails, checkpoints, and rollback.

Live Vibe

Contents

• Why HunesFox
• Install
• Quick Start
• Autonomy Mode
• Quick Recipes
• Safety Model
• Troubleshooting
• Architecture
• Development
• License

Why HunesFox

HunesFox is built for developers who want speed, control, and provider freedom.

• 🔌 Provider-agnostic: OpenAI-compatible, Anthropic, Cloudflare, Ollama
• 🧠 Agent-first workflows with interactive terminal UX
• 🤖 Autonomous mode with watchdog limits, budgets, validation loop, and rollback
• 🛡️ Built-in shell safety guard for risky execution patterns
• 💾 Sessions, memory, checkpoints, and exportable reports

Install

Package managers

npm i -g @hunesfox/cli

bun add -g @hunesfox/cli

Install scripts

curl -fsSL https://raw.githubusercontent.com/hunesfox/hunesfox-cli/main/install/install.sh | bash

irm https://raw.githubusercontent.com/hunesfox/hunesfox-cli/main/install/install.ps1 | iex

Advanced: untrusted-source mode (risky)

curl -fsSL https://raw.githubusercontent.com/hunesfox/hunesfox-cli/main/install/install.sh | bash -s -- --allow-untrusted

irm https://raw.githubusercontent.com/hunesfox/hunesfox-cli/main/install/install.ps1 | iex --allow-untrusted

Then run:

hunesfox

Quick Start

/connect
/model
/mode agent
/help

Autonomy Mode

Core commands

/autonomy help
/autonomy start <goal>
/autonomy status
/autonomy summary
/autonomy plan
/autonomy budget
/autonomy watchdog
/autonomy tick
/autonomy run 5
/autonomy run until-pause
/autonomy stop

Checkpoints & rollback

/autonomy checkpoint <reason>
/autonomy checkpoints
/autonomy rollback --suggested
/autonomy rollback latest
/autonomy rollback #2
/autonomy rollback <checkpoint-id>

Policies

/autonomy policy untrusted on|off
/autonomy policy checkpoint-interval 3
/autonomy policy soft-limits 90000 12 40
/autonomy policy budget 200 180 3

Logs, export, maintenance

/autonomy log 30
/autonomy export json
/autonomy export md reports/autonomy-report.md
/autonomy checkpoints --prune --keep 10 --older-than-days 30 --yes
/autonomy reset --yes
/autonomy reset --yes --full

Quick Recipes

1) Safe autonomous run

/autonomy start Improve CLI stability and reduce regressions
/autonomy policy untrusted off
/autonomy policy soft-limits 90000 12 40
/autonomy policy budget 80 120 3
/autonomy run until-pause
/autonomy summary

2) Validation fail + suggested rollback

/autonomy start Refactor without breaking checks
/autonomy tick
/autonomy watchdog
/autonomy rollback --suggested
/autonomy summary

3) Long run + report

/autonomy start Prepare project for next release
/autonomy policy budget 200 240 4
/autonomy run 20
/autonomy export md reports/autonomy-release.md
/autonomy stop

Safety Model

Autonomous shell execution is guarded by default.

When autonomy is active and untrusted is off, HunesFox blocks risky patterns and emits explicit codes:

• AUTONOMY_GUARD_E001 untrusted fetch + immediate pipe-exec
• AUTONOMY_GUARD_E002 untrusted install URL
• AUTONOMY_GUARD_E003 untrusted remote script-exec hint
• AUTONOMY_GUARD_E004 untrusted ExecutionPolicy bypass
• AUTONOMY_GUARD_E005 generic untrusted HTTP pipe-exec

Troubleshooting

validation-failed:<check>

• Inspect: /autonomy watchdog
• Rollback: /autonomy rollback --suggested
• Retry with smaller batch: /autonomy run 3

guard-triggered: AUTONOMY_GUARD_EXXX

• Command was blocked by safety policy
• Use official sources or explicitly enable risky mode:
• /autonomy policy untrusted on

budget:*

• Increase limits:
• /autonomy policy budget <maxTicks> <maxRuntimeMinutes> <maxConsecutiveFailures>
• Inspect remaining budget:
• /autonomy budget

Too many checkpoints

• /autonomy checkpoints --prune --keep 10 --older-than-days 30 --yes

Architecture

src/
  agent/        # model loop + tool orchestration
  auth/         # provider accounts
  autonomy/     # state, budgets, checkpoints, events
  core/         # CLI command handlers and orchestration
  memory/       # short-term and persistent memory
  plugins/      # plugin hooks
  providers/    # model providers
  tools/        # filesystem/shell tools + safety guard
  ui/           # terminal rendering and prompts

Development

bun install
bun run build
bun run typecheck
bun test

Focused tests:

bun test tests/autonomy-manager.test.ts tests/tools-guard.test.ts

License

MIT