Why I Built a Web UI for Amazon Q Developer CLI (And How I Vibe-Coded It)

🚀 Beyond the Console: Why I Built a Web UI for the Amazon Q Developer CLI

Amazon Q is a game-changer for developers, but if you've only used it inside the AWS Console, you're only seeing part of the picture. Using Q in the Console is great for general AWS questions, but when it comes to interacting with your own code and environment, it hits fundamental limits.

My project started not from a corporate need, but from a personal one familiar to many developers: the homelab. I wanted a way to make quick fixes on my server from anywhere, but was constantly frustrated by the clunky experience of mobile terminals. This is the story of why I built the Amazon Q Developer CLI WebUI.

📱 The Real Problem: The Mobile Terminal Nightmare

Picture this: you're on the couch with your phone and have an idea for a quick change on your homelab server. You log in through a mobile web terminal and immediately hit a wall. Have you ever tried to paste a multiline command into one? Or send a Ctrl+C to stop a runaway process? It's a nightmare of awkward UIs, missed keystrokes, and immense frustration.

🧱 Example 1: The Multi-Line docker run Command

A common task in a homelab is running a new Docker container with specific ports and volumes:

docker run -d --name=my-app \
  -p 8080:80 \
  -v $(pwd)/data:/app/data \
  nginx

Mobile Frustrations:

• Line Breaks: Typing a backslash (\) then hitting Enter is clumsy and error-prone on mobile keyboards.
• Special Characters: Juggling -, :, =, and $ requires constant switching between keyboard symbol layouts.
• Editing: Fixing a typo in the middle of this command on a touchscreen is incredibly difficult.

🔍 Example 2: The Piped find and grep Command

You need to search for a specific configuration line within all .conf files:

find . -name "*.conf" | xargs grep "listen_port"

Mobile Frustrations:

• Keyboard Gymnastics: This short command is packed with hard-to-access symbols on mobile keyboards: ., *, ", and especially |.
• The Pipe (|): Often deeply hidden, requiring multiple taps to find and type.
• No Ctrl Key: If a command hangs, the lack of an easy Ctrl+C makes stopping it a nightmare.

This frustration becomes a major barrier when using powerful tools like the Amazon Q Developer CLI. The CLI is the perfect assistant for the job—but it's shackled to a terminal that mobile browsers just can't handle.

🤯 Other Reasons for Build This Project

• You cannot install the great Amazon Q Developer CLI on Windows 🪟 unless you setup Windows Subsystem for Linux (WSL).
• For other AI Agent alternatives, they usually belong to one of the cases below:
  • Pure server side AI Agents - like Gemini/ChatGPT, they have access to tools/canvas and even run code for you - but they are not connected to your computer/servers
  • CLI AI Agents - like Codex CLI, requires you to use in a Bring-Your-Own-Key way. You have to be very careful with your context length as you need to worry about token usage.

🤖 Q Developer CLI: An Agent with Better Tools

Think of the Amazon Q Developer CLI as a specialized AI agent with more powerful "tools" than the AWS Console version. Its biggest advantage? File system access, giving it the context it needs to be a true coding partner.

Also look at how I vibe coded a Star Wars inspired lightsaber duel game: Building A Plasma Sword Fighter Game with Amazon Q CLI

🔍 Access Comparison

The table shows the gap: the most powerful version (CLI) is the least accessible—unless we bridge that gap.

🛠️ The Solution: A Self-Hosted Web Interface for the Q CLI

Seeing it in action: https://github.com/user-attachments/assets/99053791-17c5-4f09-bddb-d5b9ecd61cc0

My vibe-coded solution: Amazon Q Developer CLI WebUI—a bridge to the full CLI that runs in any modern browser. It wraps around the native q command, exposing its full feature set without needing a traditional terminal.

I started with telling Amazon Q Developer CLI "I want to re-create the Amazon Q Developer CLI experience in a web UI". Q came up with the plan and the initial tech stack, I iterated a few rounds with testings - in less than an hour, my final solution came:

Tech Stack:

• Backend: Node.js, Express
• Real-Time Communication: socket.io
• Terminal Emulation: node-pty for spawning a real pty

The result? A fluid, interactive CLI experience from a browser—even on mobile.

🚀 Getting Started

Make sure you have Amazon Q Developer CLI installed.

git clone --depth 1 https://github.com/gabrielkoo/amazon-q-developer-cli-webui
cd amazon-q-developer-cli-webui
npm install
q login && npm start  # —-host 0.0.0.0
#
# > [email protected] start
# > node server.js
#
# Server running on http://localhost:3000

🌐 Making Web UI Available On Your Mobile

Use any of the typical homelab methods to expose localhost:3000 online:

• 🌍 TailScale
• ☁️ CloudFlare Tunnel
• 🚪 Ngrok
• 🔐 Open port 3000 + IP Whitelisting

The first two options are preferred if you care very much about security.

📲 Unlocking a Truly Mobile Workflow

Let’s revisit the homelab scenario. You’re reviewing a Python script that needs a fix.

• Before: You’d struggle with a mobile SSH app, fighting to type commands.
• After: You just open a browser tab to your WebUI. Type: "Review fix_script.py, identify bugs, and suggest improvements." Copy, paste, and interact—touch-friendly and frustration-free.

Live demo: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2z9oxc4bm8waeor2nriy.gif

✨ More Than a Wrapper: An Enhanced User Experience

I focused on authenticity and comfort, solving the mobile pain points:

• 📝 Proper Input: A real multiline <textarea> makes command editing natural.
• 💬 Streaming Token Display: Outputs appear with a "typing" effect, just like the CLI.
• 🎨 Full ANSI Support: Colors, bolding, and formatting are preserved for readability.
• 🤖 Let Q Work for You: Don’t sweat every keystroke—Amazon Q can fix and run code for you.

This project was born from a simple need: use my favorite tools anywhere. It’s about unlocking the full power of Amazon Q, even far from a real keyboard.

🔗 Check it out here: https://github.com/gabrielkoo/amazon-q-developer-cli-webui