Metadata-Version: 2.4
Name: shortcode
Version: 0.1.0
Summary: Extract compact structural maps from source code to save LLM tokens
Author-email: Ahmet Bekcan <ahmetbekcan26@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ahmetbekcan/shortcode
Project-URL: Repository, https://github.com/ahmetbekcan/shortcode
Project-URL: Issues, https://github.com/ahmetbekcan/shortcode/issues
Keywords: llm,code-analysis,tree-sitter,context,tokens
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: tree-sitter-c-sharp>=0.23.5
Requires-Dist: tree-sitter-cpp>=0.23.4
Requires-Dist: tree-sitter-go>=0.25.0
Requires-Dist: tree-sitter-java>=0.23.5
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-php>=0.24.1
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-ruby>=0.23.1
Requires-Dist: tree-sitter-rust>=0.24.2
Requires-Dist: tree-sitter-typescript>=0.23.2
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Dynamic: license-file

# shortcode

> Extract compact structural maps from source code — designed to reduce LLM context usage.

[![CI](https://github.com/ahmetbekcan/shortcode/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmetbekcan/shortcode/actions)
[![PyPI](https://img.shields.io/pypi/v/shortcode)](https://pypi.org/project/shortcode/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/shortcode)](https://pypi.org/project/shortcode/)

When working with an LLM on a large codebase, dumping entire source files into the context is expensive and slow. **shortcode** generates a `.meta` file for each source file — a one-line-per-symbol summary that tells the LLM *where* everything lives without wasting tokens on implementation details.

**Workflow:**
1. Run `shortcode ./src` once to generate `.meta` files
2. Feed the LLM the relevant `.meta` files (tiny)
3. Ask it to read only the specific functions it needs
4. The LLM reads targeted line ranges from the originals

---

## What it looks like

Given `auth.py`:

```python
class TokenManager:
    def __init__(self, secret): ...
    def generate(self, user_id): ...
    def verify(self, token): ...
```

`shortcode` produces `auth.py.meta`:

```
[py] src/auth.py
IMPORT flask,jwt,datetime
CLASS TokenManager:4-52
  __init__:5-9
  generate:11-24
  verify:26-38
FN hash_password:54-61
FN check_password:63-70
```

~15 tokens instead of ~400. The LLM asks to see lines 11-24 when it needs `generate`.

---

## Supported languages

| Language       | Extensions                          |
|----------------|-------------------------------------|
| Python         | `.py`                               |
| JavaScript     | `.js` `.mjs` `.cjs`                 |
| TypeScript     | `.ts` `.tsx`                        |
| Java           | `.java`                             |
| C#             | `.cs`                               |
| C / C++        | `.cpp` `.cc` `.cxx` `.hpp` `.h`     |
| Go             | `.go`                               |
| Rust           | `.rs`                               |
| Ruby           | `.rb`                               |
| PHP            | `.php`                              |

Powered by [tree-sitter](https://tree-sitter.github.io) — real AST parsing, no regex heuristics.

---

## Installation

```bash
pip install shortcode
# or
uv add shortcode
```

**No Python?** Download the pre-built Windows executable from [Releases](https://github.com/ahmetbekcan/shortcode/releases).

---

## CLI usage

```bash
# Scan a folder — writes .meta next to each source file
shortcode ./src

# Write all .meta files to a separate directory
shortcode ./src --output-dir ./meta

# Only process specific extensions
shortcode ./src --ext py ts java

# Top-level only (no subdirectories)
shortcode ./src --no-recursive
```

Double-clicking the `.exe` opens an interactive prompt asking for the folder path.

---

## Python API

```python
from shortcode import parse_file
from pathlib import Path

meta = parse_file(Path("src/auth.py"))

print(meta.language)          # "py"
print(meta.imports)           # ["flask", "jwt", "datetime"]

for cls in meta.classes:
    print(cls.name, cls.line_start, cls.line_end)
    for method in cls.methods:
        print("  ", method.name, method.line_start)

for fn in meta.functions:
    print(fn.name, fn.line_start)
```

---

## Claude Code integration (MCP)

shortcode ships an MCP server so Claude Code (and any MCP-compatible agent) can call it as a tool directly — no manual `.meta` file management needed.

### Install with MCP support

```bash
pip install "shortcode[mcp]"
# or
uv add "shortcode[mcp]"
```

### Register in Claude Code

Add to your `~/.claude.json` (global) or `.claude/settings.json` (project):

```json
{
  "mcpServers": {
    "shortcode": {
      "command": "shortcode-mcp"
    }
  }
}
```

Or with `uvx` (no install needed):

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

### Available tools

| Tool | Description |
|---|---|
| `scan_folder(path, extensions?, recursive?)` | Scan a folder and return structural maps for all source files |
| `brief_file(path)` | Return the structural map of a single source file |

### Example session

```
You:   scan my src/ folder

Claude: [calls scan_folder("src/")]

       [py] src/auth.py
       IMPORT flask,jwt,datetime
       CLASS TokenManager:12-87
         __init__:13-18
         generate:20-35
         verify:37-52

       [py] src/models.py
       CLASS User:4-31
         ...

You:   show me the generate method

Claude: [reads src/auth.py lines 20-35]
```

> **Other MCP clients:** The same `shortcode-mcp` server works with Cursor, Windsurf, and any agent that supports the Model Context Protocol.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Adding support for a new language takes about 10 lines.

---

## License

MIT © [Ahmet Bekcan](https://github.com/ahmetbekcan)
