Crate mecha_core 

mecha-core — an agent harness for local models.

The library knows nothing about any particular CLI, UI, or project. It gives you four things and lets you wire them together:

• provider — talk to a model (Anthropic, or anything OpenAI-shaped)
• tool — things the agent can do, native or mcp-backed
• agent — the loop that puts those together
• session / batch — persistence and fan-out around the loop

use mecha_core::{agent::Agent, agent::Conversation, config::Config};
use mecha_core::sandbox::Sandbox;
use mecha_core::tool::{ModeApprover, Registry, ToolCtx};
use std::sync::Arc;

let cfg = Config::load(&std::env::current_dir()?)?;
let (_, provider_cfg) = cfg.provider(None)?;

// How `shell` is confined. It decides that tool's declared capabilities,
// so it is built before the registry rather than consulted at call time.
let sandbox = Arc::new(Sandbox::new(cfg.sandbox.clone()));

let agent = Agent::new(
    mecha_core::provider::build(provider_cfg)?,
    Registry::new().with_builtins(&cfg.tools, sandbox),
    Arc::new(ModeApprover { mode: cfg.tools.permission_mode }),
    ToolCtx {
        workspace: std::env::current_dir()?,
        shell_timeout: std::time::Duration::from_secs(cfg.tools.shell_timeout_secs),
        security: cfg.security.clone(),
        ..ToolCtx::default()
    },
    cfg.agent.clone(),
    None,
)?;

// A conversation carries its own taint, so keeping it across turns keeps
// the trifecta interlock honest — see `agent::Conversation`.
let mut convo = Conversation::user("What changed in this repo today?");
let outcome = agent.run(&mut convo, None).await?;
println!("{}", outcome.text);

Re-exports

pub use agent::Agent;

pub use agent::AgentEvent;

pub use agent::RunOutcome;

pub use config::Config;

pub use message::Block;

pub use message::Effort;

pub use message::Message;

pub use message::Role;

pub use message::StopReason;

pub use message::Usage;

Modules

agent

The agent loop.

batch

Run the same agent over many inputs.

cache_lens

The cache lens: is the cached prefix actually being reused?

candidate

A proposed harness change, and the decision about it.

compact

Making a long conversation fit.

config

Layered configuration.

counterfactual

Counterfactual probes: an intervention is a test case.

cron

Five-field cron expressions, resolved in a named timezone.

diagnose

The diagnostic stage: evidence in, a typed candidate out.

distill

Session-end distillation to the personal knowledge graph.

doctor

mecha doctor — every store’s distress, read in one pass.

eval

Grading agent runs.

frontdoor

The quarantine: what a stranger wrote, and what a privileged run may see.

gossip

Gossip: two agents, different sources, generative follow-ups.

harness

Harness rumination: the candidate store behind mecha harness, and the override layer an accepted change rides in.

hooks

Lifecycle hooks: user commands that attach to the loop without touching it.

image

Turning a file on disk into an image block a provider will accept.

learning

The self-learning store: reflections, learned rules, and the miner.

mail_triage

The mail triage store: one typed verdict per thread, and the quarantined pass that produces it.

mailbox

Inter-agent messages: a file-based mailbox between mecha sessions.

mcp

Minimal MCP client over stdio.

message

Provider-agnostic conversation types.

onboarding

What a new install still needs, and the one command that fixes each.

outbox

The outbox: staged outbound actions awaiting the user’s review.

outbox_source

What a staged draft is answering, recovered from the session that staged it.

provider

Model providers.

replay

Re-running a recorded session and diffing what changed.

replay_run

The half of replay that runs: recorded tools, and the loop that drives them.

runlog

The run-quality corpus: every recorded outcome, across every session.

sandbox

Confining shell.

search

Web search.

session

Session transcripts.

skill

Skills: named procedures the user writes and the model loads on demand.

subagent

Subagents.

tool

Tools: the things an agent can actually do.

trigger

Triggers: prompts that run on a schedule, unattended.

work

~/.mecha/work/<producer>/ — where a run’s generated output goes.

Constants

VERSION

Functions

create_private_dir

process_alive

Create a directory (and its parents) and make the leaf owner-only.