@relay-harness/coding-agent 0.0.0-stage → 1.0.2

package/docs/shell-aliases.md

@@ -0,0 +1,93 @@
+# Configure shell commands
+
+Relay starts a separate non-interactive shell process for each Bash command. Non-interactive Bash does not expand aliases by default and usually does not load the same startup files as an interactive terminal.
+
+Use `shellPath` to choose the Bash executable and `shellCommandPrefix` to run setup before each command.
+
+## Understand which shell Relay uses
+
+| Command source | Shell |
+|---|---|
+| Model calls the built-in `bash` tool | Relay's resolved Bash executable |
+| You enter `!command` or `!!command` | The same resolved Bash executable |
+| Model calls the optional `powershell` tool | PowerShell 7 (`pwsh.exe`) or Windows PowerShell |
+| An extension provides or replaces a shell tool | The operations implemented by that extension |
+
+Relay normally invokes Bash with `bash -c`. On Unix systems, it uses `/bin/bash`, then `bash` on `PATH`, and finally `sh` when Bash is unavailable. Native Windows first checks the configured path, then Git Bash, then `bash.exe` on `PATH`.
+
+## Choose a Bash executable
+
+Set `shellPath` in `~/.relay/agent/settings.json` when Relay should use a specific executable:
+
+```json
+{
+  "shellPath": "~/.local/bin/bash"
+}
+```
+
+On Windows, use forward slashes or escape backslashes:
+
+```json
+{
+  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
+}
+```
+
+Run `/reload` after changing the setting. See [Run Relay on Windows](windows.md) for the native Windows defaults.
+
+## Run setup before every Bash command
+
+Set `shellCommandPrefix` to prepend shell setup to both the built-in `bash` tool and user-entered `!` or `!!` commands:
+
+```json
+{
+  "shellCommandPrefix": "export CI=1"
+}
+```
+
+Relay joins the prefix and requested command with a newline. The prefix runs again for every command, so keep it fast and free of interactive prompts.
+
+## Enable Bash aliases
+
+Store aliases needed by Relay in a Bash-compatible file instead of parsing an entire interactive shell configuration.
+
+Create `~/.bash_aliases`:
+
+```bash
+alias ll='ls -la'
+alias gs='git status --short'
+```
+
+Then configure Relay to enable alias expansion and load the file:
+
+```json
+{
+  "shellCommandPrefix": "shopt -s expand_aliases\nsource ~/.bash_aliases"
+}
+```
+
+Run `/reload`, then verify the alias through Relay:
+
+```text
+!ll
+```
+
+The command should produce the same listing as `ls -la`.
+
+Aliases must use Bash-compatible syntax. Do not source an arbitrary `.zshrc` into Bash because zsh options, functions, and plugins may not parse or behave correctly there.
+
+## Troubleshooting
+
+### The prefix works for `!` but not for an extension tool
+
+`shellCommandPrefix` configures Relay's built-in Bash execution. An extension that replaces the `bash` tool or provides its own shell operations controls its own setup. Check that extension's documentation.
+
+### `shopt` is not found
+
+Relay has fallen back to `sh` or `shellPath` points to a non-Bash shell. Install Bash or set `shellPath` to a Bash executable before using Bash-specific setup such as `shopt`.
+
+### A setup command waits for input
+
+Remove interactive commands from `shellCommandPrefix`. The prefix runs in a non-interactive process before every Bash command.
+
+For the complete setting definitions, see [Shell settings](settings.md#shell).

package/docs/skills.md

@@ -0,0 +1,93 @@
+# Skills
+
+Skills give Relay specialized instructions and supporting files for a particular kind of work. Relay advertises each available skill by name and description, then loads its full instructions only when the task calls for them.
+
+Use a skill when a workflow needs more context than a prompt template but does not need a new executable integration point. Skills can bundle scripts, references, and assets alongside their instructions.
+
+Relay implements the [Agent Skills specification](https://agentskills.io/specification). Most invalid fields produce warnings rather than stopping startup.
+
+## Create a skill
+
+A skill is a directory containing `SKILL.md`:
+
+```text
+pdf-tools/
+├── SKILL.md
+├── scripts/
+│   └── extract.sh
+├── references/
+│   └── formats.md
+└── assets/
+    └── template.json
+```
+
+Start `SKILL.md` with frontmatter followed by direct instructions:
+
+```markdown
+---
+name: pdf-tools
+description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
+---
+
+# PDF tools
+
+Read `references/formats.md` before converting a document. Run scripts relative to this skill directory.
+```
+
+The description determines when the model considers loading the skill. State both what the skill does and when it applies. Avoid descriptions such as “Helps with PDFs,” which do not provide enough routing information.
+
+Use relative paths from the skill directory when referring to bundled files. Relay tells the model where the skill lives so it can resolve those paths.
+
+## Understand how skills load
+
+At startup, Relay scans configured skill locations and adds each skill’s name, description, and path to the system prompt. It does not add the full instructions.
+
+When a task matches, the model reads `SKILL.md` and follows its instructions. This keeps detailed guidance out of context until it is needed. A model might fail to load a relevant skill, so use `/skill:name` when you need to force it.
+
+Arguments after `/skill:name` are appended to the loaded instructions as a user request:
+
+```text
+/skill:pdf-tools extract report.pdf
+```
+
+Set `disable-model-invocation: true` in frontmatter when a skill should be available only through its explicit command. The `enableSkillCommands` [setting](settings.md) controls whether skill commands appear in interactive command discovery; manually entered `/skill:name` commands still work.
+
+<a id="choose-where-it-loads"></a>
+
+## Add it to Relay
+
+Place the skill in your user or project skills directory. Directories containing `SKILL.md` are discovered recursively.
+
+Relay also supports the Agent Skills locations `~/.agents/skills/` and `.agents/skills/`. Project `.agents/skills/` directories are discovered from the working directory through its ancestors, stopping at the repository root when one exists.
+
+Relay accepts some standalone Markdown skills, but a directory containing `SKILL.md` is the portable form and should be preferred. See [Settings](settings.md#resources) and [Relay Packages](packages.md) for additional locations.
+
+Project skills can instruct the model to run scripts or modify files. Review unfamiliar skills and their supporting files before granting project trust.
+
+## Write portable frontmatter
+
+The Agent Skills specification defines these fields:
+
+| Field | Purpose |
+|---|---|
+| `name` | Command and display name |
+| `description` | Routing description shown to the model |
+| `license` | License name or bundled license file |
+| `compatibility` | Environment requirements |
+| `metadata` | Additional key-value metadata |
+| `allowed-tools` | Experimental pre-approved tool list |
+| `disable-model-invocation` | Hide the skill from automatic model selection |
+
+Names use lowercase letters, numbers, and hyphens, with no leading, trailing, or consecutive hyphens. They can contain at most 64 characters; descriptions can contain at most 1024.
+
+Relay neither requires nor warns when the declared name differs from the parent directory. Other Agent Skills implementations may enforce that requirement, so matching names remain the portable choice.
+
+Malformed `SKILL.md` files and declared skills without descriptions are not loaded. Name collisions keep the first discovered skill and produce a warning.
+
+## Validate and share a skill
+
+Run Relay from a location where the skill is discoverable, then inspect the startup diagnostics and `/skill:name` command. Run `/reload` after editing a skill during an active session.
+
+Use a [Relay package](packages.md) to distribute one or more skills through npm or git. Keep environment setup inside the skill and declare any required runtime dependencies in the package.
+
+For examples, see the [Anthropic skills collection](https://github.com/anthropics/skills) and [Relay skills collection](https://github.com/badlogic/pi-skills).

package/docs/slash-commands.md

@@ -0,0 +1,61 @@
+# Slash commands
+
+Type `/` in Relay's terminal editor to search the commands available in the current session. This page lists the built-in commands in the current Relay release.
+
+Extensions, prompt templates, and skills can add commands. The command menu in Relay is therefore the exact reference for the resources loaded in your session.
+
+## Models and settings
+
+| Command | Description |
+|---|---|
+| `/settings` | Open settings |
+| `/model [provider/model]` | Select a model |
+| `/thinking [level]` | Set the thinking level |
+| `/scoped-models` | Configure the models used by interactive cycling |
+| `/login [provider]` | Add provider authentication |
+| `/logout` | Remove provider authentication |
+| `/llama` | Manage models on the configured llama.cpp router |
+
+## Sessions and context
+
+| Command | Description |
+|---|---|
+| `/new` | Start a new session |
+| `/resume` | Switch to another saved session |
+| `/name [name]` | Set the session display name, or show the current name when omitted |
+| `/session` | Show current session information and statistics |
+| `/harness` | Show the [harness core](harness-core.md): constraints, pending approvals, evidence, context savings, and skill usage |
+| `/tree` | Navigate the session tree |
+| `/fork` | Create a new session from an earlier user message |
+| `/clone` | Duplicate the current session at its current position |
+| `/compact [instructions]` | Compact the current context, optionally with custom instructions |
+| `/import <path>` | Import and resume a JSONL session |
+
+## Export and share
+
+| Command | Description |
+|---|---|
+| `/copy` | Copy the last assistant message |
+| `/export [path]` | Export the session as HTML or JSONL |
+| `/share` | Upload the session and return its link |
+| `/bug [description]` | Prepare a private bug report for the Relay developers |
+
+Review a session before exporting or sharing it. Sessions can contain prompts, tool arguments, command output, file contents, and credentials exposed during the conversation.
+
+## Runtime and project
+
+| Command | Description |
+|---|---|
+| `/trust` | Save a project trust decision for future Relay processes |
+| `/reload` | Reload keybindings, extensions, skills, templates, themes, and context files |
+| `/hotkeys` | Show active keyboard shortcuts |
+| `/changelog` | Show changelog entries |
+| `/quit` | Quit Relay |
+
+## Commands added by resources
+
+- Extensions can register commands with their own arguments and completion behavior.
+- Each prompt template is available under its template name.
+- Skills are available as `/skill:name` when skill commands are enabled.
+
+Use `/reload` after adding or changing a discovered command resource. See [Extensions](extensions.md), [Prompt Templates](prompt-templates.md), and [Skills](skills.md) for their loading and naming rules.

package/docs/terminal-setup.md

@@ -0,0 +1,219 @@
+# Configure your terminal
+
+Most modern terminals work with Relay without additional setup. Use this page when modified keys, scrolling, links, images, colors, or input-method editor (IME) positioning do not behave as expected.
+
+Relay uses extended-key protocols so terminals can distinguish combinations such as `Shift+Enter` and `Alt+Enter` from plain `Enter`. Terminal proxies, multiplexers, and built-in IDE terminals can change or discard that information.
+
+## Troubleshooting
+
+| Symptom | Start here |
+|---|---|
+| `Shift+Enter` submits instead of inserting a line | Your terminal's section below; for tmux, see [Run Relay in tmux](tmux.md) |
+| `Alt+Enter` does not queue a follow-up | [WezTerm](#wezterm), [Alacritty](#alacritty), or [Windows Terminal](#windows-terminal) |
+| Fullscreen scrolling is unusually slow | [iTerm2](#iterm2) |
+| Links work but show no hover preview | [Ghostty](#ghostty) |
+| Inline images or colors are not detected | [Override detected capabilities](#override-detected-capabilities) |
+| An IME candidate window appears in the wrong place | [WezTerm](#wezterm) or [IntelliJ IDEA](#intellij-idea-integrated-terminal) |
+| Modified keys fail only inside tmux | [Run Relay in tmux](tmux.md) |
+
+Use `/hotkeys` to inspect Relay's active shortcuts. See [Keybindings](keybindings.md) to change them.
+
+## Kitty
+
+Kitty supports the required keyboard protocol without additional configuration.
+
+## iTerm2
+
+Regular terminal mode works without additional configuration.
+
+### Fix slow fullscreen scrolling
+
+In fullscreen mode, Relay owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling native terminal history. Fast trackpad gestures can then move only about one line at a time.
+
+To change this behavior:
+
+1. Open **iTerm2 > Settings > Advanced**.
+2. Search for **Trackpad scrolls fast?**.
+3. Set it to **No**.
+
+This is an iTerm2-wide setting and can also change native trackpad scrolling. The underlying behavior is tracked in [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619).
+
+## Apple Terminal
+
+Relay enables enhanced key reporting when available. If Terminal.app still sends plain Return for `Shift+Enter`, Relay uses a local macOS modifier fallback and treats it as `Shift+Enter`.
+
+The fallback works only when Relay runs on the same Mac as Terminal.app. It cannot inspect the local modifier state when Relay runs on another machine over SSH.
+
+## Ghostty
+
+Add this mapping to Ghostty's configuration if `Alt+Backspace` does not work:
+
+```text
+keybind = alt+backspace=text:\x1b\x7f
+```
+
+The configuration file is `~/Library/Application Support/com.mitchellh.ghostty/config` on macOS and `~/.config/ghostty/config` on Linux.
+
+Older Claude Code configurations may contain:
+
+```text
+keybind = shift+enter=text:\n
+```
+
+This sends a raw linefeed, which Relay cannot distinguish from `Ctrl+J`. Remove the mapping if an older Claude Code installation is the only reason you added it. Relay already binds `Ctrl+J` as a newline alternative, so the mapping may appear to work while still preventing Relay and tmux from receiving a real `Shift+Enter` event.
+
+### Open links in fullscreen mode
+
+Links remain clickable in fullscreen mode, but Ghostty does not show its normal hover underline or URL preview while Relay captures mouse input. Hold `Shift+Command` on macOS or `Shift+Ctrl` on Linux to use Ghostty's native link handling.
+
+## WezTerm
+
+WezTerm normally reports `Shift+Enter` through xterm extended keys. To enable the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
+
+```lua
+local wezterm = require 'wezterm'
+local config = wezterm.config_builder()
+config.enable_kitty_keyboard = true
+return config
+```
+
+### Forward Alt+Enter on macOS
+
+WezTerm binds `Option+Enter` to fullscreen by default on macOS. To use it for Relay's follow-up queue, add this entry to your `config.keys` table:
+
+```lua
+{
+  key = 'Enter',
+  mods = 'ALT',
+  action = wezterm.action.SendString('\x1b[13;3u'),
+}
+```
+
+A complete minimal configuration is:
+
+```lua
+local wezterm = require 'wezterm'
+local config = wezterm.config_builder()
+config.keys = {
+  {
+    key = 'Enter',
+    mods = 'ALT',
+    action = wezterm.action.SendString('\x1b[13;3u'),
+  },
+}
+return config
+```
+
+### Position an IME candidate window in WSL
+
+If CJK IME candidates do not follow Relay's text cursor in WSL, show the hardware cursor:
+
+```bash
+export RELAY_HARDWARE_CURSOR=1
+relay
+```
+
+You can instead set `showHardwareCursor` to `true` in Relay settings.
+
+## Alacritty
+
+Alacritty normally reports `Shift+Enter`. On macOS, `Option+Enter` can arrive as plain `Enter`. Add this to `~/.config/alacritty/alacritty.toml` to forward it to Relay:
+
+```toml
+[[keyboard.bindings]]
+key = "Enter"
+mods = "Alt"
+chars = "\u001b[13;3u"
+```
+
+Restart Alacritty after changing the file.
+
+## VS Code integrated terminal
+
+VS Code 1.109.5 and newer enable the Kitty keyboard protocol in the integrated terminal by default.
+
+For an older version, add a `Shift+Enter` terminal binding to `keybindings.json`:
+
+```json
+{
+  "key": "shift+enter",
+  "command": "workbench.action.terminal.sendSequence",
+  "args": { "text": "\u001b[13;2u" },
+  "when": "terminalFocus"
+}
+```
+
+The user `keybindings.json` file is normally located at:
+
+- macOS: `~/Library/Application Support/Code/User/keybindings.json`
+- Linux: `~/.config/Code/User/keybindings.json`
+- Windows: `%APPDATA%\\Code\\User\\keybindings.json`
+
+## Zed integrated terminal
+
+Add these bindings to Zed's `keymap.json`:
+
+```json
+{
+  "context": "Terminal",
+  "bindings": {
+    "shift-enter": ["terminal::SendText", "\u001b[13;2u"],
+    "ctrl--": ["terminal::SendText", "\u001b[45;5u"],
+    "ctrl-alt-]": ["terminal::SendText", "\u001b[93;7u"]
+  }
+}
+```
+
+## Windows Terminal
+
+Windows Terminal uses Relay's Windows and WSL shortcut defaults. See [Keybindings](keybindings.md) for the complete list.
+
+### Forward Shift+Enter
+
+Open Windows Terminal's `settings.json` with `Ctrl+Shift+,` or **Settings > Open JSON file**. Add this object to its `actions` array:
+
+```json
+{
+  "command": { "action": "sendInput", "input": "\u001b[13;2u" },
+  "keys": "shift+enter"
+}
+```
+
+Fully close and reopen Windows Terminal, then verify that `Shift+Enter` inserts a new line in Relay.
+
+### Use Alt+Enter for follow-ups
+
+Windows Terminal binds `Alt+Enter` to fullscreen by default. Relay therefore uses `Ctrl+Q` for follow-ups on Windows and WSL.
+
+To use `Alt+Enter` instead, configure Windows Terminal to forward the key and bind `app.message.followUp` to `alt+enter` in Relay's `keybindings.json`. See [Keybindings](keybindings.md#assign-keybindings).
+
+## xfce4-terminal and Terminator
+
+These terminals cannot reliably distinguish modified Enter keys from plain `Enter`. Custom bindings such as `Ctrl+Enter` or `Shift+Enter` therefore may not work.
+
+Use a terminal with modern extended-key support when you need those shortcuts, such as Kitty, Ghostty, WezTerm, iTerm2, Windows Terminal, or a compatible Alacritty build.
+
+## IntelliJ IDEA integrated terminal
+
+IntelliJ IDEA's built-in terminal cannot reliably distinguish `Shift+Enter` from plain `Enter`. Use `Ctrl+J` for a newline or run Relay in a terminal with modern extended-key support.
+
+If an IME candidate window does not follow the text cursor, show the hardware cursor:
+
+```bash
+export RELAY_HARDWARE_CURSOR=1
+relay
+```
+
+## Override detected capabilities
+
+Relay automatically detects OSC 8 hyperlinks, inline image protocols, and truecolor support. A terminal proxy or multiplexer can make that detection inaccurate.
+
+| Capability | Environment variable | Setting |
+|---|---|---|
+| Hyperlinks | `RELAY_HYPERLINKS=1\|0\|auto` | `terminal.hyperlinks: true\|false\|"auto"` |
+| Inline images | `RELAY_IMAGE_PROTOCOL=kitty\|iterm2\|none\|auto` | `terminal.images: "kitty"\|"iterm2"\|false\|"auto"` |
+| Truecolor | `RELAY_TRUE_COLOR=1\|0\|auto` | `terminal.trueColor: true\|false\|"auto"` |
+
+Settings take precedence over environment variables. An unset value or `auto` preserves automatic detection.
+
+Only force a capability supported by the complete terminal path. Unsupported escape sequences can corrupt rendering. See [Environment Variables](environment-variables.md#relay-process-configuration) and [Settings](settings.md) for the canonical value definitions.

package/docs/termux.md

@@ -0,0 +1,121 @@
+# Run Relay on Android with Termux
+
+Relay runs on Android through [Termux](https://termux.dev/), a terminal emulator and Linux environment. Text input, file tools, and shell commands are supported. Relay can copy and paste text through the Android clipboard with Termux:API. Clipboard image paste is not supported.
+
+## Before you begin
+
+Install Termux from [GitHub or F-Droid](https://github.com/termux/termux-app#installation). Do not use the deprecated Google Play build.
+
+[Termux:API](https://github.com/termux/termux-api#installation) is optional. Install it only when you want Relay to copy or paste Android clipboard text, or when shell commands need Android device APIs.
+
+## Install Relay
+
+1. Update Termux packages:
+
+   ```bash
+   pkg update && pkg upgrade
+   ```
+
+2. Install Node.js and Git:
+
+   ```bash
+   pkg install nodejs git
+   ```
+
+3. Build Relay from source and link the `relay` command:
+
+   ```bash
+   git clone https://github.com/eltonssouza/relay-harness.git ~/relay
+   cd ~/relay
+   npm ci --ignore-scripts
+   npm run build:offline
+   npm link -w packages/coding-agent
+   ```
+
+4. Verify the installation:
+
+   ```bash
+   relay --version
+   ```
+
+5. Open the folder you want to work in and start Relay:
+
+   ```bash
+   cd /path/to/working-folder
+   relay
+   ```
+
+Continue with the main [Quickstart](quickstart.md#3-choose-a-model) to connect a model and run your first task.
+
+## Access Android shared storage
+
+Termux cannot access shared Android storage until you grant permission. Run this once:
+
+```bash
+termux-setup-storage
+```
+
+After approval, Android shared storage is available under `/storage/emulated/0` and through the links Termux creates under `~/storage/`.
+
+Only grant this permission when Relay should be able to access those files. Commands and tools running in Termux use the same storage permissions as the Termux process.
+
+## Use clipboard commands
+
+Relay uses `termux-clipboard-set` to copy text and `termux-clipboard-get` for its clipboard-paste shortcut. Shell commands can use both commands directly. Install the Termux:API app and its command-line package:
+
+```bash
+pkg install termux-api
+```
+
+Verify the integration:
+
+```bash
+printf 'Relay clipboard test' | termux-clipboard-set
+termux-clipboard-get
+```
+
+The second command should print `Relay clipboard test`.
+
+The Termux clipboard API supports text only. Relay's clipboard-paste shortcut inserts that text into the editor but cannot attach clipboard images.
+
+## Add Termux-specific instructions
+
+Relay detects that it is running in Termux, but it cannot infer how you want it to interact with Android. Add only the environment details relevant to your work to `~/.relay/agent/AGENTS.md`:
+
+````markdown
+# Termux environment
+
+- Relay runs in Termux on Android.
+- Shared Android storage is under `/storage/emulated/0`.
+- Open URLs with `termux-open-url "https://example.com"`.
+- Open files with `termux-open <path>`.
+- Do not access shared storage unless the task requires it.
+````
+
+Run `/reload` after changing the file during an active session.
+
+## Troubleshooting
+
+### Clipboard integration fails
+
+Confirm that you installed both components:
+
+1. The Termux:API Android app from the same source as Termux
+2. The `termux-api` command-line package
+
+Then run the clipboard verification commands above outside Relay. If they fail there, fix the Termux:API installation before retrying Relay's copy command.
+
+### Shared storage reports permission denied
+
+Run `termux-setup-storage`, approve the Android permission request, and retry the path under `~/storage/` or `/storage/emulated/0`.
+
+### Relay is not found after installation
+
+Open a new Termux shell and run:
+
+```bash
+npm prefix -g
+command -v relay
+```
+
+Confirm that the global npm binary directory is on `PATH`, then reinstall Relay if the package is missing.