Kward

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, Anthropic Claude Pro/Max subscription, OpenRouter, and experimental Copilot provider support.

Why use Kward?

Kward is designed for working with real projects, not isolated prompts.

Typical workflows include:

  • Understanding an unfamiliar codebase
  • Investigating bugs
  • Reviewing changes
  • Refactoring code
  • Automating repetitive development tasks
  • Building custom agent workflows through plugins

Examples:

kward "Explain this project"
kward "Review this diff"
kward "Find performance problems in this codebase"

Install

Install Kward from RubyGems:

gem install kward

Optionally install the starter pack after installation:

kward init

This downloads Kward's default prompts and base PRINCIPLES.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
kward help                     # show available commands and examples
/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
kward --working-directory ~/code/project "Explain this project"

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

What Kward can do

  • Keep a multi-turn coding conversation in your terminal.
  • Read, write, and edit workspace files with read-before-write guardrails.
  • Run local shell commands from the workspace.
  • 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, Anthropic OAuth, OpenRouter API keys, and Copilot/GitHub setup.
  • Troubleshooting: environment-specific install and runtime issues.

Feature guides:

  • Memory: opt-in core, soft, and session memory.
  • Personas: configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.
  • Extensibility: PRINCIPLES.md, workspace AGENTS.md, skills, prompt templates, and extension choices.
  • 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.

Development

Run tests:

bundle exec rake test

Build the YARD documentation site:

bundle exec rake docs:build

The generated site is written to _yardoc/. Pushes to main deploy that directory to GitHub Pages.

Generate the RDoc API documentation:

bundle exec rake rdoc