ctxkit 2.1.0

ctxkit is a command-line tool for creating AI prompts to modify code.

ctxkit

ctxkit is a command-line tool for creating AI prompts to modify code. It works as follows:

• construct an AI prompt containing files, directories, and URL content

• calls an API to generate the prompt response

• extract modified or newly-created files in-place

In the following example, the project's Python source code is included (-d src -x py), then a change request message (-m), then call the xAI API (--api grok), and finally extract the modified project files (--extract):

ctxkit -d src -x py -m 'Please add -q argument' --api grok grok-4-fast-reasoning --extract

Installation

To install ctxkit, enter the following commands in a terminal window:

macOS and Linux

python3 -m venv $HOME/venv --upgrade-deps
. $HOME/venv/bin/activate
pip install ctxkit

Windows

python3 -m venv %USERPROFILE%\venv --upgrade-deps
%USERPROFILE%\venv\Scripts\activate
pip install ctxkit

Calling APIs

ctxkit supports the following APIs:

claude - Claude (Anthropic) API

export ANTHROPIC_API_KEY=<key>
ctxkit -m 'Hello!' --api claude claude-3-5-haiku-latest

gemini - Gemini (Google) API

export GOOGLE_API_KEY=<key>
ctxkit -m 'Hello!' --api gemini gemini-2.0-flash-exp

gpt - ChatGPT (OpenAI) API

export OPENAI_API_KEY=<key>
ctxkit -m 'Hello!' --api gpt model-name

grok - Grok (xAI) API

export XAI_API_KEY=<key>
ctxkit -m 'Hello!' --api grok grok-3

ollama - Ollama API

ctxkit -m 'Hello!' --api ollama gpt-oss:20b

List Models

Use the --list argument to list an API's models. For example:

ctxkit --list claude

Prompt from stdin

You can call an API with a prompt from stdin by passing no prompt items:

echo 'Hello!' | ctxkit --api ollama gpt-oss:20b

Extract Response Files

When a prompt includes one or more files, the AI may respond with modified versions of the files. You can extract the modified files using the -e (or --extract) argument:

ctxkit -d src -x py -m "Add a -q argument to silence output" --api grok grok-4-fast-reasoning --extract

In this example, ctxkit passes a prompt with all of the project source and a change request, to which we expect the AI to respond with modified versions of some project files that satisfy the requested change. Magic!

Inline Instructions

The AI processes inline instructions within the included files. These are lines or comments that begin with ctxkit: followed by instructions. For example:

def calculate_total(items):
    # ctxkit: add a docstring
    return sum(total)

Files containing the inline instructions are modified per the instructions and the inline instructions removed. Note that only instructions prefixed with ctxkit: are processed - instructions intended for others (e.g. user:) are ignored.

Variables

You can specify one or more variable references in a message's text, a file path, a directory path, or a URL using the syntax, {{var}}. A variable's value is specified using the -v argument. For example:

ctxkit -v package ctxkit -m 'Write brief overview of the Python package, "{{package}}"'

Configuration Files

ctxkit JSON configuration files allow you to construct complex prompts in one or more JSON files.

Example: Write Unit Tests

To generate a prompt to write unit tests for a function or method in a module, create a configuration file similar to the following:

{
    "items": [
        {"message": "Write the unit test methods to cover the code in the {{scope}}."},
        {"file": "src/my_package/{{base}}.py"},
        {"file": "src/tests/test_{{base}}.py"}
    ]
}

In this example, the "scope" variable allows you to specify what you want to write unit tests for. The "base" variable specifies the base sub-module name. To generate the prompt, run ctxkit:

ctxkit -v base main -v scope "main function" -c unittest.json

This outputs:

<system>
...
</system>

Write the unit test methods to cover the code in the main function.

<src/my_package/main.py>
# main.py
</src/my_package/main.py>

<src/tests/test_main.py>
# test_main.py
</src/tests/test_main.py>

Copy Output

To copy the output of ctxkit and paste it into your favorite AI chat application, pipe ctxkit's output into the clipboard tool for your platform.

macOS

ctxkit -m 'Hello!' | pbcopy

Windows

ctxkit -m 'Hello!' | clip

Linux

ctxkit -m 'Hello!' | xsel -ib

Usage

Using the ctxkit command line application, you can add any number of ordered context items of the following types: configuration files (-c), messages (-m), file path or URL content (-i and -f), and directories (-d).

The CTXKIT_FLAGS environment variable is used to define default arguments, such as --api grok grok-4-fast-reasoning to set a default model. CTXKIT_FLAGS is prepended to the command-line arguments.

usage: ctxkit [-h] [-g] [-e] [-o PATH] [-b] [-c PATH] [-m TEXT] [-i PATH]
              [-t PATH] [-f PATH] [-d PATH] [-v VAR EXPR] [-s PATH] [-x EXT]
              [-l INT] [--api API MODEL] [--list API] [--temp NUM]
              [--topp NUM] [--maxtok NUM] [--noapi]

options:
  -h, --help           show this help message and exit
  -g, --config-help    display the JSON configuration file format

Output Options:
  -e, --extract        extract response files
  -o, --output PATH    output to the file path
  -b, --backup         backup output files with ".bak" extension

Prompt Items:
  -c, --config PATH    process the JSON configuration file path or URL
  -m, --message TEXT   add a prompt message
  -i, --include PATH   add the file path or URL text
  -t, --template PATH  add the file path or URL template text
  -f, --file PATH      add the file path or URL as a text file
  -d, --dir PATH       add a directory's text files
  -v, --var VAR EXPR   define a variable (reference with "{{var}}")
  -s, --system PATH    the system prompt file path or URL, "" for none

Directory Options:
  -x, --ext EXT        add a directory text file extension
  -l, --depth INT      the maximum directory depth, default is 0 (infinite)

API Calling:
  --api API MODEL      pass to an API provider (see "API Providers")
  --list API           list API provider models (see "API Providers")
  --temp NUM           set the model response temperature
  --topp NUM           set the model response top_p
  --maxtok NUM         set the model response max tokens
  --noapi              do not pass to an API provider

API Providers:
  claude - Claude (Anthropic) API
  gemini - Gemini (Google) API
  gpt    - ChatGPT (OpenAI) API
  grok   - Grok (xAI) API
  ollama - Ollama API

Examples:
  ctxkit --api ollama gpt-oss:20b -m "How do I count code lines?"
  ctxkit --api grok grok-4-fast-reasoning -f README.md -f main.py -f test_main.py -m "Add a -q argument" -e
  ctxkit --api claude claude-opus-4-1 -f README.md -d src -x py -i spec.txt -e
  ctxkit --list grok

Configuration File Format

The ctxkit -g argument outputs the JSON configuration file format defined using the Schema Markdown Language.

# The ctxkit configuration file format
struct CtxKitConfig

    # The list of prompt items
    CtxKitItem[len > 0] items


# A prompt item
union CtxKitItem

    # Config file path or URL
    string config

    # A prompt message
    string message

    # A long prompt message
    string[len > 0] long

    # File path or URL text
    string include

    # File path or URL template text
    string template

    # File path or URL as a text file
    string file

    # Add a directory's text files
    CtxKitDir dir

    # Set a variable (reference with "{{var}}")
    CtxKitVariable var


# A directory item
struct CtxKitDir

    # The directory file path or URL
    string path

    # The file extensions to include (e.g. ".py")
    string[] exts

    # The directory traversal depth (default is 0, infinite)
    optional int(>= 0) depth


# A variable definition item
struct CtxKitVariable

    # The variable's name
    string name

    # The variable's value
    string value

Development

This package is developed using python-build. It was started using python-template as follows:

template-specialize python-template/template/ ctxkit/ -k package ctxkit -k name 'Craig A. Hobbs' -k email '[e-mail]' -k github 'craigahobbs' -k noapi 1