ArgentMunch

⚠️ NOT PRODUCTION-READY — Pre-release, under active development. Do not use in production environments.

Token-efficient codebase intelligence for ArgentOS and MAO agents.

ArgentMunch is a fork of jCodeMunch MCP, repurposed and extended for the ArgentOS ecosystem, Claude Code workflows, and the MAO multi-agent cluster (17+ agents).

---

Project Purpose

Most AI agents explore codebases the expensive way — reading entire files, skimming thousands of irrelevant lines, repeating for every agent and every task. At scale, token costs compound fast.

ArgentMunch uses tree-sitter AST parsing to pre-index codebases so agents retrieve exact symbols (functions, classes, methods) instead of reading whole files.

Task	Traditional	ArgentMunch
Find a function	~40,000 tokens	~200 tokens
Understand module API	~15,000 tokens	~800 tokens
Explore repo structure	~200,000 tokens	~2,000 tokens

80–99% token reduction for code exploration tasks.

With 17+ MAO agents all hitting a shared ArgentMunch endpoint, the savings multiply across every agent, every session.

---

Quick Start

Requirements

• Python 3.10+
• pip

Install

cd argentmunch
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"

Index a Local Repo

argentmunch index /path/to/your/repo --no-ai

# Example output:
# ✓ Indexed 37 files, 358 symbols
#   Repo: local/argentmunch
#   Languages: python(37)

Query Symbols

argentmunch query local/argentmunch "search_symbols"

# Example output:
# Search: 'search_symbols' in local/argentmunch
# Found: 4 results (2.2ms)
#
#   1. [function] search_symbols
#      File: src/jcodemunch_mcp/tools/search_symbols.py:11
#      Score: 35

Filter by kind:

argentmunch query local/argentmunch "Calculator" --kind class

Search across all indexed repos:

argentmunch query --all "search_symbols" --max-results 20

List Indexed Repos

argentmunch list

# Indexed repositories: 1
#   • local/argentmunch
#     Files: 37, Symbols: 358

Health Check (CLI)

argentmunch health
# { "ok": true, "version": "0.1.0-mvp", "indexed_repos_count": 1, ... }

Multi-Repo Index Run (Allowlist Config)

# Configure explicit allowlist (deny-by-default once file exists)
mkdir -p ~/.argentmunch
cat > ~/.argentmunch/repos.yaml <<'YAML'
repos:
  - repo: argentaios/argentos
    name: argentos-core
  - argentaios/argentmunch
YAML

# Index all allowlisted repos from config
argentmunch index --config ~/.argentmunch/repos.yaml --incremental

# Manage allowlist from CLI
argentmunch repos list
argentmunch repos add argentaios/another-repo
argentmunch repos remove argentaios/another-repo

When repos.yaml exists, repos not listed are rejected for index/reindex operations.

Manual targeted reindex:

argentmunch reindex argentaios/argentos --config ~/.argentmunch/repos.yaml

Health Check (HTTP)

# Start the health server (token required by default)
export ARGENTMUNCH_HEALTH_TOKEN="replace-me"
argentmunch serve --port 9120

# Unauthorized (missing token)
curl -i http://127.0.0.1:9120/health

# Authorized
curl -s http://127.0.0.1:9120/health \
  -H "Authorization: Bearer $ARGENTMUNCH_HEALTH_TOKEN"

Unauthorized response:

{
  "error": "Unauthorized",
  "reason": "missing_token",
  "hint": "Provide Authorization: Bearer <token>."
}

Authorized response:

{
  "ok": true,
  "version": "0.1.0-mvp",
  "indexed_repos_count": 1,
  "total_symbols": 358,
  "last_indexed_at": "2026-03-04T23:10:05.822416",
  "repos": [
    {
      "repo": "local/argentmunch",
      "symbol_count": 358,
      "file_count": 37
    }
  ]
}

Returns 200 when healthy, 503 when index metadata is corrupt.

Index Freshness Status

argentmunch status --stale-threshold-minutes 30

# or over HTTP:
curl -s http://127.0.0.1:9120/status \
  -H "Authorization: Bearer $ARGENTMUNCH_HEALTH_TOKEN"

Example /status response:

{
  "ok": true,
  "version": "0.1.0-mvp",
  "indexed_repos_count": 1,
  "total_symbols": 358,
  "last_indexed_at": "2026-03-04T23:10:05.822416",
  "stale": false,
  "stale_threshold_minutes": 30,
  "threshold_config_used": {
    "stale_threshold_minutes": 30,
    "source_env": "ARGENTMUNCH_STALE_THRESHOLD_MINUTES"
  }
}

Secure Health + Webhook Configuration

# Recommended in shared environments:
export ARGENTMUNCH_HEALTH_TOKEN="replace-me"
export ARGENTMUNCH_WEBHOOK_SECRET="replace-me"

# Optional env fallback allowlist (used only when repos.yaml is absent)
export ARGENTMUNCH_REPO_ALLOWLIST="argentaios/argentos,argentaios/*"

# Stale threshold for /status and `argentmunch status`
export ARGENTMUNCH_STALE_THRESHOLD_MINUTES=60

By default, argentmunch serve now binds to 127.0.0.1 (local-safe default).
By default, /health and /status require Authorization: Bearer <token>. For explicit localhost-only dev mode without a token, set ARGENTMUNCH_HEALTH_LOCAL_DEV=true or start with argentmunch serve --health-local-dev.

Webhook trigger simulation (POST /webhook, GitHub push event):

payload='{"repository":{"full_name":"argentaios/argentos"}}'
sig=$(printf '%s' "$payload" | openssl dgst -sha256 -hmac "$ARGENTMUNCH_WEBHOOK_SECRET" | sed 's/^.* //')

curl -X POST http://127.0.0.1:9120/webhook \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -H "X-Hub-Signature-256: sha256=$sig" \
  -d "$payload"

Example response:

{
  "ok": true,
  "event": "push",
  "repo": "argentaios/argentos",
  "accepted": true,
  "reason": "scheduled",
  "retry_after_seconds": null,
  "status": {
    "repo": "argentaios/argentos",
    "in_progress": true
  }
}

---

MCP Server Mode

ArgentMunch also runs as an MCP server for Claude Code / Claude Desktop:

argentmunch-mcp

Add to your MCP server config:

{
  "mcpServers": {
    "argentmunch": {
      "command": "argentmunch-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

---

Benchmark

Run the benchmark to compare brute-force file scans vs. symbol queries:

python scripts/benchmark_mvp.py

Results (indexing ArgentMunch's own codebase):

Scenario	Brute-force	Symbol query	Savings
Broad search (index)	59,738 tokens	441 tokens	99.3% (135x)
Specific lookup (save_index)	59,738 tokens	286 tokens	99.5% (209x)
Cross-cutting (parse file)	59,738 tokens	531 tokens	99.1% (113x)

Full report: docs/benchmarks/mvp-baseline.md

---

Tests

source .venv/bin/activate
python -m pytest tests/test_mvp.py -v

17 tests covering: index success/failure/empty/incremental, query hit/miss/filter/methods, health empty/populated/HTTP/corrupt, CLI integration.

---

Architecture

                    ┌─────────────────────────────┐
                    │      ArgentMunch Server      │
                    │   (Dell R750, always-on)     │
                    │                              │
                    │  ┌──────────────────────┐   │
                    │  │   Symbol Index Store  │   │
                    │  │   ~/.code-index/      │   │
                    │  │   (tree-sitter AST)   │   │
                    │  └──────────────────────┘   │
                    └──────────┬──────────────────┘
                               │ MCP Protocol
              ┌────────────────┼────────────────┐
              │                │                │
       ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
       │ Claude Code │  │  MAO Agent  │  │  MAO Agent  │
       │  (Mac M3)   │  │  (Argent)   │  │  (Titan)    │
       └─────────────┘  └─────────────┘  └─────────────┘
              ... and 15+ more agents

---

Docs

• MVP Status
• Full Project Epic
• Roadmap
• Benchmarks
• Security Policy
• License Check
• Upstream Architecture

---

Upstream

• jCodeMunch MCP: https://github.com/jgravelle/jcodemunch-mcp
• License: See LICENSE_CHECK.md — ⚠️ pending legal review

---

Part of the ArgentOS ecosystem.