agentRamen

# agentRamen

<!-- mcp-name: io.github.palrajjp/agentramen -->

<p align="center"><img src="https://raw.githubusercontent.com/palrajjp/agentRamen/main/agentramen/assets/agentramen-logo.png" alt="agentRamen logo" width="520"></p>

[![CI](https://github.com/palrajjp/agentRamen/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/palrajjp/agentRamen/actions/workflows/tests.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/agentramen)](https://pypi.org/project/agentramen/)
[![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-4C8BF5.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/palrajjp/agentRamen?style=social)](https://github.com/palrajjp/agentRamen/stargazers)

Apache-2.0 licensed. See the [security policy](SECURITY.md) and [community code of conduct](CODE_OF_CONDUCT.md).

agentRamen indexes source structure and Git history, then retrieves task-relevant files and excerpts. It is local-first by default: each developer keeps a private SQLite index. Teams can optionally publish sanitized, commit-pinned snapshots to a centrally hosted, OIDC-protected read-only MCP service.


## Quick start

Install agentRamen, then run it from the repository you want to explore:

<img width="1048" height="642" alt="agentramen-demo" src="https://github.com/user-attachments/assets/668053b5-5dae-4184-a645-a86e96b78352" />

```bash
python -m pip install agentramen
cd /path/to/your/repository
agentramen init
agentramen context "Add authentication" --budget 2000
agentramen impact src/auth.py
```

`agentramen init` creates the configuration, indexes the repository, and offers an optional GitHub Actions caller workflow. The index is stored locally in `.agentramen/graph.db`.

Try it in 30 seconds with [`examples/demo.sh`](examples/demo.sh). See the [roadmap](ROADMAP.md) and [contributing guide](CONTRIBUTING.md).

A minimal [VS Code extension](vscode-extension/README.md) is also available.

## What it can do

- **Find task context:** rank files using paths, symbols, imports, Git history, and optional local semantic similarity.
- **Explain change impact:** inspect dependencies, dependents, co-changes, hotspots, and file history.
- **Map repository structure:** explore architecture, export the graph, and query cached commit snapshots.
- **Connect to coding agents:** use local MCP stdio, the browser UI, or an optional authenticated centralized MCP service.
- **Keep local indexes private:** in local mode, the database and optional embeddings stay in each checkout; central mode transfers only an explicit sanitized snapshot to infrastructure you operate.

## How it works

```mermaid
flowchart LR
  repo[Working tree and Git history] --> indexer[Indexer and language analyzers]
  indexer --> db[(Local SQLite graph)]
  optional[Optional local embeddings] --> db
  task[Task or query] --> clients[CLI, MCP, or local HTTP]
  clients --> retrieve[Retrieval and graph queries]
  retrieve <--> db
  retrieve --> excerpts[Ranked files and source excerpts]
```

The default install uses the Python standard library and conservative analysis for other languages. Optional extras add Tree-sitter parsing, local semantic retrieval, and model-aware token counting.

## Optional extras

```bash
python -m pip install 'agentramen[treesitter]'
python -m pip install 'agentramen[semantic]'
python -m pip install 'agentramen[tokenizer]'
python -m pip install 'agentramen[central]'
```

The default install has no runtime dependencies. Tree-sitter, semantic embeddings, tokenizers, and the remote MCP service are opt-in. Semantic model setup may download weights on first use; inference runs locally.

`agentramen init` creates `.agentramen.yml` and a GitHub Actions caller workflow if they do not exist, then creates/updates `.agentramen/graph.db`. `agentramen update` and `agentramen index` incrementally refresh changed files. The database is ignored by Git.

In local mode, source excerpts and optional embeddings stay in `.agentramen/graph.db`. Central snapshot mode transfers indexed source that passes credential heuristics to your private central service; review your organization's data-handling requirements before enabling it.

## Publishing releases

Configure a PyPI trusted publisher for `palrajjp/agentRamen`, using the
`.github/workflows/publish.yml` workflow and the `pypi` environment. To publish
a release, update the version in `pyproject.toml` and `agentramen/__init__.py`,
create a matching `v`-prefixed Git tag, and publish a GitHub release for that
tag. The workflow builds the distributions and publishes them to PyPI using OIDC.

### Configuration

agentRamen reads the following fields from `.agentramen.yml`:

```yaml
version: 1
indexing:
  incremental: true
git:
  history: true
  co_changes: true
history:
  commits: 100
semantic:
  enabled: false
  model: BAAI/bge-small-en-v1.5
context:
  default_budget: 2000
  tokenizer_model: ""
ignore:
  - .env
  - "*.pem"
  - private/
```

`indexing.incremental: false` reparses every eligible file on each index. `git.history: false` removes stored commit, rename, and co-change history; enabling it later rebuilds the configured recent history. `history.commits` controls retained commits (1–100,000), and `git.co_changes` toggles co-change edges. `context.default_budget` is used by the CLI, MCP, and HTTP API when no budget is passed. Configuration is a dependency-free YAML subset; unsupported/malformed values are rejected with a setting-specific error. `.agentramenignore` patterns are added to, rather than replacing, the built-in and YAML ignore rules.

`semantic.enabled: true` opts into local embedding generation and semantic context ranking; install `agentramen[semantic]` first. `semantic.model` selects a FastEmbed model. `agentramen[treesitter]` opts into Tree-sitter-based parsing for supported non-Python languages; without it, or if a grammar is unavailable, agentRamen falls back to regex analysis.

`context.tokenizer_model` optionally selects a model supported by `tiktoken` for tokenizer-based context budgets; install `agentramen[tokenizer]` to use it. The tokenizer vocabulary may be downloaded and cached on first use, then counting runs locally. Leave it empty to use the dependency-free approximate character-based fallback. Context responses identify `token_count_method` (`tiktoken` or `approximate`) and the tokenizer model when configured. The reported total budgets the selected files, team memories, and path/digest/commit evidence together; per-file counts are provided as `estimated_tokens`.

## Commands

```text
agentramen init
agentramen index [--json]
agentramen update [--json]
agentramen status [--json]
agentramen context "Add OAuth login" [--budget 2000] [--json]
agentramen impact src/auth/AuthService.ts [--json]
agentramen explain src/auth/AuthService.ts [--json]
agentramen history src/auth/AuthService.ts [--json]
agentramen search "auth login" [--limit 20] [--json]
agentramen architecture [--at <commit>] [--json]
agentramen hotspots [--limit 20] [--json]
agentramen changes [--limit 20] [--json]
agentramen diff <commit1> <commit2> [--json]
agentramen pr [--base origin/main] [--json]
agentramen export [--at <commit>] [--json]
agentramen benchmark --files 10 1000
agentramen serve [--host 127.0.0.1] [--port 8765]
agentramen mcp
```

Example context response:

```json
{
  "task": "Add authentication",
  "files": [
    {
      "path": "src/auth_service.py",
      "language": "python",
      "symbols": ["AuthService"],
      "imports": [],
      "recent_change": "add authentication",
      "estimated_tokens": 18
    }
  ],
  "token_budget": 2000,
  "files_avoided": 12,
  "confidence": "medium"
}
```

Context includes source excerpts only when the file still matches its indexed hash and does not contain a detected credential pattern. Token counts use the configured model tokenizer when available; otherwise they are approximate character-based estimates, not tokenizer measurements or performance claims.

## GitHub Actions

The workflow created by `agentramen init` calls the reusable workflow in this repository:

```yaml
name: agentRamen
on:
  push:
    branches: ["**"]
  pull_request:
  workflow_dispatch:
  schedule:
    - cron: "17 4 * * 1"
jobs:
  agentramen:
    uses: palrajjp/agentRamen/.github/workflows/index.yml@main
```

The reusable workflow fetches Git history, restores a cache, tests the installed package, indexes the checked-out revision, summarizes pull requests, and publishes the local SQLite artifact. Use a full-depth checkout when running the CLI outside this reusable workflow to retain history.

### Use from `gha-cd` or another workflow

Call the reusable workflow before a deployment or agent job. Supplying `task` also creates a bounded JSON context artifact; the workflow does not send repository content to an AI provider.

```yaml
jobs:
  agentramen:
    uses: palrajjp/agentRamen/.github/workflows/index.yml@main
    with:
      task: "Trace the deployment workflow and identify rollback dependencies"
      token_budget: 1200
```

The artifact is named `agentramen-context-${{ github.sha }}`. A downstream job can fetch it and pass `.agentramen-context/agentramen-context.json` to its agent step:

```yaml
- uses: actions/download-artifact@v4
  with:
    name: agentramen-context-${{ github.sha }}
    path: .agentramen-context
```

The context budget defaults to 2000 if omitted. Treat the artifact like source code: it can contain excerpts and follows the repository's GitHub Actions access and retention policy.

## Agent integrations

agentRamen's MCP server runs locally over stdio. Install agentRamen once on each developer machine, then add a portable `.mcp.json` at the repository root so VS Code Copilot and Claude Code can use the same configuration:

```bash
python -m pip install git+https://github.com/palrajjp/agentRamen.git
```

```json
{
  "mcpServers": {
    "agentramen": {