mandeven

mandeven is an agent for research work and everyday life, written in Rust.

🧭 Design philosophy

mandeven is built around a small number of opinions. The features below exist because of them, not the other way around.

Tools are a RISC instruction set

Every model-facing tool does exactly one thing. file_read reads a file. file_write writes one. task_write creates one task; a separate task_edit updates it. timer_fire fires one timer. plan_write replaces a plan snapshot.

There is deliberately no read-and-then-write, no bulk batch endpoint, no multi-step convenience tool. A single tool call is one state transition the model can reason about, audit, and roll back. Schemas stay narrow enough to keep prompts cheap and toolchoice stable across providers.

Skills and shell are the CISC layer

Composition belongs above the instruction set. Two surfaces own it:

• SKILL.md files (~/.mandeven/skills/<name>/). A skill bundles a workflow into one Markdown body the model executes via the skill_use tool, the /<name> slash fallback, or a frontmatter timers: declaration. Skills are user-editable; adding capability is a file edit, not a code change.
• shell_exec. The user's shell is a battle-tested combinator. Pipelines, environment lookups, ad-hoc one-off scripts — none of that needs a bespoke tool when shell_exec already runs them under the active sandbox policy.

The split keeps the agent's instruction set small and stable while domain-specific behaviour grows in plain text.

📦 Install

Build from source — anywhere a Rust 2024 toolchain runs. Installs into ~/.cargo/bin/:

git clone https://github.com/Si1w/mandeven.git
cd mandeven
cargo install --path .

🚀 Quick start

1. Set your provider API key

Provider	Env var
Deepseek	DEEPSEEK_API_KEY
Mistral	MISTRAL_API_KEY

First launch writes ~/.mandeven/mandeven.toml. LLM configuration is grouped by provider. The provider block owns the OpenAI-compatible endpoint (base_url) and API-key environment variable (env_key); each profile block owns the upstream model id and optional tuning knobs. max_context_window defaults to 1_000_000 tokens when omitted; the config loader may materialize that default when it rewrites the file. Set it explicitly for models with a known smaller window, for example mistral-small-latest uses 256000.

First-party providers (deepseek, mistral) have built-in base_url and env_key defaults. TOML values override those defaults when present. You can rely on the defaults:

[llm]
default = "deepseek/dsv4-flash"

[llm.deepseek.dsv4-flash]
model_name = "deepseek-v4-flash"

Or materialize the defaults explicitly:

[llm]
default = "deepseek/dsv4-flash"

[llm.deepseek]
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

[llm.deepseek.dsv4-flash]
model_name = "deepseek-v4-flash"
max_context_window = 1000000

Third-party OpenAI-compatible providers must declare both provider fields:

[llm.deepseek_proxy]
base_url = "https://proxy.example.com/v1"
env_key = "DEEPSEEK_PROXY_API_KEY"

[llm.deepseek_proxy.dsv4-flash]
model_name = "deepseek-v4-flash"

2. Launch

mandeven

3. Chat

Type into the composer. /help shows the slash-command panel. Run /doctor after first launch to check config, secrets, stores, channels, recovery state, and checkpoint availability.

🛠️ Tools (the RISC set)

Registered automatically and advertised to the model on every turn. Each row is one verb against one scope.

Capability	Tools
File	file_read, file_write, file_edit, search
Shell	shell_exec under the active sandbox policy
Web	web_search (DuckDuckGo, Bing fallback), web_fetch
Plan	plan_write for the current turn's visible checklist
Task	task_write, task_read, task_edit, task_delete, task_run
Timer	timer_write, timer_read, timer_edit, timer_delete, timer_fire
Skill	skill_use to invoke a SKILL.md workflow by name

📡 Channels

The agent talks to the user through a pluggable channel layer.

Channel	Status
tui	built-in ratatui terminal UI
discord	DM-only adapter, opt-in via [channels.discord]
wechat	text-only personal WeChat iLink adapter with QR login, opt-in via [channels.wechat]

External channel sections are materialized lazily. /wechat, /wechat status, and /wechat login write a default disabled [channels.wechat] block to ~/.mandeven/mandeven.toml when it is missing, then continue with the command. When no WeChat account is saved yet, /wechat opens the QR login flow. The logged-in WeChat user is selected automatically, replacing any previous selected user; after login, /wechat toggles the channel connection. Use /wechat autostart on if you want WeChat to connect on launch.

📜 License

Apache License 2.0. See LICENSE.