A sleek, terminal‑native autonomous coding agent – built in Go, runs locally.
OpenX is a local AI developer runtime that turns natural‑language goals into executable tool calls.
It uses a strict text‑based tool‑calling protocol (no JSON hacks), works with any OpenAI‑compatible endpoint (llama.cpp, Ollama, etc.), and comes with a gorgeous interactive TUI (optional).
- Demo
- Why OpenX?
- Architecture
- Installation
- Quick Start
- Headless Mode
- Interactive TUI
- Tool System
- Configuration
- Development
- Roadmap
- Contributing
- License
$ openx "create a Go HTTP server that listens on port 8080 and returns 'hello'"
--- LLM response ---
TOOL: write_file
path: server.go
content:
package main
...
END
Executing: write_file ...
Result: wrote 271 bytes to server.go
--- LLM response ---
TOOL: finish
END
Goal achieved.$ openx
(place a screenshot here)
- Deterministic & observable – Every LLM response maps to a tool call or a finish signal. No hidden magic.
- No JSON hacks – Uses a custom line‑oriented protocol (
TOOL: … END) that works reliably even with 1B–3B models. - Local first – Connects to any
llama.cppserver or OpenAI‑compatible API. Model‑agnostic. - Tiny footprint – Single Go binary, no Python virtual env mess.
- Beautiful TUI – Built with Bubble Tea, featuring a Sixel image logo, spinner, and scrollable logs.
- Safe – Command timeout, allow‑list, and no
go run/./serverby default.
User (CLI or TUI)
│
▼
Engine Loop
(orchestrates steps,
maintains conversation)
│
┌────┴────┐
▼ ▼
LLM Tool Registry
(HTTP) (files, shell, etc.)
User Goal ──► Prompt Builder ──► LLM (llama.cpp)
│
Tool Call (plain text)
│
Parser (line‑based)
│
Tool Execution
│
Result ──► State Update
│
Repeat until `finish`
┌─────────────────────┐
│ Engine.Run(goal) │
└──────────┬──────────┘
│
┌───────▼────────┐
│ Build system │
│ prompt + tools │
└───────┬────────┘
│
┌───────▼────────┐
│ Send to LLM │◄── conversation history
└───────┬────────┘
│
┌───────▼────────┐
│ Parse raw text │
│ (TOOL: … END) │
└───────┬────────┘
│
┌───────▼────────┐
│ Execute tools │──► ToolResult
└───────┬────────┘
│
┌───────▼────────┐
│ Append feedback│
│ to history │
└───────┬────────┘
│
▼
finish? ──► yes ──► done
│
no
│
└──────► loop again
┌──────────────────────────────────────┐
│ Sixel Logo + ASCII "OPENX" │
├──────────────────────────────────────┤
│ Text input area ("Enter goal…") │
├──────────────────────────────────────┤
│ Scrollable log viewport │
│ ▸ user goal │
│ Tool: write_file ... │
│ Result: wrote ... │
│ ✅ Done. │
├──────────────────────────────────────┤
│ Status: Ready (or spinner) │
└──────────────────────────────────────┘
- Go 1.21+
- A running llama.cpp server (or any OpenAI‑compatible endpoint) with tool‑calling support. For local models, use:
llama-server -m your-model.gguf --port 8080
- (For TUI images) iTerm2 or any terminal that supports Sixel.
git clone https://github.com/yourusername/openx.git
cd openx
go build -o openx .
sudo mv openx /usr/local/bin/Or using go install:
go install github.com/yourusername/openx@latestMake sure $GOPATH/bin is in your PATH.
- Start your LLM server (e.g., llama.cpp on port 8080).
- Run OpenX in headless mode:
openx "create a file hello.txt with 'Hello, OpenX' inside" - Check the result:
cat hello.txt
You can use OpenX as a one‑shot CLI tool. The agent will execute tool calls until the task is done and then exit.
# Simple file generation
openx "write a Python script that prints today's date"
# Multi‑step project scaffolding
openx "create a REST API with Go, using gorilla/mux, with two endpoints: /users (GET) and /health"All tool calls and their results are printed to stdout. The engine stops when the LLM emits TOOL: finish.
Launch the TUI simply by typing openx (no arguments). You’ll enter a full‑screen terminal interface with:
- Image logo (if you placed
openx.pngin the build directory) – displayed via Sixel. - Text input – type your goal and press Enter.
- Live log – tool calls, results, and errors appear in real‑time.
- Session memory – the agent remembers the entire conversation, so you can issue follow‑up commands.
| Key | Action |
|---|---|
Enter |
Send current goal |
Ctrl+C |
Quit |
| Input is disabled while the agent is processing. |
(Insert a screenshot here)
OpenX uses a strict TOOL: … END text protocol. The LLM must output exactly that format, and the parser extracts tool name and arguments.
| Tool | Arguments | Description |
|---|---|---|
write_file |
path, content (multiline) |
Create or overwrite a file |
read_file |
path |
Return file contents |
edit_file |
path, old, new |
Replace first occurrence of old with new |
list_dir |
dir (optional) |
List files in directory (default .) |
search_content |
pattern, path |
Grep for pattern in file/directory |
run_command |
command |
Execute a shell command (allow‑listed: go, ls, cat, grep, etc.) |
finish |
none | Signal task completion |
Commands are blocked if they try to start long‑running processes (go run, ./server). A 5‑second timeout prevents hangs.
TOOL: write_file
path: main.go
content:
package main
import "fmt"
func main() { fmt.Println("hi") }
END
Multiple tool calls in one response are separated by blank lines.
Invalid calls trigger a feedback loop: the engine asks the model to retry with correct formatting.
| Variable | Default | Description |
|---|---|---|
LLM_ENDPOINT |
http://localhost:8080/v1 |
Base URL of your OpenAI‑compatible API |
LLM_MODEL |
local-model (hardcoded in engine) |
Model name to send in API requests |
You can change the model name in engine.go or via an env var if you add that (modify llm.go to read LLM_MODEL).
openx/
├── main.go # entry point (CLI / TUI switch)
├── engine.go # agent loop + conversation management
├── llm.go # HTTP adapter for OpenAI‑compatible endpoints
├── parser.go # deterministic text protocol parser
├── tools.go # tool registry + execution
├── tui.go # interactive Bubble Tea interface
├── go.mod
└── openx.png # (optional) logo for TUI
Everything lives in the root – no cmd/, no internal/. This keeps the project small and easy to understand.
- Add a case to
ExecuteToolFromCallintools.go. - Document the tool in the system prompt inside
engine.go. - If it’s a dangerous command, update the
allowedCommandslist.
Currently manual; you can add go test later once the engine is decoupled.
go build -o openx . && sudo mv openx /usr/local/bin/- Autonomous file creation & editing
- Shell command execution (safe subset)
- Multi‑turn conversation in TUI
- Sixel logo support
- Context compression for long sessions
-
edit_filewith diff‑based patching - Git integration (
git commit,git log) - Model switching via environment variable
- Web‑based TUI alternative
Pull requests are welcome!
Please keep the code minimal, deterministic, and aligned with the Core Principles.
If you add a tool, remember to update the system prompt and safety checks.
MIT – do what you want, just keep the attribution.
- Bubble Tea – TUI framework.
- go‑sixel – Sixel encoding.
- The local LLM community for llama.cpp and GGUF.
---
This README covers everything: architecture diagrams (both ASCII and Mermaid-compatible text), code snippets, installation, usage for both headless and TUI, tool reference, configuration, and development guide. It's ready to be placed in your repo.
You can add a real screenshot of the TUI in the `docs/` folder and link it where indicated. Let me know if you'd like me to generate the Mermaid diagrams as actual SVG or refine any section further.