LMAgent-Plus

Local-first AI agent orchestrator. No cloud required, no external runtime, no bullshit.

---

What is this?

LMAgent-Plus is an AI agent platform that runs entirely on your machine.

It downloads and manages llama.cpp internally — no Ollama, no LM Studio, nothing to install first. Pick a model, it downloads it, it runs.

A Python daemon handles the agent loop, tool execution, and memory. Three frontends connect to it over WebSocket: a Textual TUI for terminal power users, a Tauri + Svelte 5 desktop GUI for a full graphical experience, and a web interface for remote access from any browser (same Svelte GUI served over HTTP). Cloud APIs (Anthropic, OpenAI) are supported as an alternative or fallback to local models.

---

Features (v0.3)

Core

• Self-contained runtime — downloads the right llama.cpp binary automatically (CUDA / ROCm / Vulkan / Metal / CPU)
• Built-in model manager — pull models from HuggingFace directly from the TUI or GUI
• Multi-persona routing — @assistant, @coder, @writer, @research — each with its own tool set, system prompt, memory, and model
• Tool use — bash, file read/write/list, git, memory persistence, agent delegation
• Two-layer memory — global context + per-agent memory, injected at the start of each session
• Streaming responses — real-time output for local (llama-server SSE) and cloud (Anthropic / OpenAI)
• Security — path guard, bash blocklist, git command injection protection
• Cloud routing — route to Anthropic/OpenAI instead of or alongside local models
• Custom tools — drop a Python file in ~/.lmagent-plus/tools/ and it's available to agents
• Planning loop — agents decompose complex tasks into steps before executing (opt-in per persona)
• Self-reflection — post-execution review with correction loop (opt-in per persona)
• Structured outputs — response_format support (OpenAI/local passthrough, Anthropic tool_choice translation)
• Metrics collection — token usage, cost estimation, latency tracking per request (JSONL storage)
• Eval framework — benchmark agents against predefined tasks, track outcomes
• Structured logging — JSON log formatter with request_id correlation, file rotation
• GGUF context cap — reads model metadata, prevents ctx_size from exceeding model max

Desktop GUI (Tauri + Svelte 5)

• Chat — streaming, markdown rendering, tool call display, multi-agent tabs
• Planning/Reflection cards — visual step tracking and reflection results in chat
• Metrics card — per-request token/latency/tool summary inline
• Metrics dashboard — summary cards, hourly bar chart, per-agent breakdown, token split
• Models — browse catalog, search HuggingFace, download with real-time progress bar, uninstall
• Personas — visual YAML editor (identity, model, system prompt, tool checkboxes), create/duplicate/delete
• Memory — tree view of global + per-agent memory, edit context.md and learned.md
• History — session browser filterable by agent/date/text, conversation viewer
• Settings — full config.yaml editor (7 sections, font size sliders, backend selection)
• System — daemon status, loaded model, uptime, notifications, daemon control buttons
• Setup wizard — 5-step guided first-run (routing, backend, performance, model, confirmation)
• Keyboard shortcuts — Ctrl+1-8 pages, Ctrl+W close tab, Ctrl+T chat
• Dynamic window title — shows active persona and model
• Waiting overlay — shows loading state while model boots or LLM processes

Web Interface (Remote Access)

• Same GUI as desktop — served over HTTP by a built-in FastAPI server
• Token auth — auto-generated Bearer token, login overlay in browser
• WebSocket proxy — single port (7772), proxies WS to daemon internally
• Tailscale support — interactive setup script, optional Tailscale Serve for HTTPS
• Web Access settings — enable/configure directly from the Settings page
• See docs/WEB_ACCESS.md for full guide

TUI (Textual)

• Modular architecture — sidebar navigation (Ctrl+1/2/3), dedicated pages (Chat, Metrics, Settings)
• 14 slash commands — /help, /persona, /model, /models, /tools, /hf, /hfd, /setup, /reload, /clear, /stop, /status, /metrics, /settings
• Planning/reflection/metrics display — step tracking, reflection results, per-request stats
• Metrics dashboard — request count, tokens, cost, latency, per-agent breakdown
• Setup wizard — 5-step interactive (hardware detection, routing, backend, idle timeout)
• Live tool call display, arrow key autocomplete, theme persistence, persona picker (F2)

---

Supported backends

Backend	Hardware	Notes
CUDA	NVIDIA GPUs	Best performance on NVIDIA
ROCm	AMD workstation GPUs	Requires ROCm installed
Vulkan	AMD / Intel on Linux	Recommended for AMD RX series
Metal	Apple Silicon	Native on macOS
CPU	Any	Fallback — slow on models >7B

---

Install

One-command install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/3L0935/LMAgent-plus/main/installer/install.sh | bash

One-command install (Windows PowerShell)

irm https://raw.githubusercontent.com/3L0935/LMAgent-plus/main/installer/install.ps1 | iex

Everything gets installed into ~/.lmagent-plus/ — self-contained, no system pollution.

Requirements: Python 3.10+, git. uv is auto-installed if missing. For the GUI: Node 20+, Rust/Cargo.

For developers

git clone https://github.com/3L0935/LMagent-plus.git
cd LMagent-plus
uv sync
./serve   # daemon
./chat    # TUI
./gui-dev # GUI (dev mode)

Uninstall

rm -rf ~/.lmagent-plus

Or use the interactive uninstaller: bash ~/.lmagent-plus/app/installer/uninstall.sh

---

Run

lmagent-chat     # Start the TUI (daemon auto-starts)
lmagent-serve    # Start the daemon only
lmagent-gui      # Start the GUI (needs Node + Cargo)

Commands are in ~/.lmagent-plus/bin/ — add it to your PATH during install.

First steps — TUI

/setup              guided setup — backend, routing, model download
/hf mistral         search HuggingFace for GGUF models
/hfd owner/repo     browse & download a specific HuggingFace repo (pick quantization)
/model <id>         download and load a model
/models             list available models (downloaded + catalog)
/persona coder      switch to the coder persona
/tools              list tools available for the active persona
/help               full command reference

First steps — GUI

1. Launch with ./gui-dev — if no config.yaml exists, the setup wizard opens automatically
2. Models page (Ctrl+2) — browse the catalog, search HuggingFace, download with progress bar
3. Personas page (Ctrl+3) — edit or create personas with the visual editor
4. Chat (Ctrl+1) — pick a persona from the tab bar, start chatting
5. Memory (Ctrl+4) — view/edit global context and per-agent memory
6. History (Ctrl+5) — browse past sessions, filter by agent or date

Cloud-only (no local model)

export ANTHROPIC_API_KEY=sk-...
# or: export OPENAI_API_KEY=sk-...

Set routing in ~/.lmagent-plus/config.yaml:

routing:
  default: cloud

---

Personas

Persona	Recommended model	Min RAM	Tools	Use for
@assistant	Harmonic Hermes 9B	12 GB	bash, file_ops, call_agent	General purpose, tool use, delegation
@coder	Qwen3-Coder 30B A3B	24 GB	bash, file_ops, git	Development tasks
@writer	Qwen3 8B	10 GB	file_ops	Writing, editing, summarizing
@research	Qwen3 8B	10 GB	file_ops	Analysis, reasoning, document review

Custom personas: create in the GUI (Personas page) or copy personas/_base.yaml to ~/.lmagent-plus/personas/.

---

Project structure

lmagent-plus/
├── core/          # Python daemon — agent loop, tools, memory, runtime, router
├── cli/           # Terminal TUI (Textual)
├── gui/           # Desktop GUI (Tauri v2 + Svelte 5)
├── personas/      # Bundled agent presets (YAML)
├── installer/     # One-command installers + setup helper
├── docs/          # Architecture, memory, runtime, persona docs
└── tests/         # Python tests (289 tests)

User data: ~/.lmagent-plus/ — see docs/USER_DIR.md.

---

Tests

# Python tests (289 — core + web)
uv run pytest

# Rust tests — Tauri CRUD commands (21)
cd gui/src-tauri && cargo test

# Vitest — GUI state logic + backend adapters (33)
cd gui && npm test

CI runs all 3 suites on every push. See Actions.

---

Documentation

Doc	Content
PLAN.md	Project phases and roadmap
docs/ARCHITECTURE.md	Repo structure, code conventions, multi-agent design
docs/GUI.md	Desktop GUI architecture (Tauri + Svelte)
docs/RUNTIME.md	llama.cpp backends, model manager
docs/MEMORY.md	Two-layer memory system
docs/PERSONAS.md	Persona YAML format, system prompt rules
docs/USER_DIR.md	~/.lmagent-plus/ structure, config reference
docs/WEB_ACCESS.md	Web interface setup, Tailscale, auth

---

Contributing

The easiest entry point is creating or improving personas — no Python knowledge required.

cp personas/_base.yaml personas/my-agent.yaml
# edit, test, open a PR

For everything else: docs/ARCHITECTURE.md.

---

License

See LICENSE