ichnus2

Ichnus is a stigmergic ant-swarm for bug localization. Isolated LLM ants score one file each against a bug report, deposit confidence-weighted heat onto a shared board, and spread it along the import graph with hop decay.

A median-of-3 pass catches random noise. A prosecutor / judge catches confidently wrong answers. You get a HOT / WARM / COLD markdown heatmap plus a full JSON audit trail — callable from Claude Code via MCP.

uv sync
ICHNOS_MOCK=0 uv run python -m ichnos2.demo_runner /path/to/repo \
  "query string drops the first parameter" ""

Why it exists

Grepping a bug description finds similar code. Agents that read the whole repo burn tokens and still guess. Ichnus treats localization as a swarm search with a hard spend ceiling:

• Ants never talk to each other — they only write the board (O(A) cost, not O(A²))

• Heat propagates along real import edges, so neighbours of a hot file get scouted next

• Total ant spend is bounded — wave i uses A0 / 2^i, so spend stays < 2 · A0

• Two verifiers, two failure modes — median-of-3 for random noise; prosecutor/judge for confidently wrong answers

Related MCP server: agentguard

Architecture

System

Pipeline

Stigmergy

Ant-scored heat is a measurement and never evaporates. Propagated heat is a hypothesis and does. Recruitment makes this a swarm instead of a fixed ranked list: the next wave follows the trail.

Verification

Stage 7 catches random variance. Stage 8 catches systematic error — a model that is confidently wrong every time. Median-of-3 cannot fix that; changing the question can.

Quick start

Requires Python 3.11+ and uv.

git clone https://github.com/Sharann-del/Ichnus.git
cd Ichnus
uv sync

Offline demo (no API key)

uv run python -m ichnos2.demo_runner /path/to/repo \
  "login fails with empty password" ""

Live run

Put a key in .env (never commit it):

GEMINI_API_KEY=...
# or
OPENROUTER_API_KEY=...

Then set mock mode explicitly whenever a key is present:

ICHNOS_MOCK=0 uv run python -m ichnos2.demo_runner /path/to/repo \
  "bug description" "optional stack trace"

Gemini free tier is the practical default for multi-ant waves. OpenRouter’s free quota is easy to exhaust on a mid-size repo; Ichnus fails fast with the reset time rather than spinning on a spent daily limit.

Tests

uv run pytest tests/test_algorithm.py -v

98 tests, no network required.

MCP (Claude Code / any MCP client)

.mcp.json in the project root:

{
  "mcpServers": {
    "ichnus2": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python3", "-m", "ichnos2.mcp_server"],
      "env": {
        "ICHNOS_MOCK": "0",
        "ICHNOS_PROVIDER": "gemini"
      }
    }
  }
}

Tool: locate_bug_tool(repo_path, bug_description, stack_trace="")
Returns the same markdown heatmap as the CLI. Audit JSON lands at <repo>/.ichnos2/last_audit.json.

uv run python -m ichnos2.mcp_server
# or
uv run ichnos2-mcp

What you get

Markdown heatmap — HOT / WARM / COLD bands with scores, reasons, line ranges, and verification notes.

JSON audit — full board state, ant verdicts, cache provenance, and demotion history under .ichnos2/.

The heatmap is a suggestion for where to read next, not a verdict. Keep using normal file tools after.

How a wave spends budget

Wave i scouts roughly A0 / 2^i files. Across any finite number of waves:

total spend = A0 · (2 − 2^(1−n))  <  2 · A0

This is asserted in the test suite (test_total_budget_bound_proof), not just documented.

Tests and example apps are excluded from scouting by default. A path named in a stack trace is always kept.

Verified results

Measured on this codebase — not invented:

Design choices that matter

• Confidence-weighted deposit — ranking uses relevance × confidence

• Hop decay — γ^hop from the nearest ant-sourced HOT file; cycle-safe BFS

• Bounded demotion — never below floor × peak

• Provenance-aware cache — mock and live scores never poison each other

• Rate-limit aware client — per-minute limits waited out; daily quota stops the run

• Overlapping file windows — strongest finding wins (averaging dilutes the truth)

Limitations

• Accuracy is solidly shown on one real bug (Express) plus synthetics — not a broad hit-rate study

• Ants read one file at a time; they cannot run a repro or reason about whole-repo architecture

• Non-Python import edges are regex-based; only Python uses AST for authoritative contradictions

• “Embedding” similarity in Stage 1 is a bag-of-words TF cosine proxy, not a neural embedding

• Live mode sends file contents to Gemini or OpenRouter — no local-model path yet

• Free-tier quotas can make “fast” and “works” mutually exclusive

Project layout

ichnos2/
  locate_bug.py
  candidate_filter.py
  budget.py / priority.py
  ants.py
  board.py
  reliability.py
  verify.py
  aggregate.py
  llm_client.py
  mcp_server.py
  demo_runner.py
tests/
  test_algorithm.py

License

MIT © 2026 Sharann Manojkumar