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

Note

Prebuilt binaries are Apple Silicon macOS only. Other platforms build from source — anywhere a Rust 2024 toolchain runs.

curl -fsSL https://raw.githubusercontent.com/Si1w/mandeven/main/scripts/install.sh | sh

Or from source (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, grep
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]

🧩 Runtime state

Backing stores for the tool instruction set and optional subsystems, not separate tool categories. Runtime-mutable state lives in sidecar files; durable enable/budget knobs live in mandeven.toml.

State	Source	Effect
skills	built-in + ~/.mandeven/skills/<name>/SKILL.md	Surfaced as /<name> slash commands + the skill_use tool
hooks	~/.mandeven/hooks.json	Shell commands fired on lifecycle events
tasks	project bucket tasks/*.md	User-visible task state and explicit task executions
timers	~/.mandeven/timers.json	Schedule triggers for tasks and skills
exec	project bucket execution/*.jsonl	Machine-readable history for task executions
timeline	project bucket timeline/*.jsonl	Structured runtime trajectory for /timeline
recovery	project bucket recovery/*.json	Queued-input crash recovery and active-turn markers
memory	~/.mandeven/MEMORY.md + [agent.memory]	Durable user memory injected as transient user context

Core runtime stores include schema versions. Runtime store files must carry the exact schema version supported by the current build; missing, older, or newer versions are rejected instead of being silently rewritten.

📜 License

Apache License 2.0. See LICENSE.