Overview

z2e-terminal is an autonomous AI agent TUI built with Go and Bubble Tea. It accepts natural-language missions, plans and executes multi-step CLI actions autonomously, observes output, reasons, and iterates until the objective is reached or runtime limits are hit.

Current Version

v0.2.4

Core Architecture

Agent Loop

The core loop is Plan → Execute → Observe → Replan:

1. LLM Turn: Send conversation to the model via SSE streaming (up to 3 total attempts per step)
2. Aggregate: Collect tool_calls from stream fragments
3. Emit: Stream assistant response to TUI
4. Execute: Run each tool call via bash -lc
5. Observe: Package output as z2e.tool_observation.v1 and append to chat
6. Replan: Repeat until final answer, max steps (30), doom-loop, empty-turn, or error

Safety Guards

• Max tool steps: 30
• Doom-loop detection: 3 identical command signatures in a row
• Max empty turns: 2
• Max LLM retries: 2 per step
• Command timeout: 60s default, 10 min max
• Output cap: 64KB

Features

• Autonomous agent loop: Plan → Execute → Observe → Replan
• Tool execution: bash / run_command tools (pure pass-through policy)
• Streaming output: Real-time SSE streaming from OpenCode Go gateway
• Markdown rendering: glamour for terminal markdown display
• Runtime model switching: /model command
• LLM retry with backoff: Up to 2 retries per step, exponential backoff with jitter at the gateway level
• Security-oriented system prompt: Built-in pentesting and CTF persona
• Session debug snapshots: /tmp/z2e-terminal/session.json

Model Catalog

8 models available through the OpenCode Go gateway, configured in internal/llm/gateway/models.json:

Default model: opencode-go/deepseek-v4-pro

Environment

Codebase

• Go: ~3,200 LOC across cmd/ + internal/
• Dependencies: bubbletea, bubbles, glamour, lipgloss, godotenv