Minimal Local Agent

A small local-first agent kernel. Bounded tools. Reversible edits. Auditable runs.

简体中文 · Documentation · Quick start · Customize · Releases · Contribute

One model/tool loop, one bounded workspace, and a local SQLite record of what happened. Use Ollama or an explicitly configured Chat Completions-compatible API from the CLI, local Web console, or your own Python host.

Built for developers who want to understand, embed, and customize an agent—not a universal assistant with a growing collection of default tools.

The real v1.0 interface with disposable sample files and a live model. The Web UI is currently Chinese. Screenshot provenance and reproduction.

The model called the real edit tool; the sample file stayed unchanged. Web tasks can read or preview. Approving an actual write requires interactive CLI.

Why this kernel

• Permissions that change the tool surface. Denied tools disappear from the model's schema, rather than relying on a prompt to discourage their use.
• Reviewable, reversible edits. One bounded diff, one approval, stale-file checks, transaction rollback, and hash-checked undo.
• Inspectable runs. Local history, tool audit, runtime events, and hash-chained receipts explain what ran and what changed.
• Small extension points. Add a reviewed read tool, replace model construction, or explicitly supply a context reducer without editing the loop.

See the scope comparison for trade-offs. This is neither a Python sandbox nor a general autonomous assistant.

Quick start

Requires Python 3.11+ and a model supporting tool calling. The example uses Ollama; other local servers and compatible APIs use local configuration.

macOS / Linux

git clone https://github.com/MuzeAnisichael/minimal-local-agent.git
cd minimal-local-agent
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
ollama pull qwen3.5:9b
cp agent.example.toml agent.toml
minimal-agent doctor
minimal-agent web

git clone https://github.com/MuzeAnisichael/minimal-local-agent.git
Set-Location minimal-local-agent
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
ollama pull qwen3.5:9b
Copy-Item agent.example.toml agent.toml
minimal-agent doctor
minimal-agent web

Open http://127.0.0.1:8765. Put only files the agent may access under workspace/. Prefer the terminal? Run minimal-agent chat or minimal-agent run --read-only "List the workspace files".

To try the Web interface with disposable sample files, run this from the source checkout instead of minimal-agent web:

python examples/web_demo.py

Use the URL printed by the demo. It uses your configured real model but never loads your personal workspace or saved sessions; model calls may incur charges.

For a fixed install, download the wheel from the v1.0.0 release and install it in a virtual environment:

python -m pip install minimal_local_agent-1.0.0-py3-none-any.whl

No PyPI publication is assumed. The v1.0.0 tag pins the original release; the screenshot demo and refreshed documentation live on main. More commands and configuration: user guide.

What is included

Customize without forking the core

from dataclasses import replace

from minimal_local_agent import AgentRuntime, Settings

runtime = AgentRuntime(replace(Settings.load("agent.toml"), write_policy="deny"))
outcome = runtime.run("List the workspace files")
print(outcome.response)
print(outcome.receipt_hash)

• Add a read tool: explicitly register ReadTool; start with the runnable example.
• Choose a model: use ignored local settings or supply a ModelFactory.
• Reduce context: explicitly pass a trusted context_reducer; automatic compression is off, and the original history remains stored.
• Connect MCP: optionally install the extra and allowlist reviewed local read tools. No implicit discovery or remote MCP.

Read the embedding guide and v1 compatibility contract before building an integration.

How it fits together

flowchart LR
    Host["CLI / local Web / Python"] --> Runtime["AgentRuntime: policy + budgets"]
    Runtime <--> Model["Ollama / compatible API"]
    Runtime --> Tools["Bounded tools + reviewable edits"]
    Tools --> Files["One workspace"]
    Runtime --> State["SQLite: history + audit + receipts"]

PydanticAI handles model/tool iteration; project code handles boundaries, transactions, and local state. The Web UI uses standard-library HTTP and plain HTML/CSS/JavaScript—no frontend build stack. See the architecture and source map.

Release evidence, not hype

The v1.0 validation record documents 91 passing automated tests and six passing CI jobs, including Linux/Windows fresh installs, minimum supported dependencies, and optional MCP.

These ten fixed-budget cases are regression evidence, not a model ranking or a statistical reliability guarantee. Missing usage stays unknown; token counts are not monetary costs. Reviewed release results.

Boundaries to know

• One active task per shared workspace/database. Web rejects overlap with HTTP 409.
• Remote model services receive prompts and tool results. Personal URLs, keys, and default models belong only in ignored local configuration or the environment.
• History and undo snapshots may contain file text. Protect the SQLite database and back it up before a supported upgrade.
• Python read tools and MCP allowlists are trusted declarations, not sandboxes. Receipt rewrite detection needs a final hash kept outside SQLite.
• No built-in shell, deletion, browser control, semantic memory, scheduling, hidden agents, or general crash-recovery orchestration.

Security policy · Troubleshooting · Maintenance roadmap

Contribute

Small fixes, tests, examples, and documentation are welcome. Report a bug or suggest an improvement, then follow the contribution guide. Keep independently verifiable changes in small commits and preserve the kernel's narrow scope.

MIT license