ctxkit 1.6.1

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 (--grok), and finally extract the modified project files (--extract):

ctxkit -d src -x py -m 'Please add -q argument' --grok grok-code-fast --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!' --claude claude-3-5-haiku-latest

--gpt - ChatGPT (OpenAI) API

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

--grok - Grok (xAI) API

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

--ollama - Ollama API

ctxkit -m 'Hello!' --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 --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" --grok grok-code-fast --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).

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] [--claude MODEL | --gpt MODEL | --grok MODEL |
              --ollama MODEL] [--list API] [--temp NUM] [--topp NUM]
              [--maxtok NUM]

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:
  --claude MODEL       pass to the Claude API
  --gpt MODEL          pass to the ChatGPT API
  --grok MODEL         pass to the Grok API
  --ollama MODEL       pass to the Ollama API
  --list API           list available models for the API (i.e. "ollama")
  --temp NUM           set the model response temperature
  --topp NUM           set the model response top_p
  --maxtok NUM         set the model response max tokens

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