Kreator

Kreator is a Ruby 3.2+ headless agent runtime and CLI for running coding-agent style workflows from a terminal, script, or JSONL RPC client. It streams assistant output, can call local tools, persists conversations as append-only sessions, and supports project resources, prompt templates, skills, and local Ruby plugins.

kreator --provider openai --model gpt-4o-mini "Summarize this repo"

Requirements

Ruby 3.2 or newer.
Bundler for local development.
A provider API key:
- OPENAI_API_KEY for --provider openai
- ANTHROPIC_API_KEY for --provider anthropic

Optional provider base URLs can be overridden with OPENAI_BASE_URL and ANTHROPIC_BASE_URL.

Installation

Install dependencies for local development:

bundle install

Run the CLI from the checkout:

bundle exec ruby exe/kreator "Explain the project structure"

Build and install the gem locally:

gem build kreator.gemspec
gem install ./kreator-0.1.0.gem

After installing the gem, use the executable directly:

kreator "Summarize this repo"

When Kreator is published to RubyGems, it can be installed with:

gem install kreator

Configuration

Kreator defaults to the OpenAI provider and the gpt-4o-mini model.

Setting	Purpose	Default
`KREATOR_PROVIDER`	Default provider name, `openai` or `anthropic`.	`openai`
`KREATOR_MODEL`	Default model name.	`gpt-4o-mini`
`KREATOR_HOME`	Global resource home for prompts, skills, and plugins.	`~/.kreator`
`KREATOR_COMPACT_THRESHOLD`	Character threshold for automatic session compaction.	unset
`KREATOR_APPROVAL_POLICY`	Built-in tool approval policy: `auto`, `prompt`, or `deny`.	`auto`
`KREATOR_PLUGIN_TOOL_POLICY`	Plugin tool approval policy: `auto`, `prompt`, or `deny`.	`prompt`
`OPENAI_API_KEY`	API key for the OpenAI provider.	required for OpenAI
`OPENAI_BASE_URL`	OpenAI-compatible API base URL.	`https://api.openai.com/v1`
`ANTHROPIC_API_KEY`	API key for the Anthropic provider.	required for Anthropic
`ANTHROPIC_BASE_URL`	Anthropic API base URL.	`https://api.anthropic.com/v1`

Basic Usage

Run a prompt and stream the assistant response:

kreator "Find the main entry points in this codebase"

Choose a provider and model:

kreator --provider anthropic --model claude-3-7-sonnet-latest "Review the CLI design"

Disable local tools for a pure chat-style response:

kreator --no-tools "Explain what this gem does"

Limit the enabled tools:

kreator --tools read,bash "Inspect the tests and tell me how to run them"

Emit structured JSON instead of streaming plain text:

kreator --json --no-session "Return a short project summary"

Start interactive mode by running Kreator with no prompt in a TTY:

kreator

Interactive mode supports chat-style prompting plus slash commands such as /help, /new, /resume, /model, /session, /prompt, /plugins, /plugin, /compact, /fork, and /exit.

Command Reference

Usage: kreator [options] "prompt"
        --provider PROVIDER
        --model MODEL
        --no-tools
        --tools LIST
        --timeout SECONDS
        --allow-path PATH
        --deny-bash PATTERN
        --approval-policy POLICY
        --plugin-tool-policy POLICY
        --ask-permission
        --name NAME
        --no-session
        --session PATH_OR_ID
        --continue
        --session-dir PATH
        --list-sessions
        --search-sessions QUERY
        --label-session LABEL
        --export-session FORMAT
        --cleanup-empty-sessions
        --resource-home PATH
        --no-plugins
        --plugin NAME
        --prompt-template NAME
        --compact-threshold CHARS
        --json
        --rpc
    -h, --help

Providers

Kreator includes provider adapters for:

openai: OpenAI-compatible chat completions with streaming, tool calls, usage metadata, and non-streaming fallback.
anthropic: Anthropic Messages API with streaming, tool calls, usage metadata, and non-streaming fallback.

Provider responses are normalized into Kreator messages, tool calls, usage objects, and runtime events.

Built-In Tools

Tools are enabled by default. Use --no-tools to disable them or --tools to select a subset.

Tool	What it does
`read`	Reads a UTF-8 text file with optional line and byte truncation.
`write`	Writes complete UTF-8 text contents to a file and creates parent directories.
`edit`	Applies an exact text replacement and returns a unified diff.
`bash`	Runs a shell command in the current workspace with timeout and output truncation.

Useful safety options:

kreator --ask-permission "Update the README"
kreator --approval-policy prompt "Run the test suite"
kreator --approval-policy deny "Inspect files without making changes"
kreator --allow-path . --allow-path ../shared "Read files across both workspaces"
kreator --deny-bash "rm|git reset" "Work on this repo"
kreator --timeout 10 "Run a quick health check"

By default, file tools are restricted to the current working directory. --allow-path can be repeated to permit additional directories.

Sessions

Kreator stores conversations as append-only JSONL sessions under:

~/.kreator/sessions/--encoded-cwd--/<timestamp>_<uuid>.jsonl

Sessions preserve messages, model changes, labels, usage metadata, and compaction entries.

Common session commands:

kreator --continue "Keep working from the latest session"
kreator --session SESSION_ID "Resume this specific session"
kreator --list-sessions
kreator --search-sessions "release notes"
kreator --session SESSION_ID --label-session docs
kreator --session SESSION_ID --export-session markdown
kreator --cleanup-empty-sessions

Use --no-session for one-off runs that should not be persisted. Use --session-dir PATH to store sessions somewhere other than ~/.kreator/sessions.

Project Resources

Kreator automatically discovers resource files from the current directory and its ancestors:

AGENTS.md
.kreator/instructions.md
.kreator/prompts/*.md
.kreator/skills/*/SKILL.md
.kreator/plugins/*/plugin.json

It also loads global resources from ~/.kreator or the directory configured with --resource-home:

~/.kreator/prompts/*.md
~/.kreator/skills/*/SKILL.md
~/.kreator/plugins/*/plugin.json

Project and plugin instructions are added to the system prompt. Prompt templates and available skills are listed for the model. A skill's full SKILL.md content is loaded when a prompt invokes it with forms such as $rails, @rails, skill:rails, or use rails skill.

Apply a prompt template:

kreator --prompt-template review "Check this implementation"

If a template contains {{prompt}}, Kreator replaces that token with the user prompt. Otherwise, it appends the prompt after the template content.

Plugins

Plugins are local resource bundles. A plugin can provide instructions, prompt templates, skills, and Ruby-native tools.

Plugin layout:

my-plugin/
  plugin.json
  instructions.md
  prompts/
    review.md
  skills/
    rails/
      SKILL.md
  tools/
    echo.rb

Example plugin.json:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Example local plugin",
  "tools": [
    {
      "path": "tools/echo.rb",
      "class": "MyPlugin::Echo"
    }
  ]
}

Example plugin tool:

module MyPlugin
  class Echo < Kreator::PluginTool
    tool_name "echo"
    description "Echo input"
    schema(
      "type" => "object",
      "additionalProperties" => false,
      "required" => ["text"],
      "properties" => {
        "text" => { "type" => "string" }
      }
    )

    def call(args:, context:, signal:)
      Kreator::ToolResult.new(content: "echo: #{args.fetch('text')}")
    end
  end
end

Plugin tool names are exposed as plugin_name.tool_name, for example my-plugin.echo.

Plugin lifecycle commands:

kreator plugin list
kreator plugin validate PATH_OR_NAME
kreator plugin install PATH --name NAME
kreator plugin update NAME PATH
kreator plugin remove NAME

Plugin controls:

kreator --no-plugins "Ignore local plugins"
kreator --plugin reviewer --plugin rails "Only enable selected plugins"
kreator --plugin-tool-policy prompt "Ask before plugin tool calls"

Plugin Ruby code is loaded locally, so install plugins only from sources you trust. Plugin tool calls require approval by default.

JSON Output

--json emits one final JSON object and suppresses streaming text. Successful runs include:

ok
message
messages
tool_calls
usage
session

Errors are emitted as:

{
  "ok": false,
  "error": {
    "class": "ArgumentError",
    "message": "session not found: missing",
    "code": "runtime_error"
  }
}

JSONL RPC Mode

Use --rpc to run Kreator as a line-oriented JSON RPC process. Each input line is a JSON command. Each output line is a JSON response or event.

kreator --rpc

Example input:

{"id":"1","command":"get_state"}
{"id":"2","command":"prompt","prompt":"Summarize this project"}
{"id":"3","command":"get_messages"}

Responses use this shape:

{"type":"response","id":"1","ok":true,"state":{}}

Prompt execution also emits event lines:

{"type":"event","id":"2","event":{"type":"message_delta","delta":"..."}}

Supported RPC commands:

prompt
abort
get_state
get_messages
search_sessions
label_session
export_session
cleanup_sessions
get_resources
plugin_list
plugin_validate
plugin_install
plugin_update
plugin_remove
list_branches
fork_session
new_session
set_model

Development

Run the test suite:

bundle exec rake test

Run RuboCop:

bundle exec rubocop

The gem entry point is exe/kreator, and the main implementation lives under lib/kreator.

Built By

Kreator is built by the Kreator Contributors.

License

Kreator is available under the MIT License.