An interactive AI coding assistant in the command-line interface (CLI / Shell) for Commodore Amiga (in the style of Claude Code / Gemini CLI / Aider), running directly on the Amiga within the NodeAmiga JavaScript runtime and communicating with a local Ollama instance on a host PC via a lightweight dedicated Node.js bridge.
Enables interactive pair programming directly on AmigaOS (C, Motorola 680x0 Assembler, ARexx, Amiga E, AmigaDOS batch scripts):
- π File Reading from any Amiga volume or device (
RAM:,DH0:,SYS:,DEV:) - βοΈ File Creation & Editing (full write or surgical search-and-replace
patch) - β‘ AmigaDOS Command Execution (SAS/C, VBCC, GCC compilers, scripts, diagnostic commands)
- π€ Agentic Loop β AI inspects files, plans multi-step fixes, and executes tools with safety approval (
[Y/n]prompts, SMART risk assessment, or unrestricted AUTO mode) - π§ Reasoning & Thinking Models β Full support for thinking models (DeepSeek-R1, Qwen 2.5/3.x) with an in-place compact Amiga console spinner
- πΎ Persistent Configuration β Runtime setting changes (
/host,/model,/mode,/encoding, etc.) automatically save toamai.config.json - π₯οΈ WinUAE Automation & Vision β Dedicated Python controller (
pc/winuae.py) for AI agents with pixel-accurate screenshots, keystroke injection, and mouse automation - π¦ Standalone Executable Compilation β bundle into a single self-contained Amiga binary (
NodeAmiga -compile amai amai.js) that runs independently without NodeAmiga or external libraries.
Note
Early Development Preview: AMAI is currently in early, active development. While core features and tool calling are functional, you may encounter occasional quirks, connection hiccups, or edge-case bugs. Please report issues and feedback on the GitHub Issue Tracker.
amai/
βββ CHANGELOG.md # Project version changelog (Keep a Changelog standard)
βββ pc/ # Host PC Bridge & Automation Tools
β βββ server.js # HTTP/TCP streaming server connecting to Ollama & Cloud providers
β βββ .env.example # Example configuration for API keys (Gemini, OpenAI, OpenRouter)
β βββ providers/ # Universal LLM provider adapters:
β β βββ index.js # Unified provider dispatcher
β β βββ models.js # Dynamic model discovery & noise filtering
β β βββ ollama.js # Native Ollama streaming client
β β βββ openai.js # OpenAI-compatible streaming client (Gemini, OpenAI, OpenRouter)
β βββ local_vision.py # Local vision agent (Qwen 3.8 via Ollama) for WinUAE OCR & error check
β βββ winuae.py # WinUAE emulator automation CLI (screenshots, vision, keyboard, mouse)
β βββ requirements.txt # Python dependencies for WinUAE automation (Pillow)
β βββ package.json # Node.js project manifest
βββ amiga/ # Amiga Client
β βββ bin/ # Pre-compiled NodeAmiga runtime binaries & compiled AMAI:
β β βββ amai # Standalone native Amiga executable (Universal 68000/68010)
β β βββ amai.config.json # Configuration file
β βββ amai.readme # Aminet-compliant package readme
β βββ src/ # AMAI Source Code for NodeAmiga:
β βββ amai.js # Main CLI entry point script
β βββ amai.config.json # Configuration file (host, port, model, safety mode, encoding, timeout)
β βββ lib/ # Client modules:
β βββ ansi.js # ANSI console color & line control for Amiga Shell
β βββ config.js # Configuration loader & persistent saver
β βββ network.js # TCP socket streaming client with thinking & token events
β βββ repl.js # Interactive REPL prompt, compact spinner, and agent loop
β βββ tools.js # Tool execution engine (read, write, patch, dir, cwd, shell)
β βββ version.js # Dynamic release version string
βββ tools/
β βββ build_amiga.py # Standalone cross-compiler & .lha release packager
βββ .agents/skills/ # Agent skills (release, winuae, local-vision)
βββ start_bridge.bat # Single-click launcher for the PC bridge on Windows
βββ start_bridge.sh # Launcher for Linux and macOS
AMAI communicates with local or cloud AI models via a lightweight Node.js bridge server:
Install Ollama and pull your preferred model:
ollama run qwen3.8:latestConfigure your API keys in pc/.env:
cp pc/.env.example pc/.envEdit pc/.env and set your credentials:
DEFAULT_MODEL=gemini-flash-latest
GEMINI_API_KEY=your_gemini_api_key
OPENAI_API_KEY=your_openai_api_key
OPENROUTER_API_KEY=your_openrouter_api_key- Windows:
start_bridge.bat
- Linux / macOS:
chmod +x start_bridge.sh ./start_bridge.sh
- Any OS (command line):
node pc/server.js
The bridge listens on port 11435 across all network interfaces (0.0.0.0):
- For WinUAE: connects via
127.0.0.1:11435 - For real Amiga hardware: connects to your PC's LAN IP address (e.g.
192.168.1.16:11435)
The bridge automatically logs loaded configuration, active providers, and available models on startup. It transparently handles:
- NDJSON event streaming with keepalive heartbeats
- Thinking/reasoning tag filtering (
<think>...</think>andmsg.thinking) - Google Gemini
thought_signaturepreservation across multi-turn tool calling - Model grouping, provider filtering, and Topaz-safe noise reduction
- Transparent character transliteration (ASCII, AmigaPL, ISO-8859-2)
- Session cancellation (
/abort) and error propagation
- WinUAE Configuration:
- Hardware -> Expansions / Network: enable
bsdsocket.libraryemulation (bsdsocket_emu=true). - Hardware -> Memory: recommended 8 MB Fast RAM (
fastmem_size=8). - Host -> Hard drives: mount the repository directory as a hard drive directory (e.g. Device:
DEV:, Volume:amai). - Host -> Game ports (Recommended for mouse automation): in Mouse extra settings, set Mouse untrap mode to Magic mouse (or enable Install virtual mouse driver).
- Hardware -> Expansions / Network: enable
- Boot your Amiga workbench in WinUAE and open a Shell window.
- Start AMAI:
or directly with options:
cd DEV:amiga/bin amaiDEV:amiga/bin/amai -h 127.0.0.1 -m gemini-flash-latest
- Verify that your Amiga has an active TCP/IP stack (Roadshow, AmiTCP, Miami, ImpBox) with working
bsdsocket.library. - Copy the
amiga/bincontents to your Amiga storage (e.g.DH0:Tools/amai/). - Set your PC's local IP address in
amai.config.json(e.g."host": "192.168.1.16"), or pass it via CLI argument:bin/amai -h 192.168.1.16 -m qwen2.5:latest
- Download NodeAmiga from https://juen.in/ or https://aminet.net/package/dev/lang/NodeAmiga. Unpack and get binaries in PATH
- Compile directly on Amiga:
cd amai NodeAmiga -compile amiga/bin/amai amiga/src/amai.js - Or build standalone binaries (68000, 68020, 68040, 68060) and
.lhaarchive using the cross-builder:(This script automatically fetches NodeAmiga from Aminet if not present and packages standalone Amiga executables andpython tools/build_amiga.py --version v1.0.0
.lhafor GitHub Releases).
During an interactive session at the [SMART] DEV:amiga > prompt, the following commands are available:
| Command | Description | Auto-Saved? |
|---|---|---|
/help |
Display list of available commands and usage guide | - |
/status |
Check connection to PC bridge; auto-discovers PC LAN IP if 127.0.0.1 fails | Yes |
/host [ip[:port]] |
Set bridge IP address and optional port (e.g. /host 192.168.1.16:11435) |
Yes |
/port [number] |
Change bridge port (e.g. /port 11435) |
Yes |
/model [name|prov] |
Show/switch model, or filter by provider (local, google, openai, openrouter) |
Yes |
/mode [smart|manual|auto] |
Set safety approval mode: smart (default), manual, or auto |
Yes |
/auto [on|off] |
Quick toggle between AUTO mode and SMART mode | Yes |
/encoding [mode] |
Set character encoding: ascii, amigapl, iso-8859-2, raw |
Yes |
/timeout [seconds] |
Set connection timeout in seconds (e.g. /timeout 120) |
Yes |
/debug [on|off] |
Toggle verbose diagnostic logging | Yes |
/save [file] |
Explicitly write current runtime configuration to file | - |
/read <path> |
Read Amiga file directly into conversation context (e.g. /read RAM:main.c) |
- |
/run <command> |
Run AmigaDOS command directly (e.g. /run dir RAM:) |
- |
/cd [dir] |
Inspect or print current working directory | - |
/clear |
Clear conversation history and reset context | - |
/exit or /quit |
Exit AMAI Shell | - |
Tip
Configuration Auto-Persistence: Any modification made via slash commands during the session is immediately written to src/amai.config.json (or PROGDIR:amai.config.json / ENV:), ensuring settings persist across restarts and reboots.
AMAI includes a dedicated automation CLI tool for Windows to control and inspect a running WinUAE emulator session directly from scripts or AI agents:
# 0. Install Python dependencies (Pillow for screenshot capture)
pip install -r pc/requirements.txt
# 1. Take a screenshot for vision analysis
python pc/winuae.py screenshot current_screen.png
# 2. Type text into the active Shell / editor (with CIA-safe timings)
python pc/winuae.py type "dir RAM:" --enter
# 3. Send special keys
python pc/winuae.py key enter
python pc/winuae.py key esc
python pc/winuae.py key f12 # Open WinUAE Settings GUI
python pc/winuae.py key ctrl+c # Interrupt running program
python pc/winuae.py key execute # Open Workbench 'Execute Command' (Right Amiga + E)
python pc/winuae.py key reset # Hard reset Amiga (Ctrl + L-Amiga + R-Amiga)
# 4. Pixel-accurate mouse clicks (aligned 1:1 with screenshot coordinates)
python pc/winuae.py click 215 310
python pc/winuae.py click 215 310 --double
python pc/winuae.py click 400 200 --button right
# 5. Drag & Drop / Amiga Intuition pull-down menus
python pc/winuae.py drag 50 10 50 80 --button right
# 6. Relative mouse movement (hardware mickeys)
python pc/winuae.py move 50 -20
# 7. Window management
python pc/winuae.py status
python pc/winuae.py focusKey Features of the Controller:
- Per-Monitor DPI Aware: Guarantees that coordinates measured on screenshots match physical desktop clicks 1:1, regardless of Windows display scaling (125%, 150%, 200%).
- Window Identification: Accurately targets the emulator window (
PCsuxRox/AmigaPowahwindow class) and prevents accidental input to code editors (e.g. VS Code). - DirectInput / SendInput: Uses native Windows
SendInputstructures for reliable input delivery to retro emulators.
AMAI equips the LLM with a suite of tools tailored for AmigaOS development:
read_file(path)β Read files from any Amiga path (includes a 16 KB memory protection cap).write_file(path, content)β Create or overwrite files on Amiga storage.patch_file(path, search, replace)β Precise block replacement for surgical code editing.list_dir(path)β Inspect directories and volume contents.get_cwd()β Retrieve current working directory path.run_command(command)β Execute arbitrary AmigaDOS shell commands viachild_process.execSync(e.g.vc -c file.c).launch_workbench_app(app_path, [args])β Launch GUI/Workbench applications in the background usingWBRun(e.g.SYS:Tools/Clock,SYS:Utilities/Calculator). Requires WBRun installed inC:.cpu([args])β Query Amiga CPU, FPU, MMU, and cache configuration via AmigaDOScpucommand (e.g. 68000, 68020, 68030, 68040, 68060).
smart(Default): Automatically approves safe read-only operations (read_file,list_dir,get_cwd,cpu, safe GUI launches), but prompts the user for confirmation[Y/n]before modifying files or executing shell commands.manual: Prompts the user before every single tool invocation.auto: Fully autonomous mode; executes all tool actions without prompting (recommended for trusted scripts).
Classic Amiga screens (PAL/NTSC Topaz 8 font) do not support UTF-8 characters natively. The PC bridge handles transparent transliteration according to the selected encoding mode:
ascii(Default): Converts Polish diacritics and special Unicode typography (curly quotes, dashes, bullets) to clean standard 7-bit ASCII equivalents.amigapl: Encodes characters according to the classic AmigaPL standard (Commodore Polish localized fonts).iso-8859-2: Standard Latin-2 encoding.raw: Passthrough without modification.
