If the rest of the repository feels complicated, start here.
IDKMesh helps humans and AI agents work together without trusting the first answer automatically.
Think of it as a combination of:
The long-term goal is to make this useful for large teams of people, AI agents, software tools, and computers.
Today, IDKMesh is still an alpha research and engineering project. It is not yet a finished one-click AI swarm product.
Imagine you ask one AI agent:
“Please change my software.”
The agent may produce a good answer, but it may also make a mistake.
Now imagine you ask five AI agents. That sounds safer, but the five agents may make the same mistake. Five answers do not automatically mean five independent opinions.
IDKMesh is trying to solve problems like these:
Big work is hard to control.
A large goal should be split into small, bounded jobs.
AI can be confidently wrong.
The system should not trust a worker just because it says “done.”
More reviewers do not always mean more safety.
Several reviewers may repeat the same error.
It is often unclear who did what.
The project keeps provenance: records of workers, inputs, outputs, checks, and evidence.
The same actor should not create and approve its own result.
Work and verification are separated.
Automation should not silently gain authority.
A successful worker, verifier, or CI check does not automatically get merge authority.
The basic rule is:
worker says "done"
!=
work is accepted
Suppose you want to add a login feature to a project.
Without a verification-first process:
AI writes code
->
AI says it works
->
code is accepted
With the IDKMesh idea:
Goal: add login
->
Create a small, clear task
->
Worker writes the code
->
Worker records what it changed
->
A separate verifier checks it
->
Tests and evidence are recorded
->
A human or governance rule decides whether to integrate it
The important difference is that the worker does not approve itself.
You do not need to remember the technical names yet. The basic flow is:
Example:
“Fix this bug.”
IDKMesh calls a bounded task a WorkUnit.
A WorkUnit tries to make the job clear:
The worker could be:
The result should include information about what was produced and where it came from.
This helps answer:
“What created this result, from what inputs, and under what rules?”
A different verifier checks the result.
The verifier should not simply trust the worker’s claim.
The system records what was checked and what the verifier found.
Even a successful verification is not automatically permission to merge or publish.
The final authority remains separate.
There are three useful ways to use the repository right now.
This is the easiest way to understand the trust model.
You need:
Clone the project:
git clone https://github.com/MSKazemi/idkmesh
cd idkmesh
Create a Python environment on Linux/macOS:
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-phase0.txt
Run the demo:
python scripts/demo.py
The demo deliberately tests both valid and invalid examples.
For example, it checks that the system rejects cases where:
No AI API key is required for this demo.
idkmesh gate-auditThis is the most immediately usable product in the repository today.
Install it from the repository:
pip install .
Run the included example:
idkmesh gate-audit examples/gate-audit/panel-votes.example.json --pretty
The tool helps answer a question like:
“I have several reviewers. Are they really giving me several independent checks, or are they mostly making the same mistakes?”
It looks at reviewer/verifier results and reports things such as:
This can be useful if you use:
It is a diagnostic tool. It does not approve code or make merge decisions.
For your own review data, continue with Getting Started.
The complete Git-native Verified Swarm Runner is still being developed.
You can contribute without understanding the entire project.
Useful entry points include:
Imagine you use five AI models to review generated code.
All five say:
“Looks good.”
You may think you have five independent confirmations.
But if all five models learned similar patterns, use similar prompts, or fail on the same kind of bug, the five votes may contain much less independent information than you think.
IDKMesh’s current gate-audit tool is designed to measure this kind of problem from verdict data that you already collected.
That is one concrete problem the repository can help with today.
Do not expect the current repository to:
Those are either outside the project or still future work.
IDKMesh is most useful today for:
If you only want a simple chatbot or a finished autonomous coding swarm, IDKMesh is not that product yet.
| Word | Very simple meaning |
|---|---|
| WorkUnit | A small job with clear limits |
| Worker | The person, AI, or tool doing the job |
| Result | What the worker produced |
| Verifier | A separate checker |
| Evidence | Information showing what was tested or observed |
| Provenance | The history of where a result came from |
| Gate | A checkpoint before something is accepted |
| Integration | Putting an accepted change into the main project |
| Mesh | A network of different people, agents, tools, and computers |
| IDK | “I don’t know” — uncertainty should be visible instead of hidden |
You can understand most of IDKMesh by remembering this:
Do not trust an answer only because it was produced. Check it independently, keep the evidence, and keep final authority separate.
If you are completely new, use this order:
python scripts/demo.py.idkmesh gate-audit.You do not need to understand the whole repository before trying those steps.