Kward

Kward is an extendable Ruby CLI coding agent. It can chat with you about a project, inspect and edit files, run confirmed shell commands, search the web, look up public source code, save local sessions, and load trusted Ruby plugins for custom workflows.

It currently supports the OpenAI/ChatGPT Codex backend, OpenRouter, and experimental Copilot provider support.

Install

Kward is being prepared for a RubyGems release. Once published, install it with:

gem install kward

Optionally install the starter pack after installation:

kward --install-starter-pack

This downloads Kward's default prompts and base AGENTS.md into your config directory. It is useful for a first setup, but safe to skip if you prefer to create your own instructions. Existing files are left untouched.

Then start Kward and sign in when needed:

kward                          # start an interactive chat
/login                         # from inside Kward: sign in or save provider credentials
kward login                    # from your shell: sign in or save provider credentials
kward "Explain this project"   # run one prompt and exit

See Authentication for more details about sign-in options and provider credentials.

Run from source

If you are working from a checkout:

bundle install
ruby lib/main.rb login                    # sign in or save provider credentials
ruby lib/main.rb                          # start an interactive chat
ruby lib/main.rb "Explain this project"   # run one prompt and exit

You can also use the executable directly after installing dependencies:

exe/kward

What Kward can do

• Keep a multi-turn coding conversation in your terminal.
• Read, write, and edit workspace files with confirmation before changes.
• Run shell commands after confirmation.
• Search the live web and inspect cached public GitHub repositories.
• Save, resume, clone, compact, and export sessions.
• Extend the Agent with trusted Ruby plugins for custom commands, footer UI, prompt context, and transcript-event observers.
• Use optional memory, personas, prompt templates, and skills.
• Serve an experimental JSON-RPC backend for UI clients.

Documentation

Start here:

• Getting started: first run, authentication choices, and basic commands.
• Usage: interactive chat, slash commands, sessions, tools, images, and Pan mode.
• Configuration: config files, providers, models, web search, logging, and color output.
• Authentication: OpenAI OAuth, OpenRouter API keys, and Copilot/GitHub setup.

Feature guides:

• Memory: opt-in core, soft, and session memory.
• Extensibility: AGENTS.md, personas, skills, and prompt templates.
• Plugins: trusted Ruby plugins for commands, footer UI, prompt context, transcript events, and RPC clients.
• Web search: live search providers and network behavior.
• Code search: package lookup, GitHub repository cache, and external source reading.

Advanced/reference:

• RPC protocol: experimental JSON-RPC backend mode for UI clients.
• Releasing: release checklist for RubyGems publishing.

Run tests

bundle exec rake test

Equivalent direct command:

ruby -Itest -e 'Dir["test/**/test_*.rb"].sort.each { |file| require_relative file }'

Generate API documentation

bundle exec rake rdoc
bundle exec yard doc