Conversation
Add structured docs/ folder with 9 documentation pages covering getting started, usage, async PR workflow, session management, configuration, sandbox providers, agents, TUI guide, and CLI reference. Trim README to a high-level overview with links to docs pages. Include VHS tape files for generating TUI screenshots, and update AGENTS.md with instructions for keeping docs up to date when making user-facing changes.
|
Ox Agent seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account. You have signed the CLA already but the status is still pending? Let us recheck it. |
There was a problem hiding this comment.
Pull request overview
Adds a structured docs/ section to host comprehensive end-user documentation and reduces the main README.md to a shorter entry point that links into those docs, plus adds tooling (docs/tapes/) for generating TUI GIFs and guidance in AGENTS.md to keep docs updated alongside user-facing changes.
Changes:
- Introduces multiple new documentation pages under
docs/(usage, workflow, sessions, configuration, providers, agents, TUI, CLI reference, getting started). - Adds VHS tape files + generator script for producing documentation GIFs into
docs/assets/. - Updates
README.mdto be shorter and link to the new docs, and updatesAGENTS.mdwith documentation update guidance.
Reviewed changes
Copilot reviewed 18 out of 19 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/getting-started.md | New installation + first-run + shell completions guide |
| docs/usage.md | New guide for invocation modes, agent modes, and flag compatibility |
| docs/workflow.md | New recommended async PR workflow documentation |
| docs/sessions.md | New session lifecycle and management documentation |
| docs/configuration.md | New config reference (files, keys, env vars) |
| docs/sandbox-providers.md | New Docker/Cloud provider, mount mode, port forwarding documentation |
| docs/agents.md | New agent selection/auth/model documentation |
| docs/tui.md | New TUI views/shortcuts/slash commands/themes documentation |
| docs/cli-reference.md | New CLI reference for commands/flags/options |
| docs/tapes/prompt-screen.tape | VHS tape to capture prompt screen GIF |
| docs/tapes/sessions-list.tape | VHS tape to capture sessions list GIF |
| docs/tapes/slash-commands.tape | VHS tape to capture slash command popover GIF |
| docs/tapes/start-task.tape | VHS tape to capture CLI follow-mode task start GIF |
| docs/tapes/theme-picker.tape | VHS tape to capture theme picker GIF |
| docs/tapes/generate.sh | Script to run all tapes and emit GIFs into docs/assets |
| docs/tapes/README.md | Instructions/prereqs for generating GIF assets from tapes |
| docs/assets/.gitkeep | Keeps docs/assets directory present in git |
| README.md | Trims README content and adds table linking to new docs |
| AGENTS.md | Adds “Documentation” section mapping code changes to doc pages to update |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Comment on lines
+46
to
+53
| | Column | Description | | ||
| |--------|-------------| | ||
| | Status | Color-coded icon (running, completed, failed, stopped) | | ||
| | Provider | `D` for Docker, `C` for Cloud | | ||
| | Name | Session name (derived from the generated branch) | | ||
| | Status | Human-readable status text | | ||
| | CPU | Current CPU usage (Docker sessions only) | | ||
| | Memory | Current memory usage (Docker sessions only) | |
Comment on lines
+65
to
+70
| **Options:** | ||
|
|
||
| | Flag | Description | | ||
| |------|-------------| | ||
| | `-o, --output <format>` | Output format: `table` (default), `json` | | ||
|
|
|
|
||
| | Flag | Description | | ||
| |------|-------------| | ||
| | `-a, --all` | Remove all containers, including running | |
docs/workflow.md
Outdated
| - PR links (once the agent creates one) | ||
| - Which agent and model are being used | ||
|
|
||
| Ox sends a **desktop notification** when an async session completes, so you don't need to keep checking. |
docs/configuration.md
Outdated
|
|
||
| | Key | Type | Default | Description | | ||
| |-----|------|---------|-------------| | ||
| | `themeName` | `string` | `opencode` | TUI color theme. See [Themes](tui.md#themes) for the full list. | |
docs/tapes/start-task.tape
Outdated
| Set TypingSpeed 40ms | ||
|
|
||
| # Show the basic command | ||
| Type `ox -f "Fix the failing unit tests in the auth module"` |
docs/sessions.md
Outdated
| ox sessions -o tui | ||
| ``` | ||
|
|
||
| `ox session ps`, `ox session list`, and `ox session ls` are all aliases for `ox sessions`. |
docs/cli-reference.md
Outdated
|
|
||
| ### `ox sessions` | ||
|
|
||
| List sessions. Aliases: `ox session ps`, `ox session list`, `ox session ls`. |
docs/tui.md
Outdated
Comment on lines
+176
to
+183
| | aura | ayu | carbonfox | catppuccin-frappe | | ||
| | catppuccin-macchiato | catppuccin-mocha | cobalt2 | cursor | | ||
| | dracula | everforest | flexoki | github | | ||
| | gruvbox | kanagawa | lucent-orng | material | | ||
| | matrix | mercury | monokai | nightowl | | ||
| | nord | one-dark | opencode | orng | | ||
| | osaka-jade | palenight | rosepine | solarized | | ||
| | synthwave84 | tokyonight | vercel | vesper | |
murrayju
commented
Mar 16, 2026
Comment on lines
-76
to
-82
| ### Recommended Terminal | ||
|
|
||
| While any terminal should work, we recommend [Ghostty](https://ghostty.org/) for the best TUI experience: | ||
|
|
||
| ```bash | ||
| brew install --cask ghostty | ||
| ``` |
Member
Author
There was a problem hiding this comment.
I think we need to keep this (in some form) in the main README. The default terminal's experience is unfortunately poor, and we need to make it clear that installing a better terminal is highly recommended.
docs/agents.md
Outdated
Comment on lines
+107
to
+108
| opencode: sonnet | ||
| codex: o3 |
Member
Author
There was a problem hiding this comment.
These are not real models. Provide real values like
Suggested change
| opencode: sonnet | |
| codex: o3 | |
| opencode: anthropic/claude-sonnet-4-6 | |
| codex: gpt-5.4 |
- Rename duplicate 'Status' column to 'Icon' in sessions list table - Add yaml to session info output formats in CLI reference - Add --force flag to session clean in CLI reference - Add best-effort caveat to desktop notifications - Correct themeName default (truecolor-dependent: opencode or aura) - Fix backtick-quoted Type command in start-task.tape - Reword session listing commands as equivalent commands, not aliases - Fix theme list: catppuccin-mocha -> catppuccin - Restore recommended terminal section to README - Use real model values in agentModels config example
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/folder with 9 documentation pages covering all user-facing featuresREADME.mdfrom 433 to 100 lines, replacing detailed sections with a documentation table linking to dedicated pagesAGENTS.mdwith instructions for keeping docs up to date when making user-facing changesDocumentation pages
.envfilesVHS tape files for screenshots
Includes 5 VHS
.tapefiles underdocs/tapes/for generating GIF screenshots of the TUI (prompt screen, sessions list, slash commands, task start, theme picker). These requirevhs+ Chromium to run — seedocs/tapes/README.mdfor instructions. Generated GIFs go indocs/assets/.AGENTS.md update
Added a "Documentation" section listing which docs pages to update for different types of user-facing changes, so agents keep docs in sync with code.
Design decisions
--agent-modeCLI flag)