idkmesh

Getting Started: Using IDKMesh

IDKMesh is currently an alpha research and engineering project, not a finished one-click multi-agent product. The most practical user-facing surface today is the idkmesh gate-audit CLI. The repository also includes an executable contract demo and a contribution/research environment.

This guide answers two questions:

  1. Who should use IDKMesh today?
  2. What is the shortest path to use it successfully?

Who should use IDKMesh today?

1. Engineering teams that use multiple reviewers or AI judges

Use idkmesh gate-audit when a code-review, evaluation, moderation, or acceptance gate collects multiple accept/reject verdicts and you can provide ground truth for an audited candidate set.

Typical examples:

The audit asks a specific question: how much independent evidence is the panel actually producing?

2. Researchers working on multi-agent systems or collective intelligence

Use the repository when you want reproducible contracts, simulations, experiments, provenance checks, or benchmark infrastructure for studying coordination, verification, decomposition, reviewer dependence, governance, or human/AI collaboration.

3. Open-source maintainers and platform engineers

Use the project as a reference for bounded task contracts, worker/verifier separation, provenance, GitHub-native evidence, and explicit integration authority.

4. Contributors who want to build the Verified Swarm Runner

The end-to-end Git-native Verified Swarm Runner is still being developed. Contributors can work on the runner, adapters, schemas, experiments, CI, documentation, security, community systems, or verification tooling.

Who should not expect a finished product yet?

IDKMesh is not yet the right choice if you need:

The current system deliberately keeps this authority boundary:

worker success != acceptance
verification recommendation != merge authority
CI success != independent human review

Path A: Try the contract demo

This is the fastest way to understand the core trust model.

Step 1 — Install prerequisites

You need:

No model account or API key is required for the demo.

Step 2 — Clone the repository

git clone https://github.com/MSKazemi/idkmesh
cd idkmesh

Step 3 — Create a virtual environment

Linux/macOS:

python -m venv .venv
source .venv/bin/activate

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-phase0.txt
.\.venv\Scripts\python.exe scripts\demo.py

Step 4 — Install demo dependencies

Linux/macOS:

python -m pip install -r requirements-phase0.txt

Step 5 — Run the demo

python scripts/demo.py

The demo validates committed synthetic fixtures. It intentionally checks both valid and invalid contracts, including rejection of self-acceptance, non-independent verification, missing security bounds, and mismatched provenance.

Passing the demo means the contract validators behave as expected on those fixtures. It does not prove real-world worker independence or approve any change for merge.

Path B: Audit a review or verifier panel

This is the most directly usable product surface today.

Step 1 — Install the CLI

From the repository root:

pip install .

Confirm installation:

idkmesh --version

Step 2 — Run the bundled example

idkmesh gate-audit examples/gate-audit/panel-votes.example.json --pretty

To save both machine-readable and human-readable output:

idkmesh gate-audit examples/gate-audit/panel-votes.example.json \
  --out gate-audit.json \
  --markdown gate-audit.md \
  --pretty

Step 3 — Prepare your own verdict matrix

Create a JSON file with:

Minimal shape:

{
  "gate_id": "my-review-gate",
  "evidence_class": "observed",
  "quorum": 0.5,
  "candidates": [
    {"id": "c01", "ground_truth": "accept"},
    {"id": "c02", "ground_truth": "reject"},
    {
      "id": "p01",
      "ground_truth": "reject",
      "probe": true,
      "probe_kind": "seeded-defect"
    }
  ],
  "verifiers": [
    {
      "id": "reviewer-a",
      "verdicts": {
        "c01": "accept",
        "c02": "reject",
        "p01": "reject"
      }
    }
  ]
}

For meaningful panel statistics, use more than the minimal toy example. The contract requires at least two non-probe candidates and one verifier.

Step 4 — Run the audit on your data

idkmesh gate-audit my-panel-votes.json \
  --out my-panel-report.json \
  --markdown my-panel-report.md \
  --pretty

Exit code 0 means success. Input/usage failures return 2.

Step 5 — Read the important results

Focus on:

A panel can have many nominal reviewers but much less independent evidence if their errors are strongly correlated.

Step 6 — Use the result as a diagnostic, not an authority decision

gate-audit does not run your reviewers, select candidates, accept work, or merge code. It measures a verdict matrix that you already collected.

Use the result to ask better operational questions, for example:

Path C: Add Gate Audit to GitHub Actions

A repository can run the audit in CI:

- uses: MSKazemi/idkmesh/actions/gate-audit@main
  with:
    votes-file: path/to/panel-votes.json

Treat the output as diagnostic evidence unless your own repository policy explicitly defines how that evidence is used.

Path D: Contribute to IDKMesh itself

Step 1 — Read the public front door

Read:

  1. README.md
  2. CONTRIBUTING.md
  3. COMMUNITY.md

You do not need to read the full research archive first.

Step 2 — Choose a contribution path

Useful paths include:

Step 3 — Check current work before starting

Look at open issues, assignees, recent comments, and linked pull requests. State the bounded change you intend to make so work is not duplicated.

Step 4 — Make a focused branch and change

Prefer a small, reviewable change with explicit evidence or tests.

Step 5 — Run repository checks

On POSIX environments:

make setup
make test
make integration

Portable Python fallback:

python -m pip install --disable-pip-version-check pytest
python -m pip install --disable-pip-version-check -r requirements-phase0.txt
python -m pytest -q

If you change Markdown, also run:

python scripts/check_links.py

Step 6 — Open a pull request

Describe:

AI-assisted contributions are welcome, but material generated work should be reviewed and its provenance noted when practical.

Advanced use: WorkUnits, adapters, and the future runner

The repository already contains versioned WorkUnit, ResultManifest, EvaluatorPlan, and VerificationResult contracts plus protocol-neutral adapters and A2A/MCP mappings.

The target lifecycle is:

bounded repository task
  -> WorkUnit
  -> replaceable worker adapter
  -> candidate artifacts + ResultManifest
  -> verifier-owned EvaluatorPlan
  -> independent VerificationResult
  -> evidence/reporting
  -> explicit human/governance integration decision

These pieces are suitable for contributors and researchers today, but they are not yet packaged as a polished general-purpose swarm application.

A simple rule for deciding where to start

Where to ask questions

Use GitHub Discussions for broad questions and ideas. Use issues for defects or bounded actionable work. Follow SECURITY.md rather than a public issue for security vulnerabilities.

This site is open source. Improve this page.