Note

This README was generated by SKILL, get the ZH version from here.
Tests are generated by SKILL.

---

BUILD YOUR OWN OPENCLAW WITH AGENVOY!

---

Agenvoy

A Go AI agent framework with self-improving error memory, intelligent multi-provider routing, Python/JS/REST API tool extensions, and OS-native sandbox execution

The agent learns from past failures across sessions, routes each task to the right LLM provider automatically, and lets you extend its toolset by dropping a script or JSON file — all running inside an OS-native sandbox.

Terminal UI consolidating CLI, Discord bot, and REST API into a single local interface — filesystem browser, session content viewer, and live log stream.

Table of Contents

• Architecture
• Features
• Concepts
• File Structure
• Version History
• License
• Author
• Stars

Architecture

Detailed diagrams for each subsystem: doc/architecture.md

graph TB
    subgraph Entry ["Entry Points"]
        App["cmd/app · TUI Dashboard"]
        subgraph Managed ["Managed by cmd/app"]
            CLI["cmd/cli · will deprecate"]
            Discord["Discord Bot"]
            API["REST API · HTTP Endpoint"]
        end
    end

    subgraph Engine ["Execution Engine"]
        Run["exec.Run()"]
        Execute["exec.Execute()\n≤128 iterations"]
    end

    subgraph Providers ["LLM Providers"]
        P["Copilot · OpenAI · Claude\nGemini · Nvidia · Compat"]
    end

    subgraph Security ["Security Layer"]
        S["Sandbox · Denied Paths · Keychain"]
    end

    subgraph Tools ["Tool Subsystem"]
        T["File · Web · API · Script\nScheduler · Error Memory"]
    end

    subgraph Persistence ["Persistence"]
        PS["Session Summary · History"]
    end

    App --> CLI
    App --> Discord
    App --> API
    CLI --> Run
    Discord --> Run
    API --> Run
    Run --> Execute
    Execute -->|"Agent.Send()"| Providers
    Execute -->|"tool calls"| Security
    Security --> Tools
    Tools -->|"results"| Execute
    Execute --> Persistence
    Persistence -.->|"inject"| Execute

Loading

Features

go install github.com/pardnchiu/agenvoy/cmd/cli@latest · Documentation

TUI Dashboard

A terminal UI that consolidates CLI execution, Discord bot management, and the REST API endpoint into a single local interface — browse config files, view session content, and stream logs from one window.

Multi-Provider LLM with Intelligent Routing

Six backends behind one interface — a dedicated planner LLM picks the right provider per request and trims the context window automatically.

Details

GitHub Copilot, Claude, OpenAI, Gemini, Nvidia NIM, and any OpenAI-compatible endpoint (Compat/Ollama) — all behind a unified Agent interface. A planner LLM automatically selects the best provider per request. Token-budget trimming prevents context window overflow, and per-provider configurable reasoning levels are supported.

Script & API Tool Extensions

Drop a tool.json + script.js/script.py to register a custom script tool, or a JSON file to add any HTTP API as a tool — no Go code, no recompilation required.

Details

Script tools: On startup, the executor scans ~/.config/agenvoy/script_tools/ for subdirectories containing a tool.json manifest paired with an executable script. Each tool is registered with the script_ prefix and dispatched via stdin/stdout JSON.

API tools: 14+ embedded public API tools (CoinGecko, Wikipedia, Open-Meteo, Yahoo Finance, etc.) are defined as pure JSON. User-defined extensions in ~/.config/agenvoy/apis/ are loaded at startup with no compilation step.

OS-Native Sandbox Isolation

Commands run inside bubblewrap (Linux) or sandbox-exec (macOS) — escaped paths and sensitive files are blocked at the OS level.

Details

All commands and scripts execute inside bubblewrap on Linux (with dynamic namespace probing) or sandbox-exec on macOS. Sensitive path denial is loaded from an embedded deny list, credentials are stored in the OS keychain, and symlink-safe path validation restricts access to the user's home directory only.

Persistent Error Memory

Tool failures are SHA-256 indexed per session; the agent recalls past errors and reuses resolutions across sessions.

Details

When any tool call fails, the error is persisted to tool_errors/{hash}.json. The agent can recall past failures via search_errors and persist resolution decisions via remember_error — enabling cross-session learning without manual intervention.

External Agent Verification & Internal Review

Three tools let the agent cross-check its own output before returning it — either using a priority-ordered internal model or dispatching in parallel to all declared external agents.

Details

review_result — internal completeness review. Automatically selects the highest-priority available model (claude-opus → gpt-5.4 → gemini-3.1-pro → claude-sonnet) and runs a one-shot quality check. Triggered by user phrases like "review", "any omissions", "completeness check" — no external agent declaration required. After review, the context is trimmed to draft + feedback so the agent can apply corrections directly.

verify_with_external_agent — parallel cross-validation. Dispatches the current result to all declared external agents simultaneously and merges their feedback. Triggered only when the user explicitly requests "external verification", "cross-check", "second opinion", or similar multi-source language, and at least one external agent is declared (EXTERNAL_COPILOT / EXTERNAL_CLAUDE / EXTERNAL_CODEX). Falls back to review_result when no external agents are available.

call_external_agent — direct delegation. Routes the entire task to a specific named external agent when the request exceeds the current tool set or requires a different execution environment.

Concepts

Two prior projects from the same author directly informed Agenvoy's architecture:

Script Tool as FaaS — pardnchiu/go-faas

pardnchiu/go-faas is a lightweight Function-as-a-Service platform that accepts Python, JavaScript, and TypeScript code via HTTP, executes each function inside a Bubblewrap sandbox with full Linux namespace isolation, and streams results. Agenvoy's script tool subsystem (scriptAdapter) adopts this model directly: each script tool is a stateless function invoked via stdin/stdout JSON, isolated to its own process, with the agent acting as the caller rather than an HTTP client.

Cognitive Imperfect Memory — pardnchiu/cim-prototype

pardnchiu/cim-prototype argues that perfect memory is a cognitive burden — based on research showing multi-turn LLM performance drops 39% when full conversation history is replayed verbatim (LLMs Get Lost In Multi-Turn Conversation). The system maintains a structured rolling summary and retrieves relevant fragments via fuzzy search only when triggered, mirroring how humans selectively recall rather than replay. Agenvoy's session layer reflects this directly: trimMessages() enforces a token budget rather than replaying full history, summary is persisted and deep-merged across turns, and search_history provides keyword-triggered recall rather than injecting all past context.

File Structure

agenvoy/
├── cmd/
│   ├── app/                # Unified entry point: TUI dashboard + Discord bot + REST API
│   ├── cli/                # CLI: add / remove / list / run
│   └── server/             # Discord bot entry point
├── configs/
│   ├── jsons/              # Provider model defs, denied_map, whitelist
│   └── prompts/            # Embedded system prompts and selectors
├── extensions/
│   ├── apis/               # Embedded API extensions (14+ JSON)
│   ├── scripts/            # Bundled script tools (Threads, yt-dlp + install scripts)
│   └── skills/             # Embedded skill extensions (Markdown)
├── install_threads.sh      # Cross-platform installer for Threads script tools
├── install_youtube.sh      # Cross-platform installer for yt-dlp script tools
├── internal/
│   ├── agents/
│   │   ├── exec/           # Execution engine, token trimming, summary extraction
│   │   ├── provider/       # 6 AI provider backends + Responses API
│   │   └── types/          # Agent interface + message / usage types
│   ├── discord/            # Discord slash commands + file attachments
│   ├── filesystem/         # Path validation, keychain, and usage tracking
│   ├── routes/             # HTTP REST API routing (Gin)
│   ├── store/              # Session persistence, search, atomic writes
│   ├── tui/                # Terminal UI (rivo/tview) — file browser, logs, content viewer
│   ├── sandbox/            # Sandbox isolation + sensitive path denial
│   ├── scheduler/          # Persistent one-time and recurring task scheduler
│   ├── session/            # Session state, config, and rolling summary
│   ├── skill/              # Markdown skill scanner and parser
│   ├── toolAdapter/
│   │   ├── api/            # HTTP API tool translation and dispatch
│   │   └── script/         # Script tool executor and stdin/stdout JSON bridge
│   ├── tools/              # 29+ self-registering tools + git / scheduler tools
│   │   └── externalAgent/  # External agent delegation + internal review tools
├── go.mod
└── LICENSE

Version History

• v0.17.2 — Add call_external_agent, verify_with_external_agent, and review_result tools for external delegation and internal priority-model review. Refactor session message assembly into 4 fixed segments (SystemPrompts / OldHistories / UserInput / ToolHistories) with reactive context trimming on context-length errors. Add model field to /v1/send request to bypass automatic agent selection.
• v0.17.1 — Fix build break caused by importing the missing externalAgent package before it existed in the repository.
• v0.17.0 — Full REST API layer with /v1/send (SSE + non-SSE), /v1/key, /v1/tools, /v1/tool/:name endpoints. TUI dashboard complete with file browser, session viewer, and live log stream. Discord bot and REST API unified under cmd/app. Copilot token migrated to system keychain. Renamed browser package to fetchPage. Updated schedule-task and script-tool-creator skills to invoke tools via Agenvoy API instead of direct external calls.

Earlier versions

• v0.16.1 — Bundled Threads (publish text/image/carousel, quota, token refresh) and yt-dlp (video info, download) script tool extensions with cross-platform install_threads.sh / install_youtube.sh. Refactor toolAdapter into api/ and script/ sub-packages; move session management to internal/session; split filesystem into single-responsibility files. Fix Darwin sandbox keychain directory access. Restrict tool call throttle to api_ prefix; improve AbsPath tilde expansion and exclude logic deduplication.
• v0.16.0 — Script tool runtime (scriptAdapter): drop a tool.json + script.js/script.py into ~/.config/agenvoy/script_tools/ and it is auto-discovered as a script_-prefixed tool; stdin/stdout JSON protocol mirrors API tool contract. Refactor tools/apis/adapter → apiAdapter, tools/apis → tools/api. Add skill_git_commit, skill_git_log, skill_git_rollback for skill-internal versioning. Copilot token auto-relogin on 401. Fix Discord file upload failure for non-ASCII filenames; add 10MB pre-upload size guard with user-facing warning.
• v0.15.2 — Add YouTube metadata fetch tool (analyze_youtube); Discord Modal-based API key management (/add-gemini, /add-openai, /add-claude, /add-nim); per-model token usage tracking via usageManager; configurable reasoning level across all providers; browser iteration limits and same-domain link traversal now configurable via MAX_TOOL_ITERATIONS, MAX_SKILL_ITERATIONS, MAX_EMPTY_RESPONSES; fix Makefile pass-through args
• v0.15.1 — Fix Copilot Claude/Gemini image validation failure: all uploaded images are decoded and re-encoded as JPEG (image.Decode + jpeg.Encode, supporting PNG/GIF/WebP sources), ImageURL gains detail field; summary regex split from one monolithic expression into three independent patterns (fenced block, <summary> tag, [summary] bracket); system prompts moved after history to improve model instruction adherence; Discord prompt takes priority over base system prompt
• v0.15.0 — Copilot Responses API support (GPT-5.4 and Codex models auto-switch endpoint); session-level token-budget message trimming (budget calculated via MaxInputTokens(), preserving system prompt + summary + latest user message); sensitive path denial rules for macOS and Linux sandbox (loaded from embedded denied_map.json); Linux bwrap restores --unshare-all namespace isolation (with graceful fallback probing) and --new-session process isolation; MAX_HISTORY_MESSAGES environment variable support; summary delimiter switched to XML tags; lite models excluded from agent selection
• v0.14.0 — OS-native sandbox isolation (bubblewrap on Linux with auto-install, sandbox-exec on macOS); per-request token usage tracking accumulated across all tool-call iterations; tool handlers restructured into individually named files; exclude logic and file walk/list moved into filesystem package; symlink-safe path resolution in GetAbsPath
• v0.13.0 — Self-registering tool Registry replacing switch-based routing and embedded JSON definitions; scheduler persistent JSON storage with full CRUD (add/update/delete for tasks and crons); keychain migrated under filesystem; absolute path restriction to user home directory; trimmed history ellipsis markers
• v0.12.0 — Full scheduler subsystem (cron + one-time tasks with Discord callbacks); centralize filesystem + configs packages; replace custom cron parser with go-scheduler; schedule-task skill
• v0.11.2 — Fix bidirectional error-memory keyword matching; fix Claude multi-system-prompt merge; pre-tool text suppression rule in system prompt
• v0.11.1 — Tool execution error tracking (hash-based tool_errors/); atomic writes (utils.WriteFile); Gemini multipart message fix; 8 new public API extensions; get_tool_error tool
• v0.11.0 — Declarative Extension architecture — built-in Go API tools migrated to JSON extensions; SyncSkills from GitHub; switch license to Apache-2.0
• v0.10.2 — Fix temperature for OpenAI reasoning models (gpt-5, gpt-4.1); no_temperature model flag; planner CLI command; makefile
• v0.10.1 — Provider model registry with embedded JSON configs; interactive model selection UI; uniform temperature=0.2 across all providers
• v0.10.0 — Discord bot mode with full slash command support; download_page browser tool; multi-layer sensitive path security (denied.json); HTML-to-Markdown converter
• v0.9.0 — File injection (--file), image input (--image); remember_error / search_errors tools; web search SHA-256 cache (1-hour TTL); remove command; public API (GetSession, SelectAgent, SelectSkill)
• v0.8.0 — Rename to Agenvoy (AGPL-3.0); OS Keychain integration for secure API key storage; named compat[{name}] instances; GitHub Actions CI + unit tests
• v0.7.2 — Split CLI entry into focused modules; mergeSummary deep-merge strategy; API example configs (exchange-rate, ip-api)
• v0.7.1 — Fix race conditions across all providers (instance-level model field); fix Context chain in runCommand / moveToTrash; replace strconv.Unquote with json.Unmarshal for Unicode handling
• v0.7.0 — LLM-driven automatic agent routing; OpenAI-compatible (compat) provider / Ollama support; search_history tool; file-locking for concurrent sessions; split monolithic exec.go into sub-package
• v0.6.0 — Summary-based persistent memory; session history (history.json); tool action logging; centralized utils.ConfigDir()
• v0.5.0 — Add fetch_page (headless Chrome + stealth JS), search_web (Brave + DDG concurrent), calculate; Context propagation through the full tool chain
• v0.4.0 — Built-in API tools (weather, stock, news, HTTP); JSON-driven API adapter; patch_edit tool; skill auto-matching engine; io.Writer → Event Channel output model
• v0.3.0 — Multi-agent backend support: OpenAI, Claude, Gemini, Nvidia; unified Agent interface; concurrent goroutine skill scanner
• v0.2.0 — Add full filesystem toolchain (list_files, glob_files, write_file, search_content, run_command), command whitelist, interactive confirmation, --allow flag
• v0.1.0 — Initial release — GitHub Copilot CLI with skill execution loop and automatic token refresh

License

This project is licensed under the Apache-2.0 LICENSE.

Author

邱敬幃 Pardn Chiu

Stars

---

©️ 2026 邱敬幃 Pardn Chiu