Choose a workflow for your task

Choose a workflow for your task#

Start with the outcome, not a provider or feature name. Most gptme tasks fit one of the four rows below. Pick the narrowest execution surface that can finish the job, then increase model capability or tool access only when the task requires it.

Decision matrix#

Task

Start here

Model tier

Execution and approval posture

Answer a low-stakes question

Run gptme "…" with no tools when the answer does not need live or local evidence.

Small and fast.

No external actions; inspect the answer before relying on it.

Research a topic

Give the agent the browser tool and ask for linked sources plus a short synthesis.

Small for collection; stronger reasoning for conflicting evidence or an important decision.

Keep the work local and require source links. The browser can interact with pages, so explicitly forbid external actions and use environment or credential isolation when confirmation prompts are not a reliable boundary.

Create an artifact

Name the output file and acceptance criteria: a report, image, script, or web page.

General-purpose; use a stronger model when structure or judgment matters.

Write only to a dedicated workspace. Review the artifact before sending or publishing it.

Change inspectable code

Run gptme inside a version-controlled checkout; ask it to inspect, edit, test, and show the diff.

Strong coding/reasoning model.

Use confirmations for interactive work or a review-gated branch/PR workflow for autonomous work. Isolate untrusted repositories.

Model names change faster than these capabilities. See Choosing your model for current model examples and Tool Selection & Allowlists for exact tool-selection syntax.

Copy-paste starting points#

Low-stakes answer#

gptme --tools "" \
  "Explain the difference between a process and a thread in five bullets."

Use this for explanations, brainstorming, and rewriting that need no current facts or local files. If the answer affects money, safety, legal obligations, or production behavior, it is no longer low-stakes: ask for evidence and verify it.

Research#

gptme --tools "browser,rag,chats,read" \
  "Compare three maintained Python task queues. Cite primary sources, state the tradeoffs, and save nothing. Use the browser only to read and search; do not interact with pages."

The browser tool also exposes page interactions such as clicks and form entry; its allowlist entry does not restrict it to reading, and confirmation prompts do not cover every browser operation. Explicitly prohibit external actions in the task, but do not treat that instruction as a security boundary. For stronger assurance, run in a VM or container without sensitive credentials or use a restricted account or fine-grained token that cannot write. Use hint:read-only only for tools actually annotated as read-only. For an important choice, split collection from judgment: gather sources cheaply, then use a stronger model to challenge the synthesis and identify missing evidence.

Artifact creation#

mkdir -p output
cd output
gptme \
  "Create report.md comparing the supplied options. Include a decision table and a sources section. Do not publish or send it."

An artifact-oriented task has a named deliverable and acceptance criteria. A file you can inspect, test, or render is easier to verify than a vague request to “work on” something. Use local execution when the output depends on private files or local tools. Use a remote or hosted workspace only when its convenience outweighs the cost of uploading the inputs, and never upload secrets by default.

Inspectable code#

cd /path/to/version-controlled-project
gptme \
  "Inspect the failing tests, make the smallest fix, rerun the targeted tests, and show me the diff. Do not commit or push."

A local checkout gives you a strong review surface: version control, tests, and a diff. For autonomous work, use the review-gated branch/PR workflow in Automation: stage and inspect every change, commit only that reviewed artifact, push only a feature branch, and stop before merge. A PR does not cover side effects outside the checkout, so remove external credentials or constrain them with a dedicated GitHub account or fine-grained token. Review an unfamiliar repository’s gptme.toml before starting because project configuration can run hooks and context commands. See Security Considerations for the complete trust model.

Local or remote?#

Choose based on where the required data and verification tools already live:

  • Local execution is the default for private files, existing repositories, device access, and work that must be verified with local tests.

  • Remote or hosted execution is useful for a clean disposable environment, collaboration, or work that must continue after your machine disconnects.

  • Do not copy data merely to fit the surface. Keep sensitive inputs where they already are, or create an isolated environment with only the files the task needs.

  • Treat remote execution as a different trust boundary. Check credential, retention, network, and filesystem access before granting tools.

Approval rule#

Use interactive confirmations when a human is present, or a review-gated artifact workflow when autonomous work can be fully contained in a checkout. Confirmation prompts are not available in non-interactive mode and do not cover every operation, so they are a convenience rather than a complete security boundary. Require an explicit human review immediately before any action that:

  • sends a message or submits a form;

  • spends money or creates a paid resource;

  • deletes or irreversibly overwrites data; or

  • publishes, deploys, merges, or pushes work to other people.

Drafting is not publishing. Preparing a command is not running it. Ask gptme to stop at the reviewable boundary ("write the draft but do not send", "show the diff but do not commit"). Avoid --no-confirm and --non-interactive for these actions; non-interactive mode implies no confirmations.

Escalate deliberately#

Change one dimension at a time when the first attempt is insufficient:

  1. Add the missing evidence source or local context.

  2. Grant the narrow tool capability needed to inspect or verify it.

  3. Move to a stronger model when the remaining problem is judgment or complex reasoning, not missing information.

  4. Move from local to remote (or the reverse) only when the task’s data, duration, or verification needs justify the trust-boundary change.

This keeps cheap questions cheap, research bounded to approved read operations, artifacts inspectable, and consequential actions under human control.

Contents