v1.3.8
Home GitHub

Getting Started

Last updated


Prerequisites


  • Linux (sandbox via bubblewrap; bwrap auto-installs through apt/dnf/yum/pacman/apk if missing) or macOS (sandbox-exec)
  • At least one LLM provider account — an OAuth subscription (Codex, Copilot, Grok; Claude Code through the local claude CLI once it is on PATH) or an API key (OpenAI, Claude, Gemini, Grok, DeepSeek, Mistral, NVIDIA, Ollama Cloud, OpenRouter, Cloudflare), or a local OpenAI-compatible server (Ollama, LM Studio, custom URL)
  • Go 1.25.1 or higher, only if building from source
  • Optional: pdftotext (poppler-utils) so read_files can parse PDFs
  • Optional: OPENAI_API_KEY to enable semantic search (text-embedding-3-small)
  • Optional: an OpenAI, Gemini or OpenRouter credential to enable audio — /model stt lets read_files transcribe audio and video, /model tts registers generate_audio. Both are off until a model is picked

Install


  1. curl -fsSL https://agenvoy.com/scripts/install.sh | bash
  2. agen

Or build from source:
  1. git clone https://github.com/pardnchiu/Agenvoy.git
  2. cd agenvoy
  3. make build

make build compiles, stamps the current exact-match git tag into internal/runtime.CurrentVersion, installs the binary to /usr/local/bin/agen, and refreshes the bundled skills and tools.

Configure at least one provider


Launch the TUI and run /model — it walks through provider selection, live model discovery from that provider's API, and credential storage. Tokens land in the OS keychain (security on macOS, secret-tool on Linux) under the fixed service name agenvoy; when secret-tool is unavailable they go to ~/.config/agenvoy/.secrets (mode 0600). Reads try the keychain, then that file, then an environment variable of the same name.
The main config lives at ~/.config/agenvoy/config.json; it holds registered models and runtime limits, never credentials.

First run


  1. agen

The daemon starts automatically if it isn't already running. Since v1.2.0 the daemon runs every request and the TUI talks to it over a Unix socket; while it is unreachable the status line shows Connecting. Inside the TUI, /new creates a session (optionally /new <name>, then pick a role as its description) and /session moves between sessions.
The input box is always focused — type your message and press Enter to send (Alt+Enter inserts a newline; Enter during a run sends plain text as a steer message; / commands wait until the run ends). Type / to open the command palette (matches command name or description); Tab/Enter confirms the highlighted entry, Esc dismisses it. With the input empty: Shift+Tab toggles auto-approve (⏸ safe ↔ ⏵⏵ auto; the TUI starts in auto inside a subdirectory of $HOME), Shift+F toggles fast mode, Shift+W/Shift+S cycles the session model, Shift+A/Shift+D cycles the session reasoning level (auto included), and Shift+G toggles CLAUDE.md / AGENTS.md injection.
中文