# 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.