Amp GUI

Amp GUI is a local Next.js workbench for Amp. It gives you a browser UI for starting Amp runs, continuing previous threads, attaching screenshots, inspecting live tool activity, and browsing cached conversation history without staying in the terminal.

Security note: this app shells out to your local amp executable and can run with Amp's dangerous tool-approval bypass when you enable allow tools. Run it only on a trusted machine, keep it bound to localhost, and do not expose it publicly without adding authentication and a workspace allowlist.

Features

• Stream Amp responses through a chat UI.
• Continue existing Amp threads or open a thread by T-... ID / ampcode.com URL.
• Browse, search, pin, and group recent threads by workspace.
• Paste, drag, or select image attachments for multimodal prompts.
• Inspect live tool calls, stderr, run duration, token usage, and diagnostics.
• Cache thread lists/exports locally in SQLite for faster navigation.
• Run on native Windows, native Linux/macOS, or WSL with a Windows Amp install.

Requirements

• Node.js 20+
• pnpm 10+
• Amp CLI installed and available on PATH

Check your Amp install first:

amp --version
amp threads list --json

On Windows PowerShell:

amp --version
amp threads list --json

Install

git clone https://github.com/WinterArc21/AmpGUI.git
cd AmpGUI
pnpm install

Run

Windows PowerShell

pnpm dev

Open http://localhost:3000.

The workspace input accepts Windows paths such as C:\code\my-repo. If you leave it blank, Amp runs from the folder where you launched pnpm dev.

macOS / Linux

pnpm dev

Open http://localhost:3000.

The workspace input accepts POSIX paths such as /home/me/code/my-repo. If blank, Amp runs from the launch folder.

WSL with Windows Amp

This mode is supported for people who run the GUI in WSL but have amp installed on Windows. The app converts WSL paths to Windows paths before launching Amp.

pnpm dev

If the Windows launch folder needs to be overridden, set:

export AMP_GUI_WINDOWS_LAUNCH_CWD=/mnt/c/Users/your-user
pnpm dev

For the most reliable setup, install Amp in the same environment that runs the GUI: native Windows Amp for PowerShell, native Linux Amp for WSL/Linux.

Configuration

Environment variables:

Variable	Purpose
AMP_CMD	Override the Amp executable name/path. Defaults to amp.
AMP_GUI_CACHE_DIR	Override the local SQLite cache directory. Defaults to .amp-gui-cache/.
AMP_GUI_WINDOWS_LAUNCH_CWD	WSL-only fallback folder used when launching Windows Amp through cmd.exe.

Local browser settings store your last workspace/mode and pinned threads in localStorage.

Using the UI

1. Start the dev server and open the app.
2. Pick or type a workspace. Blank means the folder where the GUI server is running.
3. Choose an Amp mode.
4. Keep allow tools off unless you trust the workspace and want Amp to run without approval prompts.
5. Type a prompt, optionally paste/drop images, and press Enter.
6. Use the activity drawer to inspect tool calls and stderr.
7. Paste a thread ID or ampcode.com thread URL into Open thread ID or URL to jump directly to a conversation.

Useful scripts

pnpm dev      # start local dev server
pnpm build    # production build/typecheck
pnpm start    # start production server after build
pnpm lint     # ESLint

Cache and diagnostics

The GUI caches Amp thread metadata and exports in .amp-gui-cache/amp-gui-cache.sqlite. The Settings panel shows cache stats and includes a Clear cache button.

Diagnostics also report:

• detected Amp command/path/version
• platform and launch folder
• whether WSL is invoking a Windows Amp install
• cache size and freshness

Troubleshooting

amp is not found

Make sure amp is available in the same shell that runs pnpm dev. You can also set AMP_CMD to an absolute executable path.

Windows cannot open a workspace

Use a native Windows path like C:\code\repo, or leave the workspace blank to run from the launch folder. If you are running from WSL with Windows Amp, prefer paths without spaces or install Amp directly in WSL.

Threads are stale or missing

Click Refresh in the sidebar, or clear the cache in Settings.

A run is still active

The GUI intentionally blocks switching conversations while an Amp run is streaming so a response cannot be appended to the wrong thread. Stop the run or wait for it to finish.

Current limitations

• This is a local workbench, not a hardened hosted service.
• Thread exports reconstruct chat history, but older exported threads may not have a full replayable tool timeline yet.
• The upload API is currently unused by the UI; image prompts are sent as base64 directly to Amp.