Hagent – Cliente TUI para Agentes Hadrian
hadriangateway/hagent
Cliente TUI lean para agentes Hadrian com MCP e busca web integrados
Ver no GitHubCliente terminal fino (TUI) em Rust para a API OpenAI-compatível do Hadrian, permitindo interação com agentes server-side que executam ferramentas como shell, busca web e MCP. O Hagent gerencia aprovações MCP, autenticação OAuth e mantém histórico de conversas, renderizando markdown com syntax highlighting no terminal nativo.
Instalação
npx convez-ai hadriangateway/hagent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Interagir com agentes agentic server-side via terminal
- Executar tarefas com shell, busca web e file search remotos
- Gerenciar aprovações de MCP servers e autenticação OAuth
- Manter histórico persistente de conversas com compactação de contexto
Veredito

Hagent é uma implementação elegante e bem arquitetada de um cliente agentic minimalista: mantém inteligentemente a lógica server-side enquanto resolve o essencial no cliente (MCP approval, OAuth). Ideal para quem quer explorar agentic loops sem overhead local, mas requer Hadrian rodando como backend.
README
A tradução para o português deste README ainda está na fila.
hagent
A thin terminal agent client (TUI) for
Hadrian's OpenAI-compatible
/v1/responses API, in the Codex / Claude Code style.
Hadrian runs the entire agentic loop server-side: it executes the
shell, web_search, file_search and mcp tools (in containers, with
mountable skills), keeps conversation history when store: true, and performs
context compaction. So hagent is genuinely thin. It streams the response,
renders it, keeps a single previous_response_id between turns, and handles
the few interactive things the server can't: MCP approval requests and
OAuth login for remote MCP servers.
It deliberately does not use the client_passthrough shell runtime, so the
client executes nothing locally.
Layout
hagent-core: protocol wire types, the SSE client, the conversation state machine, config, conversation logging, the bundled file-editing skill, and remote-MCP support (OAuth). No terminal dependencies; fully unit-tested.hagent: the Ratatui TUI. AnAppEventevent loop, a per-turn network task, a vendored inline-viewport terminal, and the renderer (Markdown plus syntax highlighting).
Usage
# Interactive TUI
HAGENT_API_KEY=gw_... hagent --model gpt-5.2
# Against a local dev Hadrian with `auth.mode = none` (no key needed)
hagent --model gpt-5.2
# One-shot headless (streams to stdout, no TUI)
hagent --model gpt-5.2 -p "Summarize the CSV in /mnt/data"
# Resume a previous conversation (by id, or the most recent one)
hagent --resume <id>
hagent --continue
The TUI renders the transcript into the terminal's native scrollback (it stays on the primary screen and does not capture the mouse), so you scroll and select/copy history with your terminal's own controls. The composer grows as you type and collapses large pastes to placeholders.
Configuration
Precedence (highest first): CLI flags, then env vars, then
config.toml, then built-in defaults.
| Setting | Flag | Env | Default |
|---|---|---|---|
| Base URL | --base-url | HAGENT_BASE_URL | http://localhost:8080/api |
| API key | --api-key | HAGENT_API_KEY | (none; omits the auth header) |
| Model | --model | HAGENT_MODEL | gpt-5.2 |
| Tools | --tools | (n/a) | all tools |
| Reasoning effort | --reasoning-effort | HAGENT_REASONING_EFFORT | high |
| Reasoning summary | --reasoning-summary | HAGENT_REASONING_SUMMARY | auto |
| Log dir | --log-dir | HAGENT_LOG_DIR | <cache>/conversations |
By default all server-side tools are enabled. Pass --tools shell,web_search
(or set tools = [...] in the config) to narrow the set, or --tools none
(tools = [] in the config) to disable them all. file_search is skipped unless
vector stores are configured, and mcp unless MCP servers are.
Other settings (MCP servers, vector stores, compaction, container reuse, the
system prompt) live in ~/.config/hagent/config.toml; see
config.example.toml and
.mcp.json.example.
Note on the base URL: Hadrian mounts its OpenAI-compatible API under
/api, so the OpenAI-style base URL is<host>:8080/api(the client appends/v1/responses). Inauth.mode = none, sending anyAuthorizationheader is rejected, sohagentomits the bearer when no key is configured.
Reasoning
Reasoning is on by default (effort = "high", summary = "auto"), so the
model's thinking shows dimmed in the transcript. Effort levels are
minimal | low | medium | high | xhigh | max | off (xhigh/max are the
adaptive Opus 4.7/4.8 plus GPT-5.x tiers above high; providers clamp
unsupported tiers down). Disable with --reasoning-effort off, the /effort
picker, or [reasoning] effort = "off".
Conversation logging & resume
On by default: each conversation writes its own directory under
<cache>/conversations/<id>/ containing log.ndjson (one redacted line per
request and response) and conversation.json (a resumable snapshot: chain
pointer, container, totals, transcript). Resume the chain with --resume <id>
(the directory name) or the most-recent one with --continue. On exit, hagent
prints a one-line usage summary and the exact command to resume the session.
Disable logging with --no-log-conversations or [logging] enabled = false.
--debug / HAGENT_DEBUG=1 turns off log redaction (writes the API key and
MCP bearers verbatim, for debugging auth only); it is distinct from
HAGENT_LOG, which sets the tracing level.
File-editing skill (bootstrap)
Hadrian executes the shell tool but exposes no first-class file-edit tool, so
hagent ships a small file-editing skill (view/create/str-replace/
insert, rendered as coloured diff blocks). The first time you use a server
with shell enabled, hagent offers a one-time bootstrap panel to upload and
activate it; the resulting skill id is cached per server in config.toml.
Suppress the offer with --no-bootstrap; force a re-upload (e.g. after the skill
changes) with --force-bootstrap or /bootstrap.
MCP servers & authentication
Remote (Streamable HTTP) MCP servers come from ./.mcp.json (Claude-Code
project scope) and config.toml [[mcp_servers]], merged by label
(config.toml wins). Auth kinds are none, bearer, header, and oauth.
OAuth discovery (PRM/AS metadata, dynamic client registration, PKCE) is done by
hagent directly against the MCP server; only the resulting bearer is handed
to Hadrian, and it is re-sent every turn. Tokens persist in the OS keychain
(with an owner-only file fallback).
Manage servers from the shell:
hagent mcp list
hagent mcp login <label>
hagent mcp logout <label>
hagent mcp add <url> [label] [--to project|user]
In the TUI, /mcp opens an interactive menu (log in / out, add a server).
Mid-turn, an unauthenticated OAuth server prompts a login panel; tool calls that
need approval show an inline approve / deny panel.
Keys
- Enter: send. Shift+Enter / Alt+Enter: newline
- Esc: cancel the in-flight turn, or close the slash-command popup
- Ctrl-C / Ctrl-D: quit (press twice within 2s; a single Ctrl-C cancels a streaming turn)
- Ctrl-U: delete from the cursor to the start of the line
- Ctrl-L: clear the screen and jump the composer to the top
- Ctrl-G: edit the composer in
$EDITOR - Ctrl-T: toggle the detailed token / cost breakdown in the status line
- Up / Down: recall prior prompts (gated to the composer's first/last line)
/: open the slash-command popup (/resume,/rewind,/clear,/model,/effort,/server,/settings,/bootstrap,/mcp,/reasoning,/output)- Type while a turn streams to queue follow-up messages
- In an MCP approval panel: a approve, d deny
- In the bootstrap / MCP-login panel: y accept, n skip
Scrollback and text selection are native: use your terminal's own scroll and mouse; hagent does not capture the mouse.
Development
cargo test # unit tests (protocol, state machine, render, input)
cargo clippy --all-targets
cargo fmt
cargo run -p hagent -- -p "hello" # headless smoke
Logs go to ~/.cache/hagent/hagent.log (TUI mode owns the terminal); set
HAGENT_LOG=debug to raise the level.
License
Dual-licensed under Apache 2.0 and MIT.