Skip to content

Home

Jump to bottom
Kansas edited this page Jul 23, 2026 · 1 revision

Welcome to the ctrlBolt wiki!

Ctrl-Bolt Wiki

Welcome to the Ctrl-Bolt wiki. Ctrl-Bolt (invoked as ctrlBolt in the terminal) is a reusable, numbered-prompt chain runner for AI coding CLIs. It turns a folder of numbered Markdown prompt files into an ordered, resumable agentic loop that can drive Codex, Claude Code, Gemini, Aider, Ollama, or any custom agent.

It is designed to replace ad-hoc, one-off shell scripts (such as run_ai_prompts.sh) with a single standardized runner that adds multi-provider support, per-project state, resume capability, logging, git checkpoints, test hooks, and graceful usage-limit exits.

Table of Contents

Overview

At its core, Ctrl-Bolt reads a directory of numbered .md prompt files, sorts them, and feeds each one in sequence to the AI coding CLI of your choice. Between steps it can run tests, create git checkpoints, and persist state so a long chain can be paused and resumed later. Because each project keeps its own independent state, multiple projects can be run and resumed separately.

Supported Providers

Ctrl-Bolt ships with adapters for several popular AI coding tools, each mapped to a sensible default command:

Provider Default command strategy
codex codex exec -
claude claude -p \"<prompt>\"
gemini gemini -p \"<prompt>\"
aider aider --yes-always --no-auto-commits --message \"<prompt>\"
ollama ollama run <model> with the prompt sent on stdin
custom Your own command template

The custom adapter is the universal escape hatch for any agent not covered by the built-in list.

Installation

Copy the script into a directory on your PATH and make it executable:

mkdir -p ~/.local/bin
cp ctrlBolt ~/.local/bin/ctrlBolt
chmod +x ~/.local/bin/ctrlBolt

# optional lowercase alias
ln -sf ~/.local/bin/ctrlBolt ~/.local/bin/ctrlbolt

Ensure ~/.local/bin is on your PATH:

echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc
source ~/.zshrc

Usage

The general pattern is to point Ctrl-Bolt at a prompt directory, a root directory, and a project directory, then select a provider.

Codex

ctrlBolt \
  --provider codex \
  --prompt-dir ~/path/to/<program>_prompt_kit \
  --root-dir ~/path/to/dir \
  --project-dir ~/path/to/dir \
  --danger

Resume an interrupted run:

ctrlBolt --resume --project-dir ~/path/to/dir

Claude Code

ctrlBolt \
  --provider claude \
  --prompt-dir ~/path/to/AI_prompt_kit \
  --root-dir ~/path/to/dir \
  --project-dir ~/path/to/dir/ \
  --danger

Note: --danger maps to Claude Code's bypass-permission mode.

Gemini CLI

ctrlBolt \
  --provider gemini \
  --prompt-dir ~/path/to/AI_prompt_kit \
  --root-dir ~/path/to/ \
  --project-dir ~/path/to/dir

Aider

ctrlBolt \
  --provider aider \
  --prompt-dir ~/path/to/AI_prompt_kit \
  --root-dir ~/path/to \
  --project-dir ~/path/to/tool

Ollama (local model)

Ollama on its own is usually best for advisory or review output rather than full file-editing agent work, but it can still run prompt chains and save logs.

ctrlBolt \
  --provider ollama \
  --model qwen2.5-coder:7b \
  --prompt-dir ~/path/to/AI_prompt_kit \
  --root-dir ~/path/to/ \
  --project-dir ~/path/to/dir/

Custom agent

ctrlBolt \
  --provider custom \
  --provider-cmd 'my-agent --project {project_dir} --prompt-file {prompt_file}' \
  --prompt-dir ~/path/to/my_prompt_kit \
  --root-dir ~/path/to/projects \
  --project-dir ~/path/to/projects/mytool

Available placeholders for the custom command template:

  • {prompt_file}
  • {prompt_text_file}
  • {project_dir}
  • {root_dir}
  • {log_file}
  • {state_dir}
  • {model}

Prompt Kit Format

A prompt kit is simply a directory of numbered Markdown files. Ctrl-Bolt auto-sorts them and runs them in numeric order:

00_MASTER_ARCHITECTURE.md
01_CORE.md
02_FEATURES.md
03_REFINER.md

Per-Project State

By default, state is stored under the root directory, one folder per project:

<root-dir>/.ctrlBolt/projects/<project-name>/
  state.json
  state.env
  logs/

For example:

~/bb/projects/.ctrlBolt/projects/macsvg/
~/bb/projects/.ctrlBolt/projects/deepMerge/
~/bb/projects/.ctrlBolt/projects/apdif/

Because each project has its own state, multiple projects can be paused and resumed independently.

Useful Flags

  • --start-at 03_REFINER.md — begin the chain at a specific prompt file
  • --run-tests — run tests between steps
  • --no-commit — skip git checkpoints
  • --continue-on-error — keep going if a step fails
  • --timeout 3600 — set a per-step timeout in seconds
  • --dry-run — show what would run without executing
  • --extra-arg VALUE — pass an additional argument through to the provider

Usage-Limit Behavior

If a provider's output contains quota, rate-limit, or usage-limit language, Ctrl-Bolt saves the current state and exits cleanly with exit code 75. You can resume later:

ctrlBolt --resume --project-dir ~/bb/projects/macsvg

Clone this wiki locally