Programmatic Execution
Relevant source files
The following files were used as context for generating this wiki page:
Programmatic Execution in QQcode refers to the non-interactive mode of operating the AI coding assistant. This mode allows users to trigger the agent via CLI flags or piped input, making it suitable for scripting, automation, and integration into CI/CD pipelines. Unlike the interactive TUI, programmatic execution processes a single prompt and exits after reaching a conclusion or a defined limit.
Sources: vibe/cli/entrypoint.py:177-183, README.md:124-129
Core Workflow and Entry Point
Programmatic execution is triggered through the vibe.cli.entrypoint module. When the --prompt flag is detected or input is piped via stdin, the system bypasses the Textual-based TUI and invokes run_programmatic. This function orchestrates the loading of configurations, session history, and the execution loop.
Command Execution Flow
The following diagram illustrates the transition from CLI arguments to the programmatic execution engine.
The logic ensures that even in programmatic mode, the agent has access to full project context and configured tools.
Sources: vibe/cli/entrypoint.py:276-310, CLAUDE.md:33-40
Configuration and Execution Modes
Programmatic execution supports three distinct execution modes that define how the agent interacts with the filesystem and handles tool approvals.
Execution Modes Table
| Mode | Description | Tool Permissions |
|---|---|---|
plan | Default mode. Allows exploration and analysis but blocks modifications. | Read-only (e.g., read_file, grep) |
interactive | Requires manual approval for tool execution via stdin. | As configured in config.toml |
auto-approve | Automatically executes all tools without prompting the user. | Full execution |
Sources: vibe/cli/entrypoint.py:48-58, vibe/core/prompts/plan_mode.md:1-15
Programmatic CLI Arguments
| Parameter | Flag | Description | Default |
|---|---|---|---|
| Prompt | -p, --prompt | The instruction to send to the agent. | None |
| Mode | --mode | Selection of plan, interactive, or auto-approve. | plan |
| Max Turns | --max-turns | Maximum number of assistant turns before exiting. | Model default |
| Max Price | --max-price | Budget limit in USD for the session. | None |
| Output Format | --output | Format of results: text, json, streaming, or vscode. | text |
Sources: vibe/cli/entrypoint.py:34-78
System Constraints and Safety
Programmatic execution implements several safety layers, particularly when running in restricted modes or under budget constraints.
Plan Mode Restrictions
When the --mode is set to plan, the system injects specific instructions that restrict the bash tool to read-only commands and blocks all write operations (write_file, edit).
Resource Limits
Programmatic execution is subject to limits to prevent runaway costs or infinite loops:
- Turn Limits: Controlled by
--max-turnsto prevent infinite tool-call loops. - Cost Guardrails: Controlled by
--max-price, which monitors token usage againstModelConfigpricing. - Timeout: The
ProjectContextConfigenforces atimeout_seconds(default 2.0s) for context gathering (e.g., git status, directory listing) to ensure programmatic scripts remain responsive.
Sources: vibe/cli/entrypoint.py:60-70, vibe/core/config.py:117-125, vibe/core/system_prompt.py:112-115
Context Integration
The programmatic runner utilizes the ProjectContextProvider to supply the AI with a snapshot of the current repository state before processing the prompt. This includes:
- Directory Structure: Up to 1000 items (default) with a maximum depth of 3 levels.
- Git Status: Branch information and recent commit history (default 5 commits).
- Project Docs: Contents of files like
AGENTS.mdor.qqcode.mdif present.
Sources: vibe/core/system_prompt.py:42-100, vibe/core/config.py:73
Programmatic execution provides a robust way to leverage QQcode's agentic capabilities within automated workflows, ensuring that the same context-aware intelligence used in interactive sessions is available for batch processing and scripting tasks.