Runbook: A CLI Detection Tool for AI Agent Development Environments — Stop Guessing, Start Coding Efficiently

Why Do AI Agents Keep Getting Your Development Environment Wrong?

When using AI coding assistants like Claude Code, have you encountered these frustrating scenarios:

• Your project clearly uses pnpm for dependency management, but the Agent stubbornly runs npm install to download packages
• You have Git Bash or another Unix Shell installed, but the Agent repeatedly executes incorrect commands in PowerShell
• Your local repository already has testing tools configured, but the Agent has no idea they exist

All these problems point to the same root cause: Agents lack the ability to detect and understand the current development environment before they start working. They don't know what tools you have installed or what workflows you prefer, so they can only "guess" — and the cost of guessing wrong is repeated trial-and-error, wasted tokens, and lost time.

This "guessing" behavior has deep technical roots. During training, LLMs learn statistically "most common" patterns — npm's historical usage frequency in the JavaScript ecosystem far exceeds pnpm or bun, so models default to npm when lacking explicit context. This phenomenon is known in the AI field as Training Distribution Bias. The more fundamental issue is that LLMs are essentially stateless text prediction systems with no native ability to "perceive" the current runtime environment — each conversation starts from scratch, unable to proactively probe the file system, environment variables, or installed software. This is why even the most advanced models like Claude and GPT-4, without tool assistance, can only rely on contextual clues or outright guessing to determine the development environment.

The open-source project Runbook was created specifically to solve this pain point. It isolates CLI environment detection as a critical step, allowing Agents to "see clearly" their working environment before taking action.

What Is Runbook: A Translation Layer Between Agent and Local Environment

Runbook is a CLI tool written in Rust. Its core function is to scan the CLI tools installed in the current development environment and provide the detection results to AI Agents, helping them make more accurate decisions.

Simply put, it acts as a "translation layer" between the Agent and your local environment — the Agent no longer needs to blindly guess whether you're using npm or pnpm, bash or zsh, because Runbook tells it directly.

Choosing Rust as the development language was no accident. Rust is experiencing explosive growth in the CLI tool space — ripgrep, fd, bat, and other modern CLI tools are all flagship Rust projects. For tools like Runbook that need to be frequently invoked by Agents, Rust's advantages are particularly pronounced: compilation into a single static binary with no runtime dependencies, instant startup without JVM or Node.js cold-start overhead, and reliable file system scanning enabled by memory safety guarantees. Installation via cargo install also integrates seamlessly with the Rust ecosystem — one command handles both compilation and installation.

Installation

The installation process is straightforward, with two options:

1. Let the Agent install it: Give the project link to Claude Code and let it download and install based on the link
2. Manual installation:

cargo install agent-runbook
npx skills add  # Add as an Agent skill

Three Core Commands Explained

Runbook currently integrates three core commands, covering the complete workflow from environment scanning to preference setting.

scan: One-Click Environment Scanning

The scan command scans the current system environment, detecting which Agent-usable CLI tools are installed and which are not. The scan results clearly list the installed tools, so the Agent knows "what weapons are available at hand."

category: Search Tools by Category

The category command supports searching tools by functional category, programming language, risk level, and other dimensions. For example, you can view the installation status of all CI/CD-related tools, all linting tools, or all MCP-related tools.

Once the Agent understands tool availability, it may:

• Suggest that a certain tool is more appropriate for the current scenario
• Recommend installing a missing but valuable tool
• Automatically select the best installed tool to complete a task

Worth noting is that the MCP (Model Context Protocol) included in the categories is an open protocol launched by Anthropic in 2024, designed to standardize how LLMs connect with external tools and data sources — similar to a "USB port" for AI. Any tool that implements the MCP protocol can be directly invoked by Agents supporting it. The npx skills add installation command represents another integration paradigm: packaging specific capabilities as reusable Agent Skill modules that load on demand. Runbook supports both mainstream integration approaches, reflecting broad compatibility with the current Agent ecosystem.

prefer: Set Tool Usage Preferences

The prefer command allows you to set CLI tool usage preferences at two levels: global preferences and project-level preferences. Once set, the Agent references these preferences when executing commands, using the tools you actually want to use.

For example, you can set a global preference to use pnpm instead of npm, or prefer bun as the runtime in a specific project. After reading these preferences, the Agent will no longer make presumptuous choices.