Vulgr Agent is a Warp-Agent-style agentic shell (CLI) that runs inside the terminal you already use. There is a single input line:
- Shell commands run directly in your own persistent shell.
- Plain-language requests go to an LLM agent, which picks the best model for each task by itself (the model router).
Stack
| Area | Choice |
|---|---|
| Language / runtime | TypeScript, Node.js ≥ 22, ESM |
| Build / tests | tsup / vitest |
| TUI | Ink + React |
| Terminal | node-pty + @xterm/headless, OSC 633 shell-integration markers |
| LLM | @anthropic-ai/sdk (Anthropic Messages API, primary); openai SDK planned |
| Other | commander (CLI), zod (schemas), picomatch / ignore (file matching) |
Key design decisions
- Your shell and the agent’s shells are separate. The agent never types into your prompt; its commands run in its own PTY sessions, which can be sandboxed. Long commands return a
session_idand are followed withwrite_stdin. - History is append-only. Changing state goes into reminders, not the system prompt, so the prompt-cache prefix stays valid.
- Tool errors go back to the model as
is_errorresults, and a denied permission is passed on together with your note.
Status
Ready and verified by tests: the shell + agent loop, ten tools, permissions, the router, retry, JSONL session logs, the TUI, the resilience / token optimizer and headless mode.
The target measurement is Terminal-Bench 2.0 (Harbor), compared against other agent harnesses.