@m4ike1/ion-coding-agent 0.1.0

package/docs/usage.md

@@ -0,0 +1,327 @@
+# Using Ion
+
+This page collects day-to-day usage details that do not fit on the quickstart page.
+
+## Interactive Mode
+
+<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
+
+The interface has four main areas:
+
+- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
+- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
+- **Editor** - where you type; border color indicates the current thinking level
+- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model. Totals include assistant responses, usage reported by tools, and summary generation.
+
+The editor can be replaced temporarily by built-in UI such as `:settings` or by custom extension UI.
+
+### Editor Features
+
+| Feature | How |
+|---------|-----|
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Press Tab to complete paths |
+| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
+| Copy response | Ctrl+X copies the selected message in `:tree`; otherwise it copies the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
+| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Shell command | `!command` runs and sends output to the model |
+| Hidden shell command | `!!command` runs without sending output to the model |
+| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
+
+See [Keybindings](keybindings.md) for all shortcuts and customization.
+
+## Slash Commands
+
+Type `/` in the editor to open command completion. Prompt templates expand via `/templatename`. Extension commands stay available when typed directly, and skills invoke via `$name` in a message or the hidden `/skill:name`.
+
+| Command | Description |
+|---------|-------------|
+| `:login`, `:logout` | Manage OAuth or API-key credentials |
+| [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
+| `:model` | Switch models; Ctrl+S in the picker saves the startup default |
+| `:thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
+| `:scoped-models` | Enable/disable models for Ctrl+P cycling |
+| `:settings` | Theme, message delivery, transport, and other preferences |
+| `:resume` | Pick from previous sessions |
+| `:new` | Start a new session |
+| `:name <name>` | Set session display name |
+| `:session` | Show session file, ID, messages, tokens, and cost |
+| `:tree` | Jump to any point in the session and continue from there |
+| `:trust` | Save project trust decision for future sessions |
+| `:fork` | Create a new session from a previous user message |
+| `:clone` | Duplicate the current active branch into a new session |
+| `:compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `:copy` | Copy last assistant message to clipboard |
+| `:export [file]` | Export session to HTML or JSONL |
+| `:import <file>` | Import and resume a session from a JSONL file |
+| `:share` | Upload as private GitHub gist with shareable HTML link |
+| `:reload` | Reload keybindings, extensions, skills, prompts, themes, and context files |
+| `:hotkeys` | Show all keyboard shortcuts |
+| `:changelog` | Display version history |
+| `:quit` | Quit ion |
+
+## Message Queue
+
+You can submit messages while the agent is still working:
+
+- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
+- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
+- **Escape** aborts and restores queued messages to the editor.
+- **Alt+Up** retrieves queued messages back to the editor.
+
+On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want ion to receive the shortcut.
+
+Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
+
+## Sessions
+
+Sessions are saved automatically to `~/.ion/agent/sessions/`, organized by working directory.
+
+```bash
+ion -c                  # Continue most recent session
+ion -r                  # Browse and select a session
+ion --no-session        # Ephemeral mode; do not save
+ion --name "my task"    # Set session display name at startup
+ion --session <path|id> # Use a specific session file or session ID
+ion --fork <path|id>    # Fork a session into a new session file
+```
+
+Useful session commands:
+
+- `:session` shows the current session file and ID.
+- `:tree` navigates the in-file session tree and can summarize abandoned branches.
+- `:fork` creates a new session from an earlier user message.
+- `:clone` duplicates the current active branch into a new session file.
+- `:compact` summarizes older messages to free context.
+
+See [Sessions](sessions.md) and [Compaction](compaction.md) for details.
+
+## Context Files
+
+Ion loads `AGENTS.md` or `CLAUDE.md` at startup from:
+
+- `~/.ion/agent/AGENTS.md` for global instructions
+- parent directories, walking up from the current working directory
+- the current directory
+
+If a directory contains `AGENTS.override.md`, Ion loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories still layer normally.
+
+Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
+
+### System Prompt Files
+
+Replace the default system prompt with:
+
+- `.ion/SYSTEM.md` for a project
+- `~/.ion/agent/SYSTEM.md` globally
+
+Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+
+### Project Trust
+
+On interactive startup, ion asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` and has no saved decision for the folder or a parent folder in `~/.ion/agent/trust.json`. Trusting a project allows ion to load `.ion/settings.json` and `.ion` resources, install missing project packages, and execute project extensions.
+
+Before the trust decision, ion loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process.
+
+Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
+
+If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.ion/agent/settings.json`, or change it with `:settings`.
+
+`ion config` and package commands use the same project trust flow, except `ion update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
+
+Use `:trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.ion/agent/trust.json` only; the current session is not reloaded, so restart ion for changes to take effect.
+
+
+## Exporting and Sharing Sessions
+
+Use `:export [file]` to write a session to HTML.
+
+Use `:share` to upload a private GitHub gist with a shareable HTML link.
+
+If you use ion for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/ion-share-hf`](https://github.com/badlogic/ion-share-hf). It publishes sessions to Hugging Face datasets.
+
+## CLI Reference
+
+```bash
+ion [options] [--] [@files...] [messages...]
+```
+
+### Package Commands
+
+```bash
+ion install <source> [-l]     # Install package, -l for project-local
+ion remove <source> [-l]      # Remove package
+ion uninstall <source> [-l]   # Alias for remove
+ion update [source|self|ion]   # Update ion only, or one package source
+ion update --all              # Update ion and packages; reconcile pinned git refs
+ion update --extensions       # Update packages only; reconcile pinned git refs
+ion update --models           # Refresh model catalogs only
+ion update --self             # Update ion only
+ion update --extension <src>  # Update one package
+ion list                      # List installed packages
+ion config [-l]               # Enable/disable package resources
+```
+
+### Auth Commands
+
+```bash
+ion auth print-api-key --provider <provider> [--model <model>]
+ion auth print-bearer-token --provider <provider> [--model <model>] [--min-expiry <duration>]
+ion auth check --provider <provider> [--model <model>] [--json] [--credentials] [--no-refresh]
+```
+
+`print-api-key` and `print-bearer-token` emit a credential for an external client. `check` reports provider readiness (`ready`, `not_ready`, `invalid`); it refreshes expired OAuth credentials unless `--no-refresh` is passed.
+
+These commands manage ion packages and `ion update` can update the ion CLI installation. To uninstall ion itself, see [Quickstart](quickstart.md#uninstall). `ion config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command. `ion update` never prompts for project trust.
+
+See [Ion Packages](packages.md) for package sources and security notes.
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| default | Interactive mode (`--mode text` without `-p`; piped stdin switches to print) |
+| `-p`, `--print` | Print response and exit |
+| `--mode text` | Explicit default text output (print or interactive, depending on TTY) |
+| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
+| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
+| `--export <in> [out]` | Export a session to HTML |
+
+In print mode, ion also reads piped stdin and merges it into the initial prompt:
+
+```bash
+cat README.md | ion -p "Summarize this text"
+```
+
+### Model Options
+
+| Option | Description |
+|--------|-------------|
+| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
+| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
+| `--api-key <key>` | API key, overriding environment variables |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
+| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
+| `--list-models [search]` | List available models |
+
+### Session Options
+
+| Option | Description |
+|--------|-------------|
+| `-c`, `--continue` | Continue the most recent session |
+| `-r`, `--resume` | Browse and select a session |
+| `--session <path\|id>` | Use a specific session file or partial UUID |
+| `--session-id <id>` | Use an exact project session ID, creating it if missing |
+| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
+| `--session-dir <dir>` | Custom session storage directory |
+| `--no-session` | Ephemeral mode; do not save |
+| `--name <name>`, `-n <name>` | Set session display name at startup |
+
+`--fork` cannot be combined with `--session`, `--continue`, `--resume`, or `--no-session`. `--session-id` cannot be combined with `--session`, `--continue`, or `--resume`.
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
+| `--exclude-tools <list>`, `-xt <list>` | Disable specific built-in, extension, and custom tools |
+| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
+| `--no-tools`, `-nt` | Disable all tools |
+
+Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`.
+Defaults are `read`, `bash`, `edit`, `write`, `grep` (overridable via the `defaultTools` setting); `find`, `ls`, and `powershell` are opt-in via `--tools`.
+
+### Resource Options
+
+| Option | Description |
+|--------|-------------|
+| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
+| `--no-extensions`, `-ne` | Disable extension discovery |
+| `--skill <path>` | Load a skill; repeatable |
+| `--no-skills`, `-ns` | Disable skills discovery and loading |
+| `--prompt-template <path>` | Load a prompt template; repeatable |
+| `--no-prompt-templates`, `-np` | Disable prompt template discovery and loading |
+| `--theme <path>` | Load a theme; repeatable |
+| `--no-themes` | Disable theme discovery |
+| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
+
+```bash
+ion --no-extensions -e ./my-extension.ts
+```
+
+### Other Options
+
+| Option | Description |
+|--------|-------------|
+| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
+| `--append-system-prompt <text>` | Append to system prompt; repeatable |
+| `--offline` | Disable startup network operations (same as `ION_OFFLINE=1`) |
+| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
+| `--use-theme <name[:name]>` | Set the initial interactive theme for this run without changing settings |
+| `--verbose` | Force verbose startup |
+| `-a`, `--approve` | Trust project-local files for this run |
+| `-na`, `--no-approve` | Ignore project-local files for this run |
+| `--` | Stop option parsing; remaining arguments are prompts or `@file` inputs |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, working status, extension widgets, editor, and footer remain fixed at the bottom. Mouse/trackpad input scrolls the region under the pointer; keyboard viewport actions always remain available. Inline images work in terminals that support the Kitty graphics protocol, including Kitty and Ghostty. In iTerm2 they render as text placeholders because its inline-image protocol cannot delete or crop placements during application-owned scrolling. In `regular` mode, ion uses the main screen and terminal-owned scrollback, and iTerm2 inline images continue to render normally. See [Terminal setup](terminal-setup.md) for terminal-specific settings and workarounds.
+
+Set **TUI mode** in `:settings` to switch between `regular` and `fullscreen` immediately and choose the default for future sessions. **Fullscreen exit output** controls whether exiting fullscreen prints the final transcript or restores the previous screen and prints only the session resume hint.
+
+### File Arguments
+
+Prefix files with `@` to include them in the message:
+
+```bash
+ion @prompt.md "Answer this"
+ion -p @screenshot.png "What's in this image?"
+ion @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```bash
+# Interactive with initial prompt
+ion "List all .ts files in src/"
+
+# Non-interactive
+ion -p "Summarize this codebase"
+
+# Prompt beginning with a dash
+ion -p -- "- Summarize these points"
+
+# Non-interactive with piped stdin
+cat README.md | ion -p "Summarize this text"
+
+# Named one-shot session
+ion --name "release audit" -p "Audit this repository"
+
+# Different model
+ion --provider openai --model gpt-4o "Help me refactor"
+
+# Model with provider prefix
+ion --model openai/gpt-4o "Help me refactor"
+
+# Model with thinking level shorthand
+ion --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+ion --models "claude-*,gpt-4o"
+
+# Read-only mode
+ion --tools read,grep,find,ls -p "Review the code"
+
+# Disable one extension or built-in tool while keeping the rest available
+ion --exclude-tools ask_question
+```
+
+## Design Principles
+
+Ion keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
+
+It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+
+For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-ion-coding-agent/).

package/docs/webfetch.md

@@ -0,0 +1,119 @@
+# Web Research
+
+Ion can search the web and read pages through two built-in tools. They work identically for every provider and model because they run in the harness, not in provider-specific MCP servers.
+
+| Tool | Description |
+|------|-------------|
+| `webfetch` | Search the web. Returns titles, URLs, and snippets; each result is stored as a `web://` ref |
+| `webextract` | Read the full text of a `web://` ref or a URL, windowed by character offset |
+
+Both tools are opt-in and disabled by default. Turn them on from `:settings` (the **Web search** and **Web extract** toggles, applied immediately) or in your settings file:
+
+```json
+{
+  "webTools": { "search": true, "extract": true }
+}
+```
+
+`webTools` layers on top of `defaultTools` and the `--tools`/`--no-tools` flags: an explicit tool list from the command line or SDK still wins. Listing `webfetch`/`webextract` in `defaultTools` also works.
+
+Edits to `webTools`, `defaultTools`, or `firecrawlApiKey` are picked up by `:reload` — no restart needed. The stored `web://` documents survive a reload, so refs returned before the reload stay valid.
+
+## Searching
+
+```text
+webfetch "ion agent changelog" (limit 5)
+```
+
+Results show the snippet only. Full text stays out of context until requested:
+
+```text
+Search results for "ion agent changelog":
+
+1. Ion releases
+   https://ion.dev/releases (web://1)
+   Monthly release notes for the Ion agent.
+
+Full text is not included. Use webextract with a web:// ref to read a result.
+```
+
+### Sources and counts
+
+`results` sets the modality and how many of each you want. Counts belong to the
+source, not the call: a flat `sources + limit` cannot say whether 5 means 5 total
+or 5 per source.
+
+```text
+webfetch "lagos skyline" results={images: 3}
+webfetch "openai announcements" results={web: 5, news: 5}
+```
+
+Naming a source replaces the default web-only request, so `results={images: 3}`
+returns images and nothing else. With no `results`, `webfetch` returns 5 web
+results. `limit` caps the total across sources and scales the per-source counts
+down together (reported in the tool details).
+
+### Filters
+
+```text
+webfetch "gpt-5" filters={domains: ["openai.com"], recency: "7d"}
+```
+
+`recency` accepts `24h`, `7d`, `2w`, `6m`, `1y`. Filters map to the backend that
+answers: Firecrawl takes `includeDomains` and a `tbs` window, Exa's REST tier
+takes `includeDomains` and `startPublishedDate`.
+
+### Tag sugar
+
+When `results`/`filters` are omitted, tags in the query string are compiled into
+the same intent — a thin parser over one grammar, not a second API:
+
+```text
+webfetch "[images=3] lagos skyline"
+webfetch "[news=5] [recent=7d] openai announcements"
+webfetch "[domains=openai.com,anthropic.com] reasoning models"
+webfetch "[img] lagos"          # shorthand for one image
+```
+
+Recognized tags are reported in `appliedTags`; a tag whose value cannot be used
+(say `[images=lots]`) stays in the query and is reported in `tagWarnings`.
+Bracketed text that is not a recognized key is left alone, so searching for the
+literal `"[img3]"` still works. Structured arguments always win over tags.
+
+## Reading pages
+
+```text
+webextract ref=web://1
+webextract ref=web://1 offsetChars=8000
+webextract url=https://example.com/page
+```
+
+Provide exactly one of `ref` or `url`. The first read of a search-result ref fetches the page; later reads page from the stored document with `offsetChars`/`lengthChars` (default window: 8000 characters). The result header echoes the served window (`[chars 0-8000 of 42133]`) so paging is straightforward.
+
+## Authentication
+
+Search and page extraction run through Firecrawl. Without a key the keyless tier applies (lower limits, surfaced in tool details as a warning). Set an API key with the `firecrawlApiKey` setting or the `FIRECRAWL_API_KEY` environment variable (see [Environment Variables](environment-variables.md)).
+
+The keyless tier is provider-side and network-dependent: it can refuse an address outright (403) or exhaust the shared anonymous pool (429). A configured key that is rejected still reports the raw provider error, so a bad key stays diagnosable. Page extraction (`webextract`) transparently falls back to a direct fetch in all of these cases.
+
+## Search backends
+
+`webfetch` searches through an ordered chain and reports which backend answered:
+
+1. **Firecrawl** (`POST /v2/search`) — primary. Optional key, keyless tier supported.
+2. **Exa** — the Firecrawl-independent fallback, so search keeps working when Firecrawl refuses the network.
+   - With `exaApiKey` / `EXA_API_KEY`: official REST `POST https://api.exa.ai/search`.
+   - Without a key: Exa's hosted MCP search tier, no account required.
+
+A backend is skipped only for auth, quota, transport, timeout, empty-response, or keyless-refusal failures; a malformed query still surfaces its own error instead of silently switching providers. When a later backend answers, tool details carry a `backendNotice` naming the skipped backend and its reason. An empty result set also reports any skipped backend, so "nothing matched" is never confused with "the provider was unavailable". Results are never merged across backends. Page fetching is not part of the Exa backend — that stays with Firecrawl and the direct-fetch fallback.
+
+Capability differences are explicit rather than papered over: image results come from Firecrawl only (Exa returns nothing for an image-only request instead of substituting web hits), and Exa's keyless tier refuses `recency`/`domains` with a message pointing at `EXA_API_KEY` rather than silently dropping the filter.
+
+## Backends and guardrails
+
+When Firecrawl is unreachable, rate-limited, or returns no usable text, page fetches fall back to a direct fetch with a one-line notice in tool details. Results are never fabricated: the direct-fetch backend cannot search, so a failed search surfaces as an error.
+
+All fetches share the same guardrails:
+
+- Only `http:`/`https:` targets; private, loopback, link-local, multicast, and carrier-grade NAT addresses are blocked, including hostnames that resolve to them (re-checked on every redirect).
+- At most 6 redirects, a 2 MB body cap, and a 30 s per-request timeout.

package/docs/windows.md

@@ -0,0 +1,39 @@
+# Windows Setup
+
+Ion uses Git Bash by default on Windows. Checked locations (in order):
+
+1. Custom path from `~/.ion/agent/settings.json`
+2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
+3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+
+For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
+
+## PowerShell Tool
+
+The optional `powershell` tool runs commands through `pwsh.exe` when available, otherwise Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
+
+Use `defaultTools` to replace the model-facing `bash` tool:
+
+```json
+{
+  "defaultTools": ["read", "powershell", "edit", "write"]
+}
+```
+
+Or enable both while comparing behavior:
+
+```json
+{
+  "defaultTools": ["read", "bash", "powershell", "edit", "write"]
+}
+```
+
+The `!` and `!!` editor commands still use Bash.
+
+## Custom Bash Path
+
+```json
+{
+  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
+}
+```

package/examples/README.md

@@ -0,0 +1,28 @@
+# Examples
+
+Example code for ion-coding-agent SDK and extensions.
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, extensions, and session management.
+
+### [extensions/](extensions/)
+Example extensions demonstrating:
+- Lifecycle event handlers (tool interception, safety gates, context modifications)
+- Custom tools (todo lists, questions, subagents, output truncation)
+- Commands and keyboard shortcuts
+- Custom UI (footers, headers, editors, overlays)
+- Git integration (checkpoints, auto-commit)
+- System prompt modifications and custom compaction
+- External integrations (SSH, file watchers, system theme sync)
+- Custom providers (Anthropic with custom streaming, GitLab Duo)
+
+### [plugins/ion-example-plugin/](plugins/ion-example-plugin/)
+An experimental plugin package that Ion automatically builds into separate Session-worker and TUI Chord facets.
+
+## Documentation
+
+- [SDK Reference](sdk/README.md)
+- [Extensions Documentation](../docs/extensions.md)
+- [Skills Documentation](../docs/skills.md)