Turtle is a local terminal assistant CLI that can either explain terminal concepts or run commands for you (with a safety confirmation prompt) using a tool-calling agent backed by Ollama.

• Two modes
  • Explain Mode: short, terminal-friendly explanations with optional example commands
  • Action Mode: proposes terminal commands and executes them only after y/n confirmation
• Tool-calling command execution
  • Uses a strict run_terminal tool schema for structured command requests
• Safer by design
  • Commands are shown before execution
  • User must confirm before anything runs
• Works great for common shell workflows
  • File/folder operations (create/move/rename/delete)
  • Searching and listing
  • Inspecting files and directories

• Python (CLI + agent)
• Ollama (local LLM runtime)
• Qwen 2.5 3B (qwen2.5:3b) (default model)
• Rich (terminal UI panels, styled output)

• macOS (or Linux) terminal
• Python 3.x
• Ollama installed and running

Pull the model:

ollama pull qwen2.5:3b 

From the repo root:

pip install -U pip pip install ollama rich 

This makes the turtle command available globally without activating a venv:

brew install pipx pipx ensurepath cd /path/to/qhacks-cli-agent pipx install -e . 

Restart your terminal (or run exec zsh -l), then:

turtle 

If you prefer running with a local environment:

python -m venv .venv source .venv/bin/activate pip install -U pip pip install -e . turtle 

Start Turtle:

turtle 

• Type your request at the prompt.
• If Turtle proposes a command, you’ll be asked to confirm with y/n before it executes.
• Type exit or quit to leave.

• On macOS, some folders (e.g. Downloads, Desktop, Documents) may require enabling Terminal / VS Code in:
  • System Settings → Privacy & Security → Files and Folders (or Full Disk Access)
  • Otherwise commands like find may show Operation not permitted.

• terminal_worker/worker.py — main CLI agent loop + prompts + command execution
• terminal_worker/tool_schema.py — strict tool schema for run_terminal
• pyproject.toml — packaging + CLI entrypoint (turtle)

Add your license here (e.g. MIT).