Metadata-Version: 2.4
Name: jcodemunch-cli
Version: 1.0.0
Summary: CLI wrapper for jcodemunch-mcp - Token-efficient code exploration
Author-email: Your Name <you@example.com>
License: MIT
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

# jCodeMunch CLI

A thin CLI wrapper for [jcodemunch-mcp](https://github.com/jgravelle/jcodemunch-mcp) — token-efficient code exploration via tree-sitter AST parsing.

**Key feature:** Uses `uvx` to always stay up to date with the latest jcodemunch-mcp. No manual updates needed.

## Why This Exists

jcodemunch-mcp is MCP-only (no CLI). This wrapper gives you a CLI that works anywhere:
- Sub-agents via exec
- Scripts
- CI/CD pipelines
- Any AI that can run shell commands

## Installation

### Option 1: pip (recommended)

```bash
pip install jcodemunch-cli
```

Or with uv:

```bash
uv pip install jcodemunch-cli
```

### Option 2: Development Install

```bash
git clone https://github.com/your-org/jcodemunch-cli.git
cd jcodemunch-cli
pip install -e .
```

### Option 3: Standalone Script

If you just want to run it directly:

```bash
# Requires Python 3.10+ and uv
uv run jcodemunch-cli list-tools
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_TOKEN` | No | GitHub token for private repos |
| `OPENAI_API_KEY` | No | API key for AI summaries |
| `OPENAI_API_BASE` | No | API base URL (default: https://api.minimax.chat/v1) |
| `ANTHROPIC_API_KEY` | No | Anthropic key for Claude summaries |
| `GOOGLE_API_KEY` | No | Google key for Gemini summaries |

### Set up GitHub Token (optional)

```bash
# Using your existing gh CLI
export GITHUB_TOKEN=$(gh auth token)

# Or create a personal access token
# https://github.com/settings/tokens
export GITHUB_TOKEN=ghp_your_token_here
```

## Usage

### Index a Repository

```bash
# Index a GitHub repository
jcodemunch index-repo owner/repo

# Index a local folder
jcodemunch index-folder /path/to/code
```

### Search for Code

```bash
# Search symbols by name
jcodemunch search-symbols --repo owner/repo login

# Get exact symbol code
jcodemunch get-symbol --repo owner/repo "src/main.py::UserService.login#method"

# Get all symbols in a file
jcodemunch file-outline --repo owner/repo src/main.py

# Get repo overview
jcodemunch repo-outline owner/repo

# Full-text search
jcodemunch search-text --repo owner/repo "TODO"
```

### List Indexed Repos

```bash
jcodemunch list-repos
```

## For AI Agents

### OpenClaw Sub-agents

Add to your skill or agent workflow:

```python
# Agent calls via exec
exec → jcodemunch search-symbols --repo owner/repo functionName
```

### Claude Code (MCP)

Use the native MCP integration instead (recommended for Claude Code):

```json
{
  "mcpServers": {
    "jcodemunch": {
      "command": "uvx",
      "args": ["jcodemunch-mcp"]
    }
  }
}
```

### Any Other AI

If your AI can run shell commands, it can use this CLI:

```
Agent: "Find the login function"
→ exec: jcodemunch search-symbols --repo owner/repo login
→ Returns: [list of matching symbols]
→ exec: jcodemunch get-symbol --repo owner/repo "src/auth.py::login#function"
→ Returns: exact function code
```

## Token Savings

| Task | Traditional | jCodeMunch |
|------|-------------|------------|
| 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 |

**95%+ token reduction** on code exploration tasks.

## Requirements

- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (for automatic jcodemunch-mcp updates)
- GitHub token (optional, for private repos)

## How It Works

This package is a **thin wrapper** that:

1. Uses the `mcp` Python library to handle the MCP protocol
2. Calls `uvx jcodemunch-mcp` under the hood
3. Passes through environment variables for API keys

Because it uses `uvx`, you always get the latest jcodemunch-mcp version — no manual updates required.

## License

MIT
