gentui 0.1.4

---

Get started

pip install gentui                               # or: uv tool install gentui
gentui http://localhost:8000/agent               # your AG-UI endpoint

Requires Python 3.12 or newer. No backend yet? See the Quick start for a sample agent.

Key features

🔌 Bring any agent Speaks AG-UI, so any compatible backend works: local, hosted, or on Amazon Bedrock AgentCore.	💬 Streaming chat Markdown answers stream in as they are written. Unknown tools show as a readable card, never an error.
🧠 Visible chain of thought Reasoning streams into a collapsible "Thought for 3s" block. Open it or tuck it away.	✋ Human-in-the-loop Approve, edit or reject before anything runs. Built on AG-UI interrupts: the model can't approve itself.
📊 Generative widgets Tool calls become the UI: command cards, output, tables, terminal charts and a live plan checklist.	🎬 Demo mode gentui --demo plays a tour of every feature by itself. No backend needed.
⏺ Record and replay Save a session to JSON with --record, then replay it with pause, a seek bar and speed control.	🛠 Built for developers A raw event inspector (/dev), /export_md, themes, hot-reloaded CSS and Python plugins.

Try the demo

No backend needed. Gentui plays a tour of every feature by itself, like a movie:

gentui --demo                # a menu: pick what to watch
gentui --demo all            # the whole movie
gentui --demo approval       # one scene: chat, approval, widgets or devtools
gentui --demo all --demo-speed 2    # twice as fast

Inside the demo, /demo <scene> switches scene and /quit leaves. Nothing is sent anywhere.

Record and replay

Save a session, then play it back anywhere: no agent, no network.

gentui http://localhost:8000/agent --record my_session     # saves my_session.json
gentui --replay my_session                                 # plays it back

In a replay: space pauses and plays, drag the bar (or ←/→) to fast-forward and rewind, +/- changes the speed, t opens or closes every chain of thought (you can also click one), d shows the raw events, q quits. Tool calls, the plan, tables, charts and approvals are drawn exactly as they were live. See Record and replay.

Why Gentui?

Gentui is a terminal interface for prototyping agents really quickly.

While developing agents locally, we end up spending our time on the frontend: a Streamlit or Chainlit app, or a React project, just to talk to the agent. Each one is a separate frontend to build and keep running, and it slows down the thing you actually want to iterate on: the agent.

Gentui removes that step. Install it, point it at your agent's AG-UI endpoint, and you get a chat, the model's chain of thought, human-in-the-loop (HITL) and approval flows out of the box, with no frontend code to write. Change your agent, restart it, and you're prototyping again in seconds.

When the agent calls a tool, the tool call becomes the UI: a command to approve, a table, a chart, a live plan. Nothing risky runs until you click Approve.

Tested with the Strands Agents framework (AWS's open-source agent SDK) over AG-UI: both on a custom backend (the example backend) and on the official ag-ui-strands adapter.

Features

• Works with any AG-UI backend. Streaming text, tool calls and shared state work out of the box; unknown tools show as a readable card, never an error.
• Chain of thought, visible. Reasoning streams into a collapsible "Thought for 3s" block.
• Human-in-the-loop approval built on AG-UI interrupts: the run ends waiting, your click resumes it. The model can't approve its own commands.
• Generative widgets from tool calls: command card, command output, tables, terminal charts (line, bar, scatter, histogram), live plan checklist.
• Developer-friendly: an event inspector (/dev) showing the raw SSE payloads exactly as sent, /theme, /clear, /reasoning, and a clear backend contract.
• Record and replay. --record name saves a session to JSON; --replay name plays it back with pause, a seek bar and speed control.
• Yours to customise: TOML config, hot-reloaded CSS, your own themes, and Python plugins that add widgets, slash commands and event hooks.
• Runs agents on AWS too: invoke agents hosted on Amazon Bedrock AgentCore Runtime (AG-UI protocol) via boto3.
• Backend-agnostic by design. The client has no framework code; a complete example backend lives in examples/strands-backend.

The sample agent: natural language → shell

The command-approval flow in the tour above comes from the bundled example backend, a natural-language-to-shell agent built on Strands Agents. You describe a task in plain English, it proposes a single shell command, and nothing runs until you approve it.

1. Ask: "what are the 5 largest files here?"
2. Review: a shell sub-agent writes one command for your shell (bash, or PowerShell on Windows) with a one-line explanation and a risk level: safe, caution or dangerous.
3. Decide: Approve, Edit the command first, or Reject. Your decision is sent back as an AG-UI resume; the model can't approve for itself or change the command.
4. Run: only the approved command executes, with a timeout, an output cap and a fixed working directory. A denylist (recursive delete of root or home, disk formatting, shutdown, fork bombs, interactive programs) is checked at proposal, at approval and again right before running. It is a safety net, not a sandbox.

The same agent can also show results as a table or chart, lay out multi-step work as a live plan, explain what a command does (an explainer sub-agent), and keep long-term memory between conversations. It's a worked example of the backend contract: copy it, or add your own tools with this guide.

Quick start

Requires Python 3.12 or newer. Gentui is on PyPI:

pip install gentui                               # or: uv tool install gentui
gentui http://localhost:8000/agent               # your AG-UI endpoint

With uv you can also run it without installing: uvx gentui http://localhost:8000/agent.

No backend yet? Run the sample natural-language-to-shell agent (Strands Agents + FastAPI). It lives in this repository, so clone it first, then start the backend in one terminal. It uses a local Ollama by default; see its README for other providers:

git clone https://github.com/rahrajlat/Gentui.git
cd Gentui/examples/strands-backend
uv sync && cp .env.example .env
uv run server                                     # http://localhost:8000/agent

Then, in another terminal, start Gentui as above (gentui http://localhost:8000/agent).

Type /help to list the slash commands (/new, /export_md, /theme, /dev, /reasoning, /quit). Working on Gentui itself? Run it from a clone with uv sync and uv run gentui <url>.

Documentation

I want to…	Read
use the slash commands, export a chat	Slash commands
set options, themes, CSS, auth, map my own widgets	Configuring and customising (all options: gentui.example.toml)
add widgets, commands or event hooks	Plugins
build my own backend in any language	Backend contract
talk to an agent on Amazon Bedrock AgentCore	AgentCore Runtime
record a session and play it back	Record and replay
understand the internals	How it works
cut a release	Releasing

Example: an agent on AgentCore Runtime

Your runtime must be deployed with the AG-UI protocol. Then, end to end:

# 1. install with the optional AWS extra (adds boto3)
pip install "gentui[agentcore]"          # or: uv tool install "gentui[agentcore]"

# 2. log in with any normal AWS method
aws sso login --profile dev              # or export AWS_PROFILE / access keys

# 3. pass the runtime ARN instead of a URL
gentui arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my_agent-AbCdEfGhIj --profile dev

Optional flags: --region eu-west-1 (default: the region in the ARN) and --qualifier prod (default: the DEFAULT endpoint). Or put it in gentui.toml and just run gentui:

agentcore_arn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my_agent-AbCdEfGhIj"
aws_profile = "dev"
send_history = true      # needed if the runtime rebuilds context from messages (e.g. ag-ui-strands)

The caller needs the bedrock-agentcore:InvokeAgentRuntime permission. IAM details, sessions and troubleshooting are in the AgentCore guide.

Status

Gentui is alpha. What has been verified, and what has not:

• Built and tested against the Strands Agents framework (AWS) over AG-UI: the example backend and the official ag-ui-strands adapter (with send_history = true).
• AgentCore Runtime support works against a real runtime (confirmed by the author with a plain runtime ARN) and only covers runtimes using the AG-UI protocol. Other setups are covered by tests with a fake boto3 client and botocore's Stubber.
• Backends on other frameworks, the interrupt flow against a backend other than the example, other model providers than Ollama, and native Windows are untested.
• The look relies on Unicode box-drawing and block characters. If glyphs are missing, try a terminal font such as DejaVu Sans Mono, Cascadia or JetBrains Mono.

Ideas, not built yet: show_form / ask_approval tools, a composable JSON-tree UI tool, persistent threads.

Development

uv run pytest -q                                   # TUI tests: headless, no LLM or backend needed
cd examples/strands-backend && uv run pytest -q    # the example backend's own tests

The images above are generated from the app's own code: uv run --with pillow python docs/assets/build_assets.py (logo, hero, demo.gif) and uv run --with pillow python docs/assets/build_tour.py (the feature tour).

Contributing

Issues and pull requests are welcome. Please run both test suites before opening a PR, and add a test with any behaviour change. Because Gentui is a client for an open protocol, changes that keep it backend-agnostic are the easiest to accept.

License

MIT. Free to use, modify and distribute, including the example backend.