Beginner FAQ¶

Fastest green check¶

If you only want one successful local proof first, use the first question on this page, then run loopforge doctor if anything looks off.

This page is intentionally short and copy/paste-friendly. If you are blocked, run loopforge doctor first.

1) I installed LoopForge. What is the minimum first run?¶

ollama serve
loopforge init
mkdir -p loopforge-demo
loopforge agent run --workspace loopforge-demo --prompt "Create hello.txt with the word hi"
cat loopforge-demo/hello.txt

Expected: hello.txt exists and contains hi.

2) Which Ollama model should I use first?¶

Use a small chat model you already have (for example qwen3:4b).

1	`ollama list`

If needed:

1	`ollama pull qwen3:4b`

Then set ~/.loopforge/config.toml:

[providers.ollama]
default_model = "qwen3:4b"

3) How do I know config and dependencies are healthy?¶

loopforge config validate
loopforge doctor

doctor should report: - config parsed - provider connectivity - browser/CDP availability (if browser tools are enabled)

4) Why does `agent run` look stuck?¶

Common causes: - model is too weak for the task/tool pattern - prompt is too broad - browser targets are dynamic/anti-bot pages

Try: - reduce scope of the prompt - switch to a stronger model - add explicit success criteria in the prompt

Example:

loopforge agent run --workspace loopforge-demo --prompt "Read README.md and write notes/summary.md with 5 bullets."

5) Why did a tool call fail with argument errors?¶

This is usually model output format drift (invalid JSON arguments).

Practical mitigations: - simplify prompt - force explicit argument keys in prompt text - retry with stronger model/provider for tool-heavy tasks

6) How do I safely run in a real repository?¶

Always use a dedicated workspace and commit early:

mkdir -p /tmp/loopforge-work
loopforge agent run --workspace /tmp/loopforge-work --prompt "..."

For repository work, prefer harness:

loopforge harness init my-repo
loopforge harness run my-repo --prompt "Run tests and fix one failing case"

7) Browser + web tasks fail on specific sites. Is that a bug?¶

Not always. Some websites use anti-bot or dynamic rendering.

Use this strategy: 1. Verify browser basics with a simple target first. 2. Keep artifacts (screenshot, page dump) for evidence. 3. Use fallback tasks (Wikipedia/public docs) when validating pipelines.

8) How do I write better prompts for beginners?¶

Use this template:

Goal:
Input:
Output file:
Constraints:
Verification command: