agentmesh-core

AgentMesh

Local-first multi-agent coordination and provenance for coding workflows.

AgentMesh adds deterministic coordination (claims, waits, steals), commit-linked lineage (AgentMesh-Episode trailers + weave events), and portable handoff bundles (.meshpack) on top of normal git workflows.

Install

pipx install agentmesh-core   # recommended (isolated)
# or
pip install agentmesh-core

# optional: commit witness signing (Ed25519)
pipx install "agentmesh-core[witness]"

Quick Start

cd your-repo
agentmesh init --install-hooks    # set up mesh + Claude Code hooks
agentmesh doctor                  # verify everything is wired correctly

agentmesh task start --title "Fix login timeout" \
  --claim src/auth.py --claim tests/test_auth.py

# edit + stage as normal
git add src/auth.py tests/test_auth.py

agentmesh task finish --message "Fix login timeout handling" \
  --run-tests "pytest -q tests/test_auth.py"
# ^ commits with AgentMesh-Episode trailer, emits capsule, releases claims

How It Works

When multiple AI agents (or humans) work in the same repo, AgentMesh prevents chaos:

• Claims: agents lock files/ports/resources before editing. Conflicts are blocked, not merged.
• Episodes: every work session gets a unique ID (ep_...) that binds claims, capsules, and commits.
• Capsules: structured context bundles (SBAR format) for zero-ramp-up handoffs between agents.
• Weaver: hash-chained provenance linking capsules to git commits. Every change is traceable.
• Commit trailers: agentmesh commit injects AgentMesh-Episode: by default, and can attach signed witness trailers (AgentMesh-KeyID, AgentMesh-Witness, AgentMesh-Sig + portable witness payload chunks) when witness support + keys are present.

Optional Witness Signing

If installed with agentmesh-core[witness], you can sign commit witnesses locally:

agentmesh key generate
agentmesh commit -m "Fix timeout handling"
agentmesh witness verify HEAD

Witness verification is portable: the signed witness payload is embedded in commit trailers, so CI and other machines can verify without local sidecar state.

CI Integration

Add agentmesh-action to check lineage coverage on PRs:

# .github/workflows/lineage.yml
name: Lineage Check
on: [pull_request]

permissions:
  contents: read
  pull-requests: write

jobs:
  lineage:
    runs-on: ubuntu-latest
    steps:
      - uses: Haserjian/agentmesh-action@v1

The action posts a sticky PR comment showing commit coverage. Set require-trailers: "true" to enforce episode lineage, and verify-witness: "true" + require-witness: "true" to enforce cryptographic witness verification.

Documentation Policy

• Public/private split guidance: docs/public-private-boundary.md
• Decision matrix + release gate: docs/public-private-decision-matrix.md
• Alpha gate operator runbook: docs/alpha-gate-runbook.md
• License transition policy: docs/license-policy.md

Generated canary artifacts (CI logs, raw gate reports) should be treated as private by default. Publish sanitized summaries/templates for OSS.

Use the classifier before publishing:

agentmesh classify --staged --fail-on-private --fail-on-review

Release preflight (deterministic gate for agents/automation):

agentmesh release-check --staged --require-witness --json

Sanitize private alpha gate artifacts before publishing:

agentmesh sanitize-alpha-gate-report \
  --in .agentmesh/runs/alpha-gate-report.json \
  --out docs/alpha-gate-report.public.json

CI rollout recommendation:

• Start with non-blocking release-check preview artifacts.
• Keep private-artifact blocking enabled.
• Switch release-check to blocking after policy tuning.

License

AgentMesh is licensed under Apache-2.0 for current and future development.

Published releases up to and including v0.7.0 remain under MIT as originally released.