kward: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository.

This is a living document. If significant changes to the codebase, architecture, commands, workflows, or project conventions occur, update this file so future agents start with accurate guidance.

Project overview

Kward is an extendable Ruby CLI coding agent. It supports interactive and one-shot chat, local workspace tools, configurable prompts/skills, image attachments, web search, OpenAI OAuth/API-key authentication, session persistence, and a JSON-RPC backend for UI clients.

Working style

• Make the smallest correct change for the request.
• Inspect relevant files before editing, and preserve existing style and naming.
• Prefer straightforward Ruby from the standard library unless an existing dependency is already used.
• Internal requires should target canonical implementations under domain folders. Keep the documented public plugin_registry.rb entrypoint.
• Keep user-facing behavior consistent with existing docs and tests.
• Do not introduce broad rewrites, formatting-only churn, or unrelated cleanup.
• Do not split large orchestration files such as RPC::SessionManager or Model::Client just because they are large; extract only when a behavior change exposes a clear, tested ownership boundary.
• Be careful with auth tokens, API keys, config files, session data, user prompts, and workspace file contents. Do not log secrets.

Important paths

• lib/main.rb - executable entrypoint.
• lib/kward/cli.rb - command-line flow and interactive chat orchestration.
• lib/kward/prompt_interface.rb and lib/kward/prompt_interface/ - terminal UI state, rendering, input, and built-in editor mechanics.
• lib/kward/sessions/store.rb - authoritative JSONL session persistence and conversation reconstruction.
• lib/kward/sessions/catalog.rb - rebuildable, fingerprint-validated session-list summary cache; JSONL sessions remain authoritative.
• lib/kward/tabs/driver.rb - session and plugin tab-driver boundary used by interactive tabs.
• lib/kward/plugins/registry.rb, lib/kward/plugins/actions.rb, lib/kward/plugins/host.rb, lib/kward/plugins/http_server.rb, lib/kward/plugins/codex_responses.rb, lib/kward/plugins/resources.rb, lib/kward/plugins/chat_runtime.rb, and lib/kward/tools/plugin_tool.rb - trusted plugin registration, typed command/action/startup-option contracts, identified-plugin host services, managed loopback HTTP and Codex Responses access, owned task/cleanup lifecycles, frontend-neutral plugin-chat execution, and model-callable plugin-tool adaptation.
• examples/plugins/openrouter_proxy/ - example local OpenRouter Chat Completions proxy backed by Kward's normal Codex provider client, plus deterministic local fake embeddings.
• lib/kward/workspace/git_worktree_manager.rb - Git worktree discovery, creation, validation, and removal mechanics.
• lib/kward/tools/workspace_targets.rb - host-scoped workspace-role routing for model tools in linked worktree tabs.
• lib/kward/cli/worktrees.rb - interactive session-tab worktree binding and workspace re-rooting orchestration.
• lib/kward/shell/kwsh.rb, lib/kward/shell/kwshrc.rb, and lib/kward/shell/persistent_session.rb - embedded-shell command routing, declarative rc parsing, state, protocol, and PTY lifecycle.
• lib/kward/pty/detached_run.rb - shared lifecycle for commands detached from terminal ownership while remaining owned by a tab.
• lib/kward/shell/prompt.rb and lib/kward/shell/prompt_session.rb - transient shell-agent prompt context and scoped actions.
• lib/kward/agent.rb - agent loop and tool execution flow.
• lib/kward/model/ - model provider HTTP client and stream parsing behavior.
• lib/kward/auth/ - OAuth providers and auth credential file helpers.
• lib/kward/tools/registry.rb - tool dispatch and schema exposure.
• lib/kward/tools/ - individual tool implementations, one file per tool.
• lib/kward/mcp/ - local MCP client transports and configured server clients.
• lib/kward/transport.rb and lib/kward/transport/ - frontend-neutral transport contracts, host, session gateway, persistent state, lifecycle manager, and foreground runtime.
• lib/kward/transcripts/ - shared Markdown, HTML, and safe-path transcript export mechanics.
• lib/kward/cli/transports.rb - transport listing, status, and foreground-run commands.
• lib/kward/rpc/ - JSON-RPC backend.
• lib/kward/prompts.rb - system prompt and skill catalog prompt assembly.
• lib/kward/config_files.rb - config path handling.
• lib/kward/skills/ - Agent Skills discovery, parsing, validation, activation reads, and saved-session skill capture.
• test/ - Minitest coverage.
• doc/ - user documentation and generated docs source pages.
• doc/api.md - curated API reference overview used as the API docs landing page.
• doc/platform-support.md - supported operating systems, terminals, and sandbox backends.
• CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md - contribution workflow and project trust policies.
• templates/default/kward_navigation.rb - shared generated-docs navigation data for guide/API dropdowns.
• templates/default/layout/ - YARD layout templates for normal generated docs pages.
• templates/default/fulldoc/ - YARD templates for generated full-list pages such as class, method, and file indexes.