Documentation Index

features/cli — Command-Line Interface

The CLI surface and its supporting mechanics. Every flag, subcommand, and override pattern.

File	Description
`interface.md`	Full CLI subcommand tree design, headless vs interactive duality, and architectural decisions revealed by flag layout. Covers Aider (argparse), Codex (clap), and OpenCode (yargs).
`config-overrides.md`	The `-c key=value` pattern for overriding any config field at the command line using TOML dotted-path syntax, without editing a config file.
`shell-completions.md`	Generating and installing shell completion scripts for bash, zsh, and fish via `clap`’s built-in completion generator.

features/searching — File and Symbol Search

How the agent finds files and symbols across a large codebase within a limited context window.

File	Description
`repo-mapping.md`	The core repo mapping system: tree-sitter tag extraction, PageRank-based symbol ranking, SQLite caching, binary-search token budget fitting, and LSP augmentation. Covers Aider, Codex, and OpenCode approaches.
`fuzzy-file-search.md`	Interactive fuzzy file picker using `nucleo`, gitignore-aware parallel filesystem walking with `ignore`, and progressive result streaming to the TUI.
`ripgrep-integration.md`	How `ripgrep` is used as the primary file content search backend for agent tools, including pattern search, file listing, and the debug interface.

features/editing — File Edit Mechanics

How the agent proposes, applies, streams, and rolls back file changes.

File	Description
`edit-formats.md`	The diff, udiff, search-replace, and whole-file edit formats: when each is chosen, how the LLM produces them, and the tradeoffs in token cost and error rate.
`streaming-edits.md`	Applying file patches incrementally as tokens stream in from the model, before the response is complete. Reduces perceived latency for large edits.
`undo-redo.md`	Snapshot-based undo system: capturing file state before each agent turn, content-addressing snapshots, and restoring on rollback. Covers Codex’s `snapshot` subsystem and OpenCode’s VFS.

features/context — Context Window Management

How the total context budget is allocated and maintained across turns.

File	Description
`chat-history.md`	Rolling chat history: summarization strategies, truncation policies, and token budget allocation so history doesn’t crowd out working context.
`token-budgeting.md`	How the total context window is partitioned across system prompt, repo map, chat history, tool results, and the current user message.
`prompt-caching.md`	Provider-side prompt cache mechanics (Anthropic, OpenAI), how to structure prompts to maximize cache hit rate, and cache keepalive ping patterns.

features/lsp — Language Server Protocol

LSP client architecture and how LSP data feeds into agent context.

File	Description
`integration.md`	LSP client architecture: spawning language server processes, initialization handshake, request routing, multi-server support per workspace, and cold-start latency handling.
`diagnostics.md`	Feeding LSP diagnostics (errors, warnings, hints, code actions) back to the model as structured tool results after each edit cycle.

features/tui — Terminal User Interface

Ratatui-based rendering, input handling, and terminal compatibility.

File	Description
`rendering.md`	Ratatui frame loop, widget layout system, flicker-free double-buffered updates, and how OpenTUI’s Zig rendering primitives inform the design.
`input-handling.md`	Key event processing, PTY allocation for shell tool execution, alt-screen management, and inline mode for terminals like Zellij that restrict alternate screen scrollback.

features/server — Client-Server Architecture

The background server, protocol design, and MCP.

File	Description
`architecture.md`	The HTTP/SSE server design: how the TUI, headless CLI, and IDE plugins all connect to a shared persistent agent backend. Covers OpenCode’s Hono server and the event bus.
`mcp-integration.md`	Managing MCP servers: stdio and remote StreamableHTTP/SSE transports, OAuth PKCE flows, tool routing, and running OpenOxide itself as an MCP server.

features/git — Git Integration

Auto-commit, dirty-commit handling, and project documentation conventions.

File	Description
`auto-commit.md`	Automatic commit generation after accepted edits: AI attribution, custom commit message prompts, dirty-commit handling, and the `--dry-run` escape hatch.
`agents-md.md`	Hierarchical project documentation discovery (`AGENTS.md`) from repo root to CWD, byte budget enforcement, override priority (`AGENTS.override.md`), and prompt injection security pitfalls.

features/ai — Model and Provider Abstraction

LLM provider interfaces, multi-model workflows, and output constraints.

File	Description
`provider-abstraction.md`	Unified LLM provider interface: API key management, endpoint configuration, per-provider quirks, and fallback chains for resilience.
`multi-model.md`	Architect mode: a planner model produces a high-level plan, a separate editor model applies it to files. Covers Aider’s `--architect` flag and model-specific `--editor-model`.
`structured-output.md`	Constraining model responses to a JSON Schema via the API, retrying on schema violations, and using structured output for tool call results and code review summaries.

features/sandboxing — Process Isolation

OS-level sandboxing for safe agent shell execution.

File	Description
`sandbox-modes.md`	The three sandbox tiers (read-only, workspace-write, full-access): behavioral contracts, approval policy axes, and the `--full-auto` shorthand.
`platform-isolation.md`	OS-level enforcement mechanisms: Landlock + seccomp on Linux, Seatbelt (sandbox-exec) on macOS, AppContainer or restricted token on Windows. Follows Codex’s `codex-rs/linux-sandbox/` model.

features/permissions — Agent Permissions

What the agent is and isn’t allowed to do, and how those limits are declared.

File	Description
`index.md`	What filesystem paths, network hosts, and shell commands the agent may access; how permissions are declared in config and enforced at runtime; the relationship between permissions and sandbox modes.

features/mcp — Model Context Protocol

OpenOxide as both an MCP host and an MCP server.

File	Description
`client.md`	Managing external MCP servers: adding stdio and remote StreamableHTTP/SSE transports, OAuth PKCE flows, tool discovery, and routing tool calls to the correct server.
`server.md`	Running OpenOxide itself as an MCP server on stdio, exposing its agent capabilities as callable tools to other hosts or editors.

features/acp — Agent Client Protocol

The ACP layer that sits above raw HTTP/SSE and enables multi-client agent sessions.

File	Description
`server.md`	Running an ACP server: transport options, working directory scoping, and how ACP differs from the raw HTTP/SSE event bus.
`client.md`	Connecting to a running ACP server and issuing agent requests: attaching to an in-progress session, sending messages, and receiving streamed events.

features/sessions — Session Management

How sessions are stored, resumed, imported, and exported.

File	Description
`directory-layout.md`	How session data is structured on disk: the directory hierarchy under the XDG data path, file naming conventions, and the content of each persisted artifact (messages, snapshots, metadata).
`import.md`	Restoring a session from a JSON export file or a share URL: schema validation, ID remapping, and conflict handling when a session already exists locally.
`export.md`	Dumping a session to a portable JSON format for backup, sharing, or migration between machines; the share URL format and any hosted sharing service requirements.

features/pr — GitHub Pull Request Integration

Agent-assisted PR review and automation.

File	Description
`index.md`	The `pr` subcommand: fetching a PR branch, constructing diff context from changed files, launching the agent in review mode, and the `github run` automation path for CI-triggered reviews.

features/exec — Non-Interactive Exec Mode

Running a single prompt and exiting without a persistent session.

File	Description
`index.md`	The `exec` / `run` subcommand: one-shot prompt execution, JSONL event stream output for machine consumers, JSON Schema constraints on the final response, and ephemeral session handling.