fluffypony/dothething

Dothething (dtt) – a local AI‑agent for autonomous tasks

What it is – Dothething (invoked as dtt) is a self‑contained, locally‑run AI assistant. You give it a natural‑language instruction, and the agent plans, runs tools, and returns the result without you having to supervise each step. It is built around LLM calls routed through OpenRouter and a toolbox that includes web search, a privacy‑focused browser, file‑system access, shell commands, email, and clipboard handling.

How it works – Each turn the main model decides which tool(s) to call, receives the tool output, and decides the next action. The loop continues until the task is marked complete, a cost/loop limit is hit, or the agent reports it cannot proceed. Tool calls can be batched and ordered with an exec_order field, letting the agent execute several actions in parallel when possible.

Key capabilities

• Research & data extraction – Searches a local SearXNG instance, queries scholarly APIs (OpenAlex, Crossref, PubMed, arXiv), and scrapes pages with a hardened Firefox fork (Camoufox) via the Notte framework.
• Browser automation – Handles captchas, multi‑step logins, form filling, clicks, file uploads, and can pause for manual login when needed.
• File & shell operations – Read/write files, run arbitrary commands, make HTTP requests, and manipulate the system clipboard (including images).
• Email integration – Sends/receives through AgentMail.
• Extensible skills – Drop a SKILL.md into ~/.dtt/skills/ and the agent will load the skill on demand.
• Cost awareness – Tracks token usage and dollar cost via OpenRouter, with Anthropic prompt‑caching to reduce expense.
• Modes –
  • Normal – cheap, fast models (DeepSeek Flash, Gemini Flash, Claude Sonnet, GPT‑5.6 Terra) with full toolset.
  • Advanced – strongest models (Claude Fable + Astra) for hard problems.
  • Quick – single‑shot on a fast frontier model (Claude Opus Fast) with a trimmed toolset for rapid answers.
• Orchestrator & MCP – Run multiple agents from one terminal or expose the search/browser tools to other agents via an MCP server.

Installation / quick start

curl -fsSL dotheth.ing/dtt.sh | bash -s -- --install   # installs to ~/.local/bin/dtt
# or clone the repo and run ./dtt.sh --install

dtt --prompt "Find the 10 largest public companies by revenue that went bankrupt in the last 20 years and write a markdown report with causes and timelines."

The first run creates a Python 3.11+ virtual environment, installs SearXNG, and sets up the Notte browser framework. It then prompts for an OpenRouter API key (required) and optionally a 2Captcha key.

Typical command‑line flags

Flag	Meaning
q / --quick	Fast one‑shot mode (no planning, no oracle)
--advanced	Use strongest models, higher reasoning depth
--prompt "..."	Supply the task inline (otherwise an editor opens)
--cwd DIR	Working directory for file ops
--max-loops N	Upper bound on agent turns (default 200, 15 in quick)
--model ROLE=SLUG	Override model for a role (main, worker, oracle, browser)
--resume ID	Continue a previously saved thread
--browser-session NAME	Reuse a named Firefox profile (preserves logins)
--headed / --headless	Show or hide the browser window
--orchestrator	Manage multiple agents from one terminal
--pipe	Emit only final output for pipelines (exit codes indicate success/partial/failure)
--tui	Experimental full‑screen terminal UI
--notify-desktop / --notify-email EMAIL	Desktop or email notification when the task finishes
--max-cost USD	Stop when cumulative OpenRouter cost reaches this amount

System requirements

• macOS or Linux
• Python 3.11+ (installed automatically in a virtualenv)
• OpenRouter API key (mandatory)
• Optional: 2Captcha key (for solving captchas), AgentMail key (email), wl-clipboard or xclip for image clipboard support.

Why it matters – Dothething bundles a full autonomous workflow stack (LLM planning, search, privacy‑preserving browser automation, file & OS interaction) into a single command‑line tool. It lets power users delegate complex, multi‑step internet‑heavy tasks to an AI without leaving their machine, while giving fine‑grained control over models, cost, and privacy.