convez.ai
MCP Server
selimozten

elek

selimozten/elek

Ver no GitHub
BomPluginScore · de 0 a 100

AI code review GitHub Action for pull requests, model-agnostic via pi and ready for OpenRouter, DeepSeek, OpenAI, Anthropic, Google, and more. Posts inline review threads without approve, merge, or close powers.

Instalação

$npx convez-ai selimozten/elek

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
19
Forks
2
Acompanhando
0
Saúde
85%
Último commit
há 3 dias
Versão
v1.4.0
Issues abertas
2
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

elek is a GitHub App-first AI review product in development. This public repo contains the open review engine, CLI tools, feedback analytics, and self-hosted GitHub Action runtime that make the review behavior auditable.

The planned hosted GitHub App will be the primary install path for branded, zero-config pull request reviews. The self-hosted Action works today for teams that want BYOK control, local auditability, or advanced workflow integration.

It can run one reviewer, a two-lens cross-check, or a four-lens council with any provider pi supports: DeepSeek, OpenRouter, OpenAI, Anthropic, Google, Bedrock, Vertex, Groq, Mistral, Together, xAI, and more. Models can read code, search, and post review feedback. They cannot approve, merge, or close — that's a structural guarantee, not a runtime check.

PathStatusUse it for
Hosted GitHub AppPlanned primary pathBranded reviews, simple onboarding, hosted analytics, team settings
Self-hosted GitHub ActionAvailable todayBYOK reviews, auditable runs, custom workflow control
CLI toolsAvailable todayFeedback adjudication, saved-run analytics, benchmark evaluation

Why elek

eleksingle-provider review actionsgeneral-purpose CLI actions
Providers11+ (any pi target)usually one providerusually one provider
Per-review cost~$0.005 (deepseek)often premium-model pricedvaries by hosted stack
Inline review threads✓ via MCPoften supportedpartial
Iterates on prior findings✓often supportedpartial
Structural safety✓ no merge/approve/close pathsoften broader PR API accessoften broader repo access
Modulessmall TypeScript corelarger vendor stacklarger platform stack
RuntimeHosted App planned; Action/CLI availableprovider CLI/runtimeprovider CLI/runtime

Bias toward cheap, capable models. DeepSeek-v4-Pro plus Kimi K2.7 Code through OpenRouter gives you two independent review passes without defaulting to one expensive model. Run them in parallel for cross-validation; reserve premium validators for the highest-risk PRs.

Hosted App status

The public GitHub App install is planned and not yet open. Normal product onboarding should become "Install the elek GitHub App"; until that path is available, use the self-hosted Action below.

Advanced self-hosted quick start

Fast path from your repository root:

npx --package github:selimozten/elek elek-init --provider deepseek

This creates .github/workflows/elek.yml and .elek.yml for the Action runtime.

  1. Add a provider API key to repo secrets (Settings → Secrets and variables → Actions):

    DEEPSEEK_API_KEY  # or OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / etc.
    
  2. Commit the generated files, or drop this in .github/workflows/elek.yml manually:

    name: elek
    on:
      pull_request: { types: [opened, synchronize, reopened] }
      issue_comment: { types: [created] }
      issues: { types: [opened] }
    
    permissions:
      contents: read           # blocks merge entirely (read-only)
      pull-requests: write     # post review comments
      issues: write            # post tracking comment
    
    concurrency:
      group: elek-${{ github.event_name }}-${{ github.event.pull_request.number || github.event.issue.number || github.ref }}
      cancel-in-progress: true
    
    jobs:
      review:
        if: ${{ github.event_name != 'issue_comment' || !endsWith(github.actor, '[bot]') }}
        runs-on: ubuntu-latest
        timeout-minutes: 15
        steps:
          - uses: actions/checkout@v6.0.3
            with: { fetch-depth: 0 }
          - uses: selimozten/elek@v1
            with:
              deepseek_api_key: ${{ secrets.DEEPSEEK_API_KEY }}
              provider: deepseek
              model: deepseek-v4-pro
              thinking: high
    
  3. Open a PR. Within ~3 minutes you'll see a tracking comment with a live progress checklist, then the final review (top-level summary + inline threads on changed lines).

Useful initializer variants:

npx --package github:selimozten/elek elek-init --provider openrouter --model moonshotai/kimi-k2.7-code
npx --package github:selimozten/elek elek-init --strategy crosscheck --max-cost-usd 0.05
npx --package github:selimozten/elek elek-init --no-config

The final comment includes an estimated token/cost line by default:

Estimated review cost: $0.0012 (3,420 in / 810 out tokens)

For models without built-in price hints, elek still reports token estimates and returns $0.0000 until you provide cost_rates.

To trigger from a comment, set trigger_phrase (default @pi) and write @pi review the auth flow.

Modes

The mode input controls the model's tool surface:

modeToolsMCPEditsUse case
review (default)read,grep,find,ls,mcp✓✗Code review only. Recommended.
review+edit+ write,edit✓✓Review + push fixes to an elek/* branch.
agent+ bash✗✓Legacy, full power. Trusted workflows only.

Use mode to choose the tool surface. The low-level tools input is kept for compatibility and debugging; review modes still resolve to the safe mode presets.

The model can never approve, merge, or close in any mode — those endpoints aren't plumbed in elek's MCP server. The permissions: block in your workflow is the backstop.

Review Strategies

The review_strategy input controls orchestration quality:

review_strategyRunsUse case
solo (resolved when unset)1 final reviewerFast, cheap default review.
crosscheck2 read-only lenses + 1 final validatorBest default for serious PR review.
council4 read-only lenses + 1 final validatorLarger or high-risk PRs touching auth, billing, migrations, infra, or public APIs.

crosscheck and council currently run only with mode: review. If you use review+edit or agent, elek runs a solo review and logs a warning.

crosscheck runs two independent candidate reviewers:

  • Risk Review — correctness, security, breaking changes, devex regressions, feature-gate leaks.
  • Design Review — maintainability, structural simplification, abstraction quality, file-size growth, spaghetti branching, type boundaries.

council adds:

  • Test Integrity Review — missing/weak tests, nondeterminism, meaningless assertions.
  • Operational Review — rollout/rollback safety, migrations, configuration, observability, retries, partial updates.

Candidate reviewers are read-only and cannot post. The final validator receives their reports, rejects speculative or duplicate findings, and posts only high-confidence feedback through elek's narrow review MCP tools.

Every finding is expected to follow elek's review contract: severity, confidence, evidence, impact, and a concrete fix. Low-confidence findings should be dropped instead of posted.

with:
  provider: deepseek
  model: deepseek-v4-pro
  review_strategy: crosscheck
  review_models: deepseek/deepseek-v4-pro,openrouter/moonshotai/kimi-k2.7-code
  validator_model: deepseek/deepseek-v4-pro
  max_cost_usd: "0.05"
  max_council_changed_lines: 1200
  max_crosscheck_changed_lines: 3000

For expensive models, a good pattern is cheap parallel reviewers plus one stronger validator. If the selected multi-lens strategy already exceeds max_cost_usd before output tokens are counted, elek downgrades to the next cheaper strategy. If a PR exceeds a changed-line guard, elek also downgrades before starting model calls.

Cross-Model Review

Run two providers in parallel for free cross-validation. Each model independently iterates on the other's findings:

jobs:
  deepseek:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6.0.3
      - uses: selimozten/elek@v1
        with:
          deepseek_api_key: ${{ secrets.DEEPSEEK_API_KEY }}
          provider: deepseek
          model: deepseek-v4-pro

  kimi:
    name: openrouter-kimi-k2.7-code
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6.0.3
      - uses: selimozten/elek@v1
        with:
          openrouter_api_key: ${{ secrets.OPENROUTER_API_KEY }}
          provider: openrouter
          model: moonshotai/kimi-k2.7-code

On the second push, each model reads the other's prior findings (kept in the comment thread) and opens its review with a status table — fixed / still present / no longer relevant — before listing new findings.

How it works

flowchart LR
    A[GitHub event] --> B[run.ts]
    B --> C[fetch diff,<br/>comments,<br/>prior reviews]
    C --> D[XML-tagged<br/>prompt]
    D --> E["pi --mode json"]
    E -->|tool calls| F[MCP server]
    F -->|inline comments| G[/buffer.jsonl/]
    E -->|streaming events| B
    B -->|live updates| H[(tracking<br/>comment)]
    G --> I[post-step]
    I --> J[(inline review<br/>threads)]

A composite Action installs Node + pi + the MCP adapter, then tsx runs the orchestrator. Pi spawns the model, streams events back as JSONL, and elek converts those into a live checklist. The model calls our MCP server to buffer inline comments; a post-step drains the buffer to GitHub's PR review-comments API after pi exits.

Full architecture: docs/ARCHITECTURE.md.

Public roadmap

  • GitHub App primary install — make the hosted elek App the default way to add review-only AI to a repository, with the Action remaining the advanced self-hosted runtime.
  • Opt-in telemetry contract — publish redacted telemetry schemas and client redaction tests so teams can choose aggregate or finding-metadata reporting without sending raw code, raw diffs, prompts, file paths, branch names, commit SHAs, secrets, or author identities.
  • Model-quality analytics — build on elek-feedback, elek-analytics, and elek-eval so teams can compare models by accepted findings, false positives, cost, latency, and inline-comment health.

Inputs

Trigger / behavior

InputDefaultNotes
trigger_phrase@piDetected in comments, issue body, PR body
prompt(comment text)Explicit prompt; bypasses trigger detection
modereviewreview / review+edit / agent
config_path.elek.ymlRepo-local defaults and review policy; use none, off, or false to disable
review_strategy(resolved)solo / crosscheck / council
review_models(primary model)Comma-separated reviewer model specs, e.g. deepseek/deepseek-v4-pro,openrouter/moonshotai/kimi-k2.7-code
validator_model(primary model)Final synthesis model spec
severity_threshold(.elek.yml or unset)Prompt-level reviewer threshold: critical, important, or minor
show_costtrueShow estimated token usage and review cost in comments/logs; outputs are always set
cost_rates(empty)Optional price overrides as model=inputPerMillion:outputPerMillion
max_cost_usd(.elek.yml or unset)Soft cost cap; multi-lens strategies downgrade when known input-side estimates already exceed it
max_council_changed_lines(.elek.yml or default)Changed-line cap before council downgrades; 0 disables
max_crosscheck_changed_lines(.elek.yml or default)Changed-line cap before crosscheck downgrades; 0 disables
actor_filter(empty)Comma-separated allowlist of usernames
allowed_bots(empty)Comma-separated bot logins, or * for all
sticky_commenttrueReuse the same tracking comment across pushes

Model

InputDefaultExamples
provideranthropicdeepseek, openrouter, openai, anthropic, google, groq, mistral, together, xai
model(provider default)deepseek-v4-pro, moonshotai/kimi-k2.7-code, claude-sonnet-4-6, claude-opus-4-8, gpt-5.5, gemini-3.1-pro-preview
thinkingmediumPortable pi levels: off / minimal / low / medium / high / xhigh; provider adapters map these to native efforts, e.g. Claude's maximum max
system_prompt(pi default)Override pi's system prompt
max_turns20Cap conversation turns
run_timeout_seconds600Wall-clock timeout for each model run; keep the job timeout higher so elek can update the tracking comment
tools(mode-resolved)Legacy low-level allowlist; review modes use mode presets
base_branch(repo default)Override the comparison base
branch_prefixelek/Prefix for branches the action creates

Outputs

OutputNotes
conclusionsuccess, failure, or skipped
summaryFirst 1,000 chars of the final review text
cost_usdAggregate estimated USD cost across all model runs
input_tokens / output_tokensAggregate estimated token usage
review_summary_pathPath to elek-review-summary.json on the runner
review_summary_jsonSame summary as a single-line JSON output

The review summary JSON includes run duration, requested/executed strategy, model labels, parsed findings, per-model token/cost estimates, pricing source, and inline comment counts. Use review_summary_path with your own artifact upload step when you want to compare models or review strategies across CI runs. If the runner cannot write the optional file, review_summary_path is set to an empty string while review_summary_json is still emitted.

Adjudicate each finding after the implementation agent has handled the PR:

npx --package github:selimozten/elek elek-feedback --template artifacts/pr-42/elek-review-summary.json > feedback.json
# Fill verdict/points per finding: accepted, partial, rejected, or unreviewed.
npx --package github:selimozten/elek elek-feedback --apply feedback.json artifacts/pr-42/elek-review-summary.json > artifacts/pr-42/adjudicated-summary.json

Feedback is stored on each finding with a 0-5 integer score, evaluator, timestamp, and note. This lets humans or implementation agents mark whether a model's finding was accepted, partially useful, or rejected before analytics aggregates model quality. Applying feedback is a replacement step: findings omitted from the feedback file are reset to unreviewed.

Aggregate saved summaries to compare strategies, models, repositories, cost, latency, findings, and inline comment outcomes:

npx --package github:selimozten/elek elek-analytics --group-by model artifacts/*/adjudicated-summary.json

Compare two saved artifact sets to spot regressions in success rate, finding volume, inline comment health, latency, and cost:

npx --package github:selimozten/elek elek-analytics --group-by model \
  --baseline artifacts/before/*/adjudicated-summary.json \
  --current artifacts/after/*/adjudicated-summary.json

Add --json to feed dashboards, release reports, scheduled quality checks, or community model-quality leaderboards.

Model evaluation

Use elek-eval to score saved elek-review-summary.json files against your own seeded PR benchmark suite:

npx --package github:selimozten/elek elek-eval --suite review-benchmark.yml artifacts/*/elek-review-summary.json

Bootstrap an editable suite case from a known-good summary:

npx --package github:selimozten/elek elek-benchmark --id auth-regression artifacts/auth/elek-review-summary.json > review-benchmark.yml

Example suite:

version: 1
cases:
  - id: auth-regression
    repository: owner/repo
    number: 42
    expected_findings:
      - id: tenant-bypass
        min_severity: critical
        keywords: [tenant, session, bypass]
    max_false_positives: 0

elek-eval reports recall, precision, false positives, duration, and cost per summary, then exits non-zero if a run misses expected findings or exceeds the false-positive budget. Add --json for machine-readable output. Generated benchmark cases are meant to be reviewed and edited before they become policy.

Repo Config

Add .elek.yml to keep review defaults and repo-specific policy next to the code. Workflow inputs still win when they are set explicitly.

review_strategy: crosscheck
review_models: deepseek/deepseek-v4-pro,openrouter/moonshotai/kimi-k2.7-code
validator_model: deepseek/deepseek-v4-pro
cost_rates: openrouter/moonshotai/kimi-k2.7-code=0.95:4.00,deepseek/deepseek-v4-pro=0.25:1.00
max_cost_usd: 0.05
max_council_changed_lines: 1200
max_crosscheck_changed_lines: 3000
severity_threshold: important

knowledge_paths:
  - AGENTS.md
  - CONTRIBUTING.md
  - docs/ARCHITECTURE.md

ignore_paths:
  - docs/**
  - "*.md"

instructions:
  - Treat auth and permission changes as security-sensitive.
  - Require tests for parser and config changes.

Supported keys: review_strategy, review_models, validator_model, cost_rates, max_cost_usd, max_council_changed_lines, max_crosscheck_changed_lines, severity_threshold, knowledge_paths, ignore_paths, and instructions. cost_rates uses the same model=inputPerMillion:outputPerMillion format as the workflow input. severity_threshold accepts critical, important, or minor. Severity and ignore-path policy are prompt instructions for the reviewer, not a server-side filter. If an existing config file has malformed YAML, elek fails the run instead of silently dropping repo policy.

On pull requests, policy fields (review_strategy, review_models, validator_model, cost_rates, max_cost_usd, changed-line guards, and severity_threshold) are loaded from the base branch when available. Guidance fields (knowledge_paths, ignore_paths, and instructions) come from the checked-out branch so contributors can propose review guidance changes without controlling cost or severity policy. knowledge_paths points elek at repo-local docs that should shape review judgment, such as agent instructions, contribution guidelines, architecture notes, or ADR folders. When unset, elek automatically tries AGENTS.md, CONTRIBUTING.md, docs/ARCHITECTURE.md, and docs/adr. Loaded files are bounded by count and byte size before they enter the prompt. Each run logs the loaded config source plus effective strategy/model/severity choices. If elek cannot resolve a PR comment trigger's actual base branch, it skips base-branch policy loading for that run instead of guessing from the default branch; policy fields from the checked-out workspace are not used as a fallback. For issue_comment triggers, "checked-out branch" is whatever the workflow checked out, usually the default branch unless the workflow explicitly checks out the PR head.

API keys

Each provider has its own input; only set the one you use. Pi reads the matching *_API_KEY env var.

InputEnv var
anthropic_api_keyANTHROPIC_API_KEY
openai_api_keyOPENAI_API_KEY
google_api_keyGOOGLE_API_KEY
deepseek_api_keyDEEPSEEK_API_KEY
groq_api_keyGROQ_API_KEY
mistral_api_keyMISTRAL_API_KEY
together_api_keyTOGETHER_API_KEY
xai_api_keyXAI_API_KEY
openrouter_api_keyOPENROUTER_API_KEY

For AWS Bedrock: AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY as job-level env. For Vertex: GOOGLE_APPLICATION_CREDENTIALS, ANTHROPIC_VERTEX_PROJECT_ID.

Outputs

OutputDescription
conclusionsuccess / failure / skipped
branch_nameThe elek/* branch created (if any)
comment_idThe tracking comment ID
session_idPi session ID for resumption
summaryFirst 1000 chars of the review
cost_usdEstimated review cost in USD
input_tokensEstimated input tokens across all review runs
output_tokensEstimated output tokens across all review runs

Permissions

permissions:
  contents: read           # blocks merge — model literally can't push to base
  pull-requests: write     # post review comments
  issues: write            # post tracking comment

For mode: review+edit (model pushes fixes to an elek/* branch), upgrade contents: write. The model still can't approve/merge — those scopes are separate, and the MCP server has no code path to pulls.merge regardless. GITHUB_TOKEN reviews don't satisfy required-approver counts on protected branches either.

Supported events

  • pull_request — opened, synchronize, reopened
  • issues — opened
  • issue_comment — created (on PRs or issues)
  • pull_request_review — submitted
  • pull_request_review_comment — created

Cost visibility

elek shows estimated review cost in the final comment and exposes the same data as action outputs. This is intentionally transparent rather than billing-grade: when pi exposes exact usage, elek can use it; today it estimates tokens from prompt/output text and applies model price hints.

Set show_cost: false to hide the visible comment/log line. The cost_usd, input_tokens, and output_tokens action outputs are still populated for downstream workflow steps.

Built-in price hints cover the recommended low-cost defaults:

ModelPrice sourceNotes
deepseek/deepseek-v4-probuilt inStrong low-cost reviewer
openrouter/moonshotai/kimi-k2.7-codebuilt inIndependent reviewer through OpenRouter

For premium or newer models, pass your provider's current prices in USD per 1M tokens:

with:
  show_cost: true
  cost_rates: openai/gpt-5.5=1.25:10,anthropic/claude-sonnet-4-6=3:15
  max_cost_usd: "0.10"
  max_council_changed_lines: 1200
  max_crosscheck_changed_lines: 3000

max_cost_usd is a soft guard for strategy selection. elek estimates the known prompt/input-side cost before running multi-lens reviews; if that minimum estimate already exceeds the cap, it downgrades council to crosscheck, then crosscheck to solo. Provide cost_rates for custom models so the guard can enforce the cap.

Changed-line guards run before cost estimates. By default, council downgrades above 1,200 changed diff lines and crosscheck downgrades above 3,000. Override with max_council_changed_lines and max_crosscheck_changed_lines, or set either value to 0 to disable that guard.

Running two cheap models in crosscheck mode often costs less than one premium validator while surfacing disagreements that a single pass misses.

Security

  • The MCP server exposes exactly two tools: create_inline_comment and update_tracking_comment. There is no code path to pulls.createReview({event: "APPROVE"}), pulls.merge, or issues.update({state: "closed"}).
  • update_tracking_comment is pinned to the env-passed comment_id; arg-level overrides are structurally inaccessible.
  • Token sanitization redacts ghp_, ghs_, gho_, ghu_, ghr_, and github_pat_ prefixes from any model output before it reaches GitHub.
  • .mcp.json (which carries GITHUB_TOKEN) is written to ~/.config/mcp/, never the workspace, and unlinked when pi exits.

Threat model: a fully jailbroken model still cannot perform destructive operations because the plumbing doesn't exist. The permissions: scope is the backstop.

Documentation

Credits

Built on pi coding agent. MCP integration via pi-mcp-adapter.

License

MIT

Ver o original no GitHub

Bom para

Relacionados