mecha: Instructions file for Claude Code

mecha — CLAUDE.md

What this is

An agent harness whose purpose is to make a local open-weight model into a usable personal assistant: wired into enough personal context to be worth asking (mail, calendar, a knowledge graph), able to reach the world through a reviewed surface, and safe to hold all of that at once. Almost every design decision here is downstream of that last clause — a personal assistant has private data, third-party content and a way to send by definition, so the lethal trifecta is the permanent condition rather than an edge case.

Four crates:

• mecha-core/ — the library. Knows nothing about any CLI or application.
• mecha-cli/ — the mecha binary. Thin; all logic belongs in core.
• mecha-mail/ — mail, calendar and documents. Mail and calendar sit behind one provider-neutral MCP surface; mecha-docs is a fourth binary on the same library, sharing its OAuth and token lifecycle.
• mecha-slack/ — the Slack transport. No mecha-core dependency, ever; that is the whole reason it is a crate, and it is checkable in Cargo.toml.

Interfaces: mecha run (one-shot), mecha chat (readline REPL), mecha tui (full-screen; the input line stays live so you can steer a run in flight), and mecha batch / mecha eval for fan-out.

The user-facing half of this reasoning is published at https://docs.mecha-factory.ai/, each rule on the page for the feature it governs rather than restated in one place; the standalone principles page was cut on 2026-09-26.

Where everything else lives. This file holds only what any session may need on any run; it is the expensive file, because it rides in every agent's context. docs/ARCHITECTURE.md holds the per-subsystem invariants — read its section before changing a subsystem it names, and put a new subsystem's invariants there, not here. docs/README.md is the map of all the rest — which document holds what, and the routing question to ask before writing a line anywhere. Two of its rules govern this file: state the rule, then the incident in one sentence, never the other way round; and where a topic doc covers something, point at it rather than restating it, because duplication is how documents drift into disagreeing.