Skip to content

docs: add Auggie 1.x preview & migration guide #176

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
augmentmoogi merged 5 commits into from
Oct 15, 2026
Merged

docs: add Auggie 1.x preview & migration guide #176

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1981a0b
docs: add Auggie 1.x preview & migration guide
augmentmoogi Oct 12, 2026
2dc6257
docs: rename v2-notes to 1.x-preview-guide
augmentmoogi Oct 12, 2026
d4f149c
docs: remove internal PR references from preview guide
augmentmoogi Oct 12, 2026
bb3460a
docs: note chat input completions are not supported in 1.x
augmentmoogi Oct 14, 2026
de9d70e
docs: address review feedback on 1.x preview guide
augmentmoogi Oct 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
164 changes: 164 additions & 0 deletions docs/1.x-preview-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/<name>.md` (workspace) or `~/.augment/agents/<name>.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 <source>` 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.