agent

AI Agent Runtime on the BEAM
Multi-gateway, SQLite-backed, tool-augmented chat — built in Gleam on Erlang/OTP.

Documentation · Getting Started · Architecture · API Reference

Quick start

# Set your API key
echo 'DEEPSEEK_API_KEY=sk-...' > .env

# Run the CLI REPL
gleam run

# Run the daemon (Telegram bot + admin TCP listener)
gleam run -m agent_app

# Admin CLI (connect to running daemon)
gleam run -m agent_admin sessions list
gleam run -m agent_admin db stats

# Run tests
gleam test

Features

Chat & Gateways

• CLI REPL — interactive chat with approval-gated bash execution, admin slash commands
• Daemon mode — headless agent with Telegram bot and TCP admin interface
• Telegram gateway — real Telegram bot using telega’s OTP supervision tree

Tool System

• Bash — sandboxed shell execution with env clearing and background wrapper detection
• Web — URL fetching with SSRF-hardened DNS resolution and secret scanning
• Browser — Playwright automation (navigate, click, type, scroll, screenshot)
• Code — Python, Node, and Bash code execution
• Memory — SQLite-backed persistent memory with dedup, validation, and frozen snapshots
• Session Search — FTS5 full-text search across past conversations
• Cron — runtime-managed 5-field scheduler with create/list/update/delete tools
• Parallel execution — concurrent tool calls via Gleam/OTP processes

Persistence

• SQLite storage — WAL-mode with automatic NFS/SMB fallback
• FTS5 search — full-text search across all message content
• Token & cost tracking — per-session, per-model cost accounting
• Session lifecycle — resume, fork, prune, export, crash recovery, auto-titling

Safety & Autonomy

• Guardrails — circuit breaker with warn/block/halt escalation, idempotent no-progress detection
• Context compression — automatic middle-message summarization at 70% window fill
• Structured autonomy — Pulse time-driven tasks, Reflection memory consolidation, Cron scheduler, Harness safety gating
• Notifications — Telegram message delivery with runtime DND coordination

Extensions & Config

• Plugin system — Tools, Gateways, Hooks, and Memory providers all follow defined shapes
• User extensions — drop custom plugins in ~/.agent/tools/, ~/.agent/hooks/, etc.
• Config-driven — every knob in agent.toml, secrets in .env

Architecture

The project follows a three-category architecture. Full details in the Architecture Guide.

src/
├── core/
│   ├── behaviours/        # 13 DI behaviour records (LLMClient, SessionStore, Guardrail, Logger, ...)
│   ├── types/             # session, message, client, response, hooks, tool_def, logging, guardrails
│   ├── config/            # config.gleam (loader), helpers.gleam
│   ├── loop/              # orchestrator, runner, context, compression, error, guardrails
│   ├── registry/          # registry.gleam (dispatch), builder.gleam (wires tools)
│   ├── session/           # session.gleam (state), handler.gleam (composition)
│   ├── tool/              # tool.gleam (types), executor.gleam (validation + parallel exec)
│   ├── schedule.gleam     # Shared cron parser
│   └── service.gleam      # Service shape definition
├── services/              # Fixed branches (api, storage, admin, tokens, guardrails, persona, context, titler, pulse, cron, harness, notifications, logger, supervisor)
│   ├── storage/           # db, db_behaviour, session_db, session_db_behaviour, memory_db, cron_db, schema, cfg
│   └── supervisor/        # Service lifecycle supervisor
├── plugins/               # Pluggable, shape-conforming — each module in its own folder
│   ├── types.gleam        # Plugin shape definition (Tool, Gateway, Hook, MemoryProvider)
│   ├── tools/             # bash/, browser/, code/, cron/, memory/, session_search/, web/, gateways/telegram/
│   ├── gateways/          # telegram/ (8 files), tui/README.md (planned), supervisor.gleam
│   ├── hooks/             # context_compressor/, reflection/, tool_guardrails/
│   └── memory/            # file_memory/
├── agent.gleam            # CLI REPL entry point
├── agent_app.gleam        # Daemon entry point (uses agent_supervisor)
├── agent_admin.gleam      # Admin CLI
└── agent_supervisor.gleam # Root supervisor (coordinates service + gateway supervisors)

Key patterns: behaviour-record DI, blessed violators, OTP supervision — see the Architecture Guide.

Admin Commands

Available in both CLI REPL (prefix with /) and via gleam run -m agent_admin:

Database:
  /db stats                 Show row counts and DB file size
  /db cost                  Show total cost across all sessions, per-model breakdown
  /db wipe memories         Delete all memory entries
  /db wipe sessions         Delete all sessions and messages
  /db prune sessions <days> Delete ended sessions older than N days

Sessions:
  /sessions list            List all sessions (key, source, model, tokens, cost)
  /sessions show <key>      Show session detail (persona, model, token breakdown)
  /sessions delete <key>    Delete a session and its messages
  /sessions search <query>  Full-text search across all message content
  /sessions rename <k> <t>  Rename a session
  /sessions export <key>    Export a session as JSON

REPL-only:
  /resume <id|title>        Switch to a previous session
  /continue                 Resume the most recent CLI session
  /clear                    End current session, start new one with parent linkage
  /title <text>             Set title for current session

Gateways:
  /gateways list            List configured gateways and their status
  /gateways status          Show detailed status for all active gateways

DND:
  /dnd status               Show active DND rules
  /dnd set <HH:MM> <HH:MM>  Add a scheduled quiet window (UTC)
  /dnd indefinite            Toggle indefinite DND on/off
  /dnd clear                 Remove all DND rules

Models:
  /models list              List all configured models
  /models primary           Show the primary model (name, base_url)

TCP protocol is line-delimited JSON: {"cmd":"sessions","action":"list"} → {"ok":"..."}

Configuration

• .env — secrets: DEEPSEEK_API_KEY, TELEGRAM_BOT_TOKEN
• agent.toml — everything else: model, persona, tool settings, gateway config, admin port

See the Configuration Reference for every option.

Dependencies

Documentation

Full documentation at agent-8x3.pages.dev:

• Getting Started — prerequisites, clone, configure, first run
• Architecture — Core/Services/Plugins, OTP supervision, request flow
• Configuration — complete agent.toml reference
• Services — API, storage, admin, guardrails, pulse, cron, and more
• Plugins — how to write and install custom tools, gateways, and hooks
• Telegram Bot Setup — end-to-end walkthrough
• API Reference — complete module-level API docs from source

Comparison with hermes-agent

Our agent is modeled after hermes-agent, a production Python AI agent.

Matched capabilities

Deliberately deferred (design choices, not gaps)

• Streaming responses — v1 buffers full responses; SSE streaming needs httpp + gleam_otp/process
• Multi-provider abstraction — single OpenAI-compatible endpoint suffices
• Full actor-based OTP services — supervisor tree coordinates startup/stop/health using shapes
• ETS for approval cache — in-memory list fine for current scale

Key gaps vs hermes-agent

Test coverage

~630 tests. Guardrails (46), web/SSRF (42), admin (34), browser (14), and the full conversation loop (53 tests across unit, guardrails, compression, and integration suites) are well-covered. The only remaining untested areas are integration tests that require real API keys or external services.

Development

gleam run                     # Run the CLI REPL
gleam run -m agent_app        # Run the daemon (Telegram + admin)
gleam run -m agent_admin ...  # Connect to daemon's admin port
gleam test                    # Run all tests
gleam format                  # Format source files