Skip to content
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:

  • Sessions: resume, clone, fork, rewind, compact, and navigate saved work.
  • Memory: opt-in core, soft, and session memory.
  • Personas: configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.

Advanced:

  • 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.
  • RPC protocol: experimental JSON-RPC backend mode for UI clients.
  • Releasing: release checklist for RubyGems publishing.
  • Agent tools: overview of model-callable tools, token-saving behavior, and tool categories.
  • Workspace tools: local file, edit, and shell command tools.
  • Web search: live search providers and network behavior for the web search agent tool.
  • Code search: package lookup, GitHub repository cache, and external source reading for the code search agent tool.
  • Context tools: skills, compacted output retrieval, and structured clarification questions.

API reference:

  • API reference: generated Ruby API entry points, indexes, and public API expectations.

Development

Run tests:

bundle exec rake test

Preview the built YARD documentation site locally with automatic rebuilds:

bundle exec rake docs:serve

The preview builds _yardoc/, serves it with WEBrick using Cache-Control: no-store, and rebuilds in a fresh process when documentation sources, library code, or templates change. Generated HTML, images, CSS, and JavaScript match the published site. Open http://localhost:8808/ and refresh your browser after rebuilds. Use PORT=4000 bundle exec rake docs:serve to choose another port.

Build the static YARD documentation site for publishing:

bundle exec rake docs:build

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

Check generated documentation links, images, and scripts:

bundle exec rake docs:check

External link checks are disabled by default for stable local runs. Enable them with DOCS_CHECK_EXTERNAL=1 bundle exec rake docs:check.

Generate the RDoc API documentation:

bundle exec rake rdoc