Skip to content
Kward

Kward

Kward is a coding agent for your terminal. It can inspect and edit a project, run commands, research problems, and save your work in sessions you can resume later.

Use Kward from the terminal, its local browser interface, or a trusted JSON-RPC client. It works with ChatGPT/Codex and Claude subscriptions, hosted model APIs, GitHub Copilot, OpenRouter, and local servers such as Ollama, LM Studio, and llama.cpp.

Why Kward?

Software work rarely fits into one chat. A project can span days of research, implementation, debugging, review, and decisions worth keeping.

Kward treats that work as an ongoing workspace rather than a disposable conversation. You can resume earlier sessions, split work across tabs and Git worktrees, and keep project guidance close to the code. Optional permissions, command sandboxing, and workspace boundaries give you more control when a task needs it.

Start with a normal coding conversation. If your workflow grows, you can add memory, reusable prompts and skills, local plugins, lifecycle hooks, MCP servers, transports, or a custom RPC client.

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 sign in and start Kward:

kward login                    # sign in or save provider credentials
kward                          # start an interactive chat
kward help                     # show available commands and examples
kward hooks doctor             # inspect lifecycle hook setup
kward "Explain this project"   # run one prompt and exit
kward --working-directory ~/code/project "Explain this project"

From inside Kward, /login lets you choose API-key or subscription authentication across supported providers. /model then switches providers, refreshes model catalogs, or accepts a manual model/deployment ID. Direct OpenAI API credentials and ChatGPT/Codex OAuth can coexist.

See Model providers to choose a backend and Authentication for credential storage and login flows.

Common ways to use Kward

  • Explore an unfamiliar codebase and keep useful discoveries for later sessions.
  • Investigate a bug, make a focused change, and run the related tests.
  • Review a diff, inspect the surrounding code, and commit from the terminal UI.
  • Work on several tasks at once with tabs, branches, and linked Git worktrees.
  • Teach Kward your project conventions with AGENTS.md, skills, prompt templates, and optional memory.
  • Add trusted local behavior through plugins, lifecycle hooks, MCP servers, transports, or JSON-RPC integrations.

Documentation

New to Kward:

  • 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: multi-provider API keys, OpenAI/Anthropic subscription OAuth, Azure setup, and credential safety.
  • Model providers: compare providers and find their runtime IDs, model keys, environment variables, discovery behavior, and limitations.

Work safely:

  • Security and trust: local permissions, external data flow, trusted extensions, and safe work in unfamiliar repositories.
  • Permissions: opt-in tool approval, write scopes, policy rules, and current limits.
  • Command sandboxing: opt-in OS-enforced boundaries for model-requested shell commands.
  • Troubleshooting: environment-specific install and runtime issues.

Everyday workflows:

  • Sessions: resume, clone, fork, rewind, compact, and navigate saved work.
  • Interactive composer: use multiline input, completion, history, files, reasoning shortcuts, busy input, and images.
  • Tabs: keep several conversations open and run work in another tab.
  • Project files: browse, search, mention, open, and edit workspace files.
  • Integrated editor: open files from the shell or composer, edit in-place, and choose editor keybindings.
  • Git: review changes, use the diff viewer, stage files, and commit from the interactive TUI.
  • Shell: use /shell, the embedded Kward shell with aliases, completion, and per-tab state.
  • Memory: opt-in core, soft, and session memory.
  • Personas: configure Kward's tone and role by default, workspace, model, reasoning effort, time, and weekday.
  • Skills: add reusable instructions that load only for matching tasks.
  • Prompt templates: create reusable slash prompts and use the starter templates installed by kward init.
  • MCP servers: connect trusted local Model Context Protocol tool servers.
  • Pan mode: use the mobile-friendly browser interface on a trusted local network.
  • Local models: connect Ollama, LM Studio, or llama.cpp and use a minimal replacement prompt.

Extend and integrate:

  • Extensibility: choose between PRINCIPLES.md, workspace AGENTS.md, skills, prompt templates, and other extension points.
  • Plugins: trusted Ruby plugins for commands, footer UI, prompt context, transcript events, and RPC clients.
  • Lifecycle hooks: deterministic runtime hooks for policy, approvals, automation, and command-hook integrations.
  • RPC protocol: JSON-RPC backend mode for trusted local UI clients.
  • Releasing: release checklist for RubyGems publishing.

Reference guides:

  • Agent tools: overview of model-callable tools, token-saving behavior, and tool categories.
  • Workspace tools: local file, edit, and shell command tools.
  • Context budgeting: focused context gathering, budgeted reads, output compaction, and token-saving history.
  • 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.

Generated Ruby API:

  • API reference: generated Ruby API entry points, indexes, and supported 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