diff --git a/README.md b/README.md index 53b2c0a..568197b 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ Learn more in the Augment Docs: - Overview: [Introducing Auggie CLI](https://docs.augmentcode.com/cli/overview) - Custom Commands Examples: [Custom Slash Commands Examples](https://docs.augmentcode.com/cli/custom-commands-examples) +- Auggie 1.x Preview: [Auggie 1.x Preview & Migration Guide](docs/1.x-preview-guide.md) ## Quick start diff --git a/docs/1.x-preview-guide.md b/docs/1.x-preview-guide.md new file mode 100644 index 0000000..90bf465 --- /dev/null +++ b/docs/1.x-preview-guide.md @@ -0,0 +1,164 @@ +# Auggie 1.x Preview & Migration Guide + +Auggie CLI is preparing for its first major release: **Auggie 1.x.x**! + +After extensive development and feedback across the `0.x` series, the upcoming 1.x release represents a major evolution of Auggie. It replaces the underlying terminal rendering architecture for immediate responsiveness, introduces unified TUI navigation with type-to-filter across all menus, and adds interactive workflow tools like session tree visualization, git worktree management, and session export/import. + +This guide outlines release channels, headline feature highlights, breaking changes, items still in development, and a detailed changelog of customer-relevant fixes and improvements correlated by release tags. + +--- + +## 1. Release Channels & Distribution Tags + +Auggie is published to npm under `@augmentcode/auggie`. Packages are available across three distribution tags: + +| Channel / Tag | Version Series | Recommended For | Description | +|---|---|---|---| +| `latest` | `0.x.x` | Everyday Production | Current stable release line. Remains the default until 1.x completes preview testing. | +| `preview` | `1.x.x` | Early Adopters & Testers | Preview channel for the upcoming 1.x major release. Try out new capabilities and share feedback. | +| `daemon` | `1.x.x` | Automated Runners & CI | Pinned builds for headless automation, background workers, and CI environments. | + +### Installation + +Install or upgrade to the 1.x preview: +```bash +npm install -g @augmentcode/auggie@preview +``` + +Switch back to the stable 0.x release at any time: +```bash +npm install -g @augmentcode/auggie@latest +``` + +In all channels, the command you run in your terminal is simply `auggie`. + +--- + +## 2. Feature Highlights (What’s New in 1.x) + +> *Note: These are curated highlights of user-facing changes in 1.x. For release-by-release details, see the [Changelog](#5-detailed-changelog) below.* + +- **Snappier Terminal UI (Direct ANSI Engine)**: + In 0.x, the terminal interface could stutter or lag during fast token streaming or when printing large diffs. In 1.x, the rendering engine has been rewritten from scratch with a direct terminal renderer (`pi-tui`), delivering instant scrolling, smooth rendering, and zero redraw lag. +- **Interactive Thinking Effort Controls**: + On reasoning models, you can adjust thinking levels interactively rather than being locked into static model configurations. Press **Tab** in the `/model` selector to cycle through thinking efforts (`off` → `minimal` → `low` → `medium` → `high` → `xhigh`), or use **Shift+Tab** from the main prompt. The active thinking level is displayed directly in the status footer, and your choice is remembered per model for future sessions. +- **Predictive Headroom & Compaction Management (`/compact`)**: + In addition to automated background compaction with intelligent headroom budgeting to avoid token limits, 1.x adds the `/compact` slash command to let you manually summarize conversation history on demand. +- **Improved TUI Navigation & Unified Key Mapping**: + Navigation across menus and popovers is now unified: + - **Type-to-Filter**: All selectors (model picker, worktree selector, settings) support typing directly to filter results. + - **Consistent Keybindings**: Standardized navigation across the interface (arrow keys, readline shortcuts like `Ctrl+A`/`Ctrl+E`, `Escape` to step back or dismiss). + - **Custom Keybindings**: Configure personal keybindings in `~/.augment/keybindings.json` and reload them on the fly with `/reload`. Run `/hotkeys` anytime to view the complete shortcut cheat sheet. +- **Session Tree Navigation (`/tree`)**: + While 0.x supported forking sessions with `/fork`, it lacked a way to visualize or navigate between branches. In 1.x, `/tree` provides an interactive visual session tree so you can view conversation branches and jump between them. +- **Interactive Git Worktree Management (`/worktree`)**: + In 1.x, you can manage git worktrees directly from inside Auggie using `/worktree`. An interactive selector lets you create isolated worktrees for experimental tasks, switch between them, and clean them up when finished. +- **Session Export & Import (`/export`, `/import`)**: + You can now export your conversation session to standalone HTML or JSONL files via `/export`, or import and resume a previous session from a JSONL file with `/import`. +- **Redesigned Permission Rule Manager (`/permissions`)**: + `/permissions` is now a full-screen manager that shows active rules across every source (CLI, managed, local, project, global) and lets you add, edit, or remove rules in place. +- **Configurable Themes**: + Settings in `.augment/settings.json` now support custom color themes via `theme` (`"dark"`, `"light"`, or custom theme files). + +--- + +## 3. Breaking Changes & Migration Notes + +When upgrading from `0.x` to `1.x`, keep the following changes in mind: + +### Personas Deprecated & Replaced by Subagents +In 0.x, Auggie supported backend-configured "Personas" via the `/persona` slash command and CLI `auggie persona` commands to adjust system prompts and disable certain tools. + +In 1.x, the separate persona abstraction has been retired in favor of native, standardized customization mechanisms: +- **Custom Subagents / Agents**: Define role-specific behaviors, instructions, and dedicated toolsets in `.augment/agents/.md` (workspace) or `~/.augment/agents/.md` (global). +- **Custom Rules & Prompts**: Set project guidelines and prompt overrides using `.augment/rules/*.md`, `AGENTS.md`, or `.augment/SYSTEM.md`. +- **Tool Permissions**: Restrict or require user confirmation for specific tools via `/permissions` or `.augment/settings.json`. + +### Hook Tool Names Changed (With Temporary Backward Compatibility) +Tool names have been standardized to short, canonical verbs across Auggie 1.x. If you have custom hooks configured under the `hooks` key in `.augment/settings.json` (or `~/.augment/settings.json`), in plugin `hooks/hooks.json` files, or reference tools in permission rules, note the following canonical tool name updates: + +| 1.x Canonical Name | 0.x / Legacy Names (Supported via Backward Compatibility Aliases) | Description | +|---|---|---| +| `read` | `view`, `read-file`, `read_file` | Read file contents | +| `edit` | `str-replace-editor`, `str_replace_editor`, `edit-file`, `edit_file` | Targeted string replacement in files | +| `write` | `save-file`, `save_file`, `write-file`, `write_file` | Create or overwrite files | +| `grep` | `grep-search`, `grep_search` | Search files using regex patterns | +| `find` | `file-search`, `file_search`, `find-by-name` | Find files matching glob patterns | +| `bash` | `launch-process`, `launch_process`, `shell` | Run shell commands | + +> **Note on Compatibility**: Temporary backward compatibility is provided in 1.x. **Hook matchers** using any legacy name above (e.g. `matcher: "str-replace-editor"`) continue to trigger for the canonical 1.x tools during the preview period. +> +> **Permission rules** recognize only a subset of legacy names: `view`, `save-file`, `save_file`, `str-replace-editor`, `str_replace_editor`, `grep-search`, `launch-process`, and `shell`. Other legacy names (such as `read_file`, `launch_process`, or `file_search`) are **not** matched by permission rules, so a deny or ask rule using them will not apply. Update permission rules to the canonical names before upgrading. + +### Hook Payloads: Changed Files Detection +In 0.x, hook events for shell execution attempted to calculate and inject an internal list of modified files into the hook payload. This has been removed from `bash` hooks (and is being phased out across other tool hooks). Hooks requiring a list of modified files should rely directly on version control (e.g., `git status --porcelain` or `git diff --name-only`) rather than tool-level payload heuristics. + +### Keybinding & Configuration Updates +- **`Shift+Tab` Shortcut**: `Shift+Tab` now cycles reasoning effort on thinking models (replacing the legacy plan-mode toggle from 0.x). +- **Settings Preservation**: Existing settings in `.augment/settings.json` and `~/.augment/settings.json` (such as custom shell paths, default models, and MCP servers) continue to be honored automatically. + +### Not Compatible +The following 0.x features will not be supported in 1.x: +- **Chat Input Completions**: Inline completions while typing in the chat input are not available, and the `chatInputCompletions` setting in `settings.json` is ignored. + +--- + +## 4. Still in the Works for GA (Customer Roadmap) + +Items actively being finalized before 1.x becomes the default (`latest`) release: + +- **Seamless 0.x Session Migration**: + Automatic compatibility and fast resume when opening historical `0.x` session history files in `1.x`, enabling you to inspect, resume, or fork earlier sessions without manual format conversion. +- **Hotkey Mapping & Backward Compatibility**: + Refining and finalizing keyboard shortcuts across the terminal interface — ensuring familiar `0.x` hotkeys remain intuitive or backward-compatible, while establishing clean default mappings for new 1.x capabilities (alongside custom bindings via `~/.augment/keybindings.json`). + +--- + +## 5. Detailed Changelog + +### Recent Releases + +#### `v1.2.0-prerelease.202610091519` +- **MCP Reliability**: Gracefully handle and report status on rejected targeted MCP server restarts. + +#### `v1.2.0-prerelease.202610090920` +- **Settings**: Respect and preserve legacy display preferences across sessions. + +#### `v1.2.0-prerelease.202610081217` +- **CLI Help**: Cleaned up and trimmed CLI `--help` examples and tool listings for better readability. +- **Cloud Workflows**: Preserved PR artifacts when local tool definitions share names with cloud tools. + +#### `v1.2.0-prerelease.202610080924` +- **Thinking Selector**: Polished thinking selector labels, keyboard hints, and status footer indicators in the TUI. +- **Rules**: Correctly honor frontmatter rule types for workspace rules. +- **Model Selection**: Honor configured model registry defaults and fallback cleanly when a model is unspecified. +- **Permissions**: Enforce organization and tenant tool permission policies consistently across sessions and subagents. + +#### `v1.2.0-prerelease.202610071518` +- **Interactive Permissions Manager**: Added the `/permissions` interactive TUI screen to inspect, add, edit, and delete tool permission rules across scopes. +- **Startup Performance**: Cached and reused integration tool definitions across sessions for faster CLI startup. +- **CLI Help**: Deduplicated extension flags in `--help` output. + +#### `v1.2.0-prerelease.202610071218` +- **TUI Tool Formatting**: Formatted and rendered remote tool calls and expandable result blocks cleanly in the terminal. + +#### `v1.2.0-prerelease.202610070820` +- **Code Indexing**: Fixed background file watcher to properly capture and upload incremental code edits in active workspaces. +- **Cloud Preference**: Persisted session cloud preference across commands until CLI restart. + +#### `v1.2.0-prerelease.202610061520` +- **GitHub PR Reviews**: Preserved inline review comment reply relationships and threading. + +#### `v1.2.0-prerelease.202610051219` +- **MCP Discovery**: Kept MCP server discovery from blocking CLI startup and isolated server connection failures. + +--- + +### Older Releases (Summary) + +Earlier prereleases in the `v1.0.x` – `v1.2.0` cycle delivered foundational architecture and tool enhancements: +- **Bash Tool**: Raised default command execution timeout to 600s. +- **Plugin Management**: Added the `auggie plugin marketplace add ` command to configure custom plugin marketplaces. +- **MCP Startup**: Kept integration discovery off the startup critical path to accelerate CLI initialization. +- **Diagnostics & Logging**: Preserved structured stack traces in debug logs. +- **Foundation Architecture**: Ported core interactive runtime to the direct ANSI engine (`pi-tui`), established headless daemon runner support, and stabilized the ACP protocol bridge.