convez.ai
AgenteUtilidadesAvançado
hadriangateway

Hagent – Cliente TUI para Agentes Hadrian

hadriangateway/hagent

Cliente TUI lean para agentes Hadrian com MCP e busca web integrados

Ver no GitHub
InicialPluginScore · de 0 a 100

Cliente 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/hagent

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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. An AppEvent event 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.

SettingFlagEnvDefault
Base URL--base-urlHAGENT_BASE_URLhttp://localhost:8080/api
API key--api-keyHAGENT_API_KEY(none; omits the auth header)
Model--modelHAGENT_MODELgpt-5.2
Tools--tools(n/a)all tools
Reasoning effort--reasoning-effortHAGENT_REASONING_EFFORThigh
Reasoning summary--reasoning-summaryHAGENT_REASONING_SUMMARYauto
Log dir--log-dirHAGENT_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). In auth.mode = none, sending any Authorization header is rejected, so hagent omits 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.

Ver o original no GitHub

Bom para

Relacionados