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

On macOS, the same names can live in Keychain instead of the process environment:

security add-generic-password -U -s mandeven -a DEEPSEEK_API_KEY -w '<key>'

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, file_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]

📜 License

Apache License 2.0. See LICENSE.