Agent loop

Plain text in the REPL starts the coding agent. The model receives tool schemas, calls tools, gets results, and continues until finish_task or a limit.

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  vritraai   │────▶│  Agent loop  │────▶│  Providers / LLM │
│  (REPL UI)  │     │  tools/exec  │◀────│  + failover      │
└─────────────┘     └──────────────┘     └─────────────────┘
                           │
                           ▼
                    Workspace + .vritraai/
                    files · memory · trust

One turn

  1. Prompt

    Your objective plus conversation/tool history is sent to the active model.

  2. Tool calls

    The model may call one or more tools (read, write, search, shell, …).

  3. Local execution

    Tools run on your machine inside the workspace. Writes/shell go through approval when required.

  4. Feedback

    Tool outputs are appended; the loop continues with a fresh model call.

  5. Finish

    When the objective is met, the model calls finish_task with a short summary.

finish_task

The agent must call finish_task to end cleanly. The summary is what you see as “Done - …” in the UI. If every model is blocked, you get an error path that lists free /model options instead of a fake success.

Limits

KnobDefaultEnv
Max iterations32VRITRA_AGENT_MAX_ITER
Per-model wall clock120sVRITRA_MODEL_TIMEOUT
Streaming narrationonVRITRA_AGENT_STREAM=0 to disable

Workspace boundary

All tool paths resolve under the folder you opened with vritraai [path]. Treat that folder as the sandbox. Do not open your home directory if you only want a single project touched.

Content quality

Hollow HTML/CSS/JS stubs (empty shells pretending to be “done”) are rejected. Ask for real structure and copy; the agent should rewrite instead of finishing with placeholders.

Narration & UI

  • Streaming events: Calling model… Create… Edit… $ command…
  • Diff / write previews with divider styling
  • Approve · always this session · deny

For tool names and arguments, see Tools. For approval modes, see Approvals.