AIPACK

KEY CONCEPT

Single Runtime, One Markdown, one agent, multiple stages, built-in concurrency

The main aipack concept is to minimize the friction of creating and running an agent while providing maximum control over how those agents run and maximizing iteration speed to mature them quickly.

Stage Language Description
# Before All Lua Reshape/generate inputs and add command global data to scope (the "map" of the map/reduce capability).
# Data Lua Gather additional data per input and return it for the next stages.
# System Handlebars Customize the system prompt with the input, data, and before_all data.
# Instruction Handlebars Customize the user instruction prompt with the input, data, and before_all data.
# Assistant Handlebars Optional for special customizations, such as the "Jedi Mind Trick." Uses input, data, before_all.
# Output Lua Processes the ai_response from the LLM. Otherwise, ai_response.content will be output to the terminal.
# After All Lua Called with inputs and outputs for post-processing after all inputs are completed.

Notes:

  • Stage names are case insensitive.
  • # Instruction is aliased to # User and # Inst
  • # Assistant is aliased to # Model, # Mind Trick or # Jedi Trick
# Run the ./first-agent.aip on the README.md file
aip run ./my-agents/first-agent.aip -f "./README.md"

./my-agents/my-first-agent.aip

# Data

```lua
-- `aip run -f src/**/*.rs`
-- NOTE: Each file will be an input, so it can run concurrently (as defined by input_concurrency options)
-- It has access to `input` and `before_all` and can fetch more data, returning it for the next stage.
-- Input originates from the command line (when using -f, this will be a FileInfo object).

local file_record = aip.file.load(input.path)
return {
    file_content = file_record.content
}
```

# Instruction

This is a Handlebars section where we can include the data generated above. For example:

Here is the content of the file `` to proofread:

```

```

- Correct the English in the content above.
- Do not modify it if it is grammatically correct.

# Output

```lua
-- This section allows processing of `ai_response`.
-- It has access to `input`, `data`, `before_all`, and `ai_response`.

-- Example: remove an optional leading markdown block if present.
local content = aip.md.outer_block_content_or_raw(ai_response.content)
-- Example: ensure single trailing newline for code output.
content = aip.text.ensure_single_ending_newline(content)
-- More processing....

-- Save the processed content back to the original file path.
-- `input.path` contains the path derived from the `-f` flag.
aip.file.save(input.path, content)

-- This string will be printed in the terminal if returned.
return "File saved: " .. input.path

```

More Details

aip command line doc

Here is the overall command

Command Agent runner to accelerate production coding with genai.

Usage: aip <COMMAND>

Commands:
  init        Initialize the workspace `.aipack/` and the base `~/.aipack-base/` aipack directories
  init-base   Init the ~/.aipack-base only with force update
  run         Executes the AIPack agent using `aip run demo@craft/code`, or an agent file `aip run path/to/agent.aip`.
              
              Example usage:
              ```sh
              # Run the demo@craft/code AIP agent
              aip run demo@craft/code
              
              # Run the demo@proof main.aip agent and provide a file as input
              aip run demo@proof -f ./README.md
              
              # Run a direct agent file from the local directory
              aip run some/agent.aip
              ```
  list        Create a new agent from a built-in template Disabled for now List the available aipacks `aip run list` or `aip run list demo@`
  pack        Pack a directory into a .aipack file
  install     Install an aipack file
  check-keys  Check available API keys in the environment
  self        Manage the aip CLI itself
  help        Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

aip run ... documentation

Executes the AIPack agent using aip run demo@craft/code, or an agent file aip run path/to/agent.aip.

Example usage:

# Run a direct agent file from the local directory
aip run some/agent.aip

# Gives two inputs
aip run some/agent.aip -i "input 1" -i "input 2"

# Use -f to give file or globs (each matched file will be a input)
aip run some/agent.aip -f "src/**/*.js"

# Run the demo@craft/code AIP agent
aip run demo@craft/code

# Run the demo@proof main.aip agent and provide a single file as input
aip run demo@proof -f ./README.md

Usage: aip run [OPTIONS] <CMD_AGENT_NAME>

Arguments: <CMD_AGENT_NAME> The name of the agent, which can be: - A AIP pack reference: aip run demo@proof - Or a direct file: aip run path/to/agent.aip

Options: -i, --input <ON_INPUTS> Optional input, allowing multiple input NOTE: CANNOT be combined with -f/--on-files -f, --on-files <ON_FILES> Optional file parameter, allowing multiple files NOTE: CANNOT be combined with -i/--input -w, --watch Optional watch flag -v, --verbose Verbose mode -o, --open Attempt to open the agent file (for now use VSCode code command) --dry <DRY_MODE> Dry mode, takes either 'req' or 'res' [possible values: req, res] -s, --single-shot Single Shot execution (e.g., non-interactive). (Was the --ni or --non-interactive in v0.6.x) -h, --help Print help

Tips

aipack is built on top of the genai crate and therefore supports all major AI Providers and Models (OpenAI, Anthropic, Gemini, Ollama, Groq, Cohere).

You can customize the model and concurrency in .aip/config.toml.

New .aip/ file structure with the .aip file extension. See .aip/ folder structure.

TIP 1: In VSCode or your editor, map the *.aip extension to markdown to benefit from markdown highlighting. aipack agent files are standard Markdown files.

TIP 2: Make sure to commit your changes before running this command so that overwritten files can be easily reverted.

P.S. If possible, please refrain from publishing aipack-custom type crates on crates.io, as this might be more confusing than helpful. However, feel free to fork and code as you wish.

API Keys

aipack uses the genai crate; therefore, the simplest way to provide the API keys for each provider is via environment variables in the terminal when running aipack.

Here are the names of the environment variables used:

OPENAI_API_KEY
ANTHROPIC_API_KEY
GEMINI_API_KEY
FIREWORKS_API_KEY
TOGETHER_API_KEY
XAI_API_KEY
DEEPSEEK_API_KEY
GROQ_API_KEY
COHERE_API_KEY

On macOS, this CLI uses the Mac keychain to store the key if it is not available in the environment variable. This feature will be extended to other operating systems as it becomes more robust.

Complete Stages Description

Here is a full description of the complete flow:

Usage

Example: aip run proof-rs-comments -f "./src/main.rs"

(You can also use any glob pattern, like -f "./src/**/*.rs")

aip command arguments

# Creates/updates the .aip/ settings folder (not strictly required, automatically runs on "run")
aip init

## -- Running a Pre-Installed Pack

# Executes the pre-installed `proof` AI Pack from the `core` namespace (~/.aipack-base/pack/installed/core/)
# on any file matching `src/**/*.rs` (these files become 'inputs').
aip run core@proof-rs -f "src/**/*.rs"

# Verbose mode prints details like the prompt sent, the AI response, and # Output return values to the console.
aip run core@proof-rs -f "src/**/*.rs" --verbose

# Performs a dry run up to the request stage. Use with -v to print the rendered instruction.
# Does not call the AI or run the # Output stage.
aip run core@proof-rs -f "src/**/*.rs" -v --dry req

# Performs a dry run including the AI call. Use with -v to print the rendered instruction and AI response.
# Does not run the # Output stage.
aip run core@proof-rs -f "src/**/*.rs" -v --dry res

## -- Running the ask-aipack

# Creates a prompt file for interactive editing (press 'r' in the terminal to re-run).
aip run core@ask-aipack

## -- Running your own agent
aip run path/to/my-agent.aip

# Happy coding!

aipack folder structure

(Updated in version 0.7.x - migration handled automatically)

Example of a Command Agent File

See the example agent file within this README, or check installed agents like .aipack-base/pack/installed/core/proof-rs-comments/agent.aip.

Config

On first run (aip run, aip init, etc.), .aipack/config.toml and ~/.aipack-base/config.toml files will be created if they don't exist.

Workspace Config (.aipack/config.toml) Example:

# Default options for agents run within this workspace.
# Can be overridden by agent-specific meta or `aip.flow` functions.
[default_options]
# Required model identifier (any model supported by the Rust genai crate).
model = "gpt-4o-mini"

# Optional concurrency setting for processing inputs in parallel. Defaults to 1.
# Increasing this can speed up processing, especially with remote AI services.
input_concurrency = 4

# Aliases for model names
[model_aliases]
# main = "gpt-4o"
# mini = "gpt-4o-mini"
# fast = "gpt-3.5-turbo"

Base Config (~/.aipack-base/config.toml) Example:

# Base configuration affecting all workspaces unless overridden locally.
[default_options]
# Default model if not set in workspace or agent.
# model = "gpt-4o-mini"

# Where to store/retrieve API keys (e.g., "keyring", "env", "config")
# api_key_source = "keyring"

# Optional API keys can be stored directly here (less secure)
#[api_keys]
#OPENAI_API_KEY = "sk-..."
#ANTHROPIC_API_KEY = "..."