Skip to content
Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace
BranchesTags

Repository files navigation

Fixel — label an issue, get a reviewable pull request.

Label an issue. Get a reviewable pull request.

Fixel is an open-source GitHub Action and CLI that turns a labeled issue into a focused code change for you to review.

License: MIT CI Node.js ≥20 Claude provider Codex provider GitHub Action PRs Welcome

English · فارسی

Verified Fixel dogfood run: issue #10 became PR #11, failed an adversarial credential probe, was hardened, passed CI, and shipped as v1.1.0.

Verified dogfood / اجرای واقعی: issue #10 → Fixel + Codex PR #11 → security review → v1.1.0. The first working implementation was not merged until its credential boundary passed an adversarial probe.

🇬🇧 English

Fixel is a human-gated GitHub issue-fixing agent. Point it at a repository and it uses either Claude or a locally authenticated Codex CLI to propose a focused pull request for each selected issue. If you cannot push to the repository, Fixel can work through your fork. It never auto-merges: review the diff and CI before merging.

🧠 Never Fail Twice

Turn a reviewed PR into a repository lesson:

fixel learn --repo myuser/myapp --pr 42

Fixel captures the PR description, review comments, inline feedback, conversation comments, and failed checks in .fixel/lessons/pr-42.md. The file starts as status: draft, so it has no effect. A maintainer must replace the placeholders with one specific rule and a regression command, review the captured evidence, and change it to status: approved. Future runs automatically load approved lessons; drafts and malformed or oversized files are ignored.

Review → lesson draft → maintainer approval → future fix → regression command. See the full workflow and threat model.

flowchart LR
    A["🏷️ Open issue"] --> B["🔍 Fixel reads it<br/>(+ comments)"]
    B --> C["🌿 Fresh branch<br/>fixel/issue-N"]
    C --> D["🤖 Claude or Codex<br/>fixes the code"]
    D --> E["✅ Commit & push"]
    E --> F["🚀 PR opened<br/>Fixes #N"]
    F --> G["🎉 Merge →<br/>issue auto-closes"]
Loading

⚡ Use as a GitHub Action

The zero-setup way. Copy examples/label-trigger.yml to .github/workflows/fixel.yml in your repo, add your ANTHROPIC_API_KEY secret, and then — just add the fixel label to any issue. A pull request shows up by itself:

name: Fixel
on:
  issues:
    types: [labeled]

jobs:
  fix:
    if: github.event.label.name == 'fixel'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: read
    steps:
      - uses: AmIrRX0/Fixel@v1.2.0
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.issue.number }}

Prefer a night shift? examples/nightly.yml makes Fixel fix up to 3 bug-labeled issues every night while you sleep. 😴

💻 Use as a CLI

Already signed in to Codex with ChatGPT? This local path does not need ANTHROPIC_API_KEY:

codex login
codex login status
export GITHUB_TOKEN="your-minimum-permission-github-token"

# Run the released CLI directly from GitHub — no clone or npm install
npx --yes github:AmIrRX0/Fixel#v1.2.0 --repo myuser/myapp --provider codex --issue 42 --verbose

Or clone it when you want the source locally:

export GITHUB_TOKEN="your-minimum-permission-github-token"

git clone https://github.com/AmIrRX0/Fixel.git
cd Fixel
npm install
node src/cli.js --repo myuser/myapp --provider codex --issue 42 --verbose

Fixel invokes codex exec non-interactively with ephemeral state and a granular permission profile: project roots are writable, common credential paths are denied, and shell network access is limited to required GitHub/package hosts. ChatGPT sign-in is for local CLI runs; the GitHub Action still uses Claude and an ANTHROPIC_API_KEY because your local Codex session must not be copied to a hosted runner.

Claude remains the backward-compatible default:

git clone https://github.com/AmIrRX0/Fixel.git
cd Fixel
npm install

cp .env.example .env   # put your tokens in it

# Your own repo: fix the first 3 open issues and open PRs
node --env-file=.env src/cli.js --repo myuser/myapp

# Someone else's repo: fork it, fix only issue #42, stream progress
node --env-file=.env src/cli.js --repo bigorg/oss-project --fork --issue 42 --verbose

# Try it safely first: fix locally and show the diff, no push, no PR
node --env-file=.env src/cli.js --repo myuser/myapp --dry-run

✨ What it does

  1. Connects to GitHub with your GITHUB_TOKEN
  2. If you don't have push access to the repo (or you pass --fork), it forks the repo and syncs the fork with upstream
  3. Lists the open issues (filterable by label or issue number)
  4. For each issue: fresh branch off the latest base (fixel/issue-N) → the selected provider fixes the code inside a clone → commit → push → PR with Fixes #N (so the issue closes automatically on merge)
  5. Skips issues that already have an open PR — no duplicate work

⚙️ CLI options

Option Description
--repo <owner/name> Target repository (required)
-V, --version Show the Fixel CLI version
--fork Fork the repo and open PRs from the fork (automatic when you lack push access)
--issue <n> Only this issue (repeatable: --issue 3 --issue 7)
--max-issues <n> Max issues per run (default: 3)
--labels <a,b> Only issues carrying these labels
--base <branch> Base branch for PRs (default: the repo's default branch)
--provider <name> claude or codex (default: claude; also configurable with FIXEL_PROVIDER)
--model <id> Provider-specific model id (default: provider default)
--dry-run Fix locally and show the diff — no push, no PR
--verbose Stream the agent's progress step by step

Learning command options:

Option Description
learn Capture PR feedback as an inert lesson draft
--pr <n> Pull request to learn from (required with learn)
--output <path> Draft path (default: .fixel/lessons/pr-N.md)

📦 Requirements

  • Node.js 20+ and git
  • A GitHub token — classic with the repo scope, or fine-grained with Contents (read/write) + Issues (read) + Pull requests (read/write). In fork mode, push access is only needed on your fork. (As an Action, secrets.GITHUB_TOKEN just works.)
  • For --provider codex: the Codex CLI installed and authenticated with codex login; no Anthropic key is needed.
  • For --provider claude: the Claude Agent SDK sandbox prerequisites and an ANTHROPIC_API_KEY (or supported local Claude authentication). The Action installs missing Linux sandbox prerequisites automatically.

🔒 Security notes

  • The GitHub token never appears in remote URLs or visible process arguments (a transient credential helper is used instead).
  • The agent works inside a throwaway clone. Codex shell commands use a granular filesystem/network profile that explicitly denies common credential paths; GitHub, Anthropic, OpenAI, package, and unrelated host environment credentials are also excluded from the Codex process. The Claude provider independently denies common credential files and the Anthropic key to sandboxed commands.
  • Codex issue text is sent through stdin, never interpolated into a shell command or exposed as a process argument. Codex runs ephemerally without loading user config or exec-policy rules.
  • The agent is not allowed to commit or push by itself — Fixel performs those operations outside the agent session.
  • Issue text, comments, repository code, and tests are untrusted input. Use an isolated runner and minimum-permission token, prefer --fork or --dry-run for unfamiliar repositories, and always review generated code before merging. See the full security policy.

🗺️ Roadmap

  • CLI with fork mode, labels filter, dry-run
  • GitHub Action with label trigger + nightly schedule
  • Comment trigger (@fixel fix this) on issues
  • Auto-retry when CI fails on the opened PR
  • Cost report comment on each PR
  • Human-approved learning from review and CI evidence (fixel learn)

🧠 Architecture

action.yml      ← GitHub Action wrapper (label an issue → get a PR)
src/cli.js      ← argument parsing & input validation
src/runner.js   ← orchestration: fork/clone → pick issues → branch → agent → commit → push → PR
src/agent.js    ← Claude Agent SDK provider
src/codex-agent.js ← local Codex CLI provider
src/prompt.js   ← shared untrusted-issue prompt boundary
src/learning.js ← PR/review/check evidence → inert lesson draft
src/lessons.js  ← bounded loader for maintainer-approved repository lessons
src/github.js   ← GitHub API via Octokit (issues, forks, PRs)
src/git.js      ← git operations with safe authentication
src/config.js   ← env loading

⭐ If Fixel saved you a debugging night, star the repo — it's how other developers find it.

🇮🇷 فارسی

Fixel یک ایجنت حل ایشوهای گیت‌هاب با کنترل انسانی است. یک ریپو به آن بده؛ ایشوهای انتخاب‌شده را می‌خواند و با Claude یا Codex CLI یک Pull Request پیشنهادی می‌سازد. اگر دسترسی push نداشته باشی، از فورک استفاده می‌کند. Fixel هیچ PRی را خودکار مرج نمی‌کند؛ diff و CI را قبل از مرج بررسی کن.

🧠 یک اشتباه را دوبار تکرار نکن

با فرمان زیر بازخورد یک PR را به lesson تبدیل کن:

fixel learn --repo myuser/myapp --pr 42

فایل ساخته‌شده ابتدا status: draft دارد و هیچ اثری روی ایجنت نمی‌گذارد. maintainer باید قانون دقیق و فرمان regression را بنویسد، evidence را بررسی کند و سپس وضعیت را به approved تغییر دهد. فقط lessonهای تأییدشده در اجراهای بعدی خوانده می‌شوند. جزئیات در راهنمای Never Fail Twice آمده است.

⚡ استفاده به‌عنوان GitHub Action

راحت‌ترین راه، بدون هیچ سروری: فایل examples/label-trigger.yml را در ریپوی خودت در مسیر .github/workflows/fixel.yml کپی کن، سیکرت ANTHROPIC_API_KEY را اضافه کن و بعد — فقط روی هر ایشویی لیبل fixel بزن. پول‌ریکوئست خودش ظاهر می‌شود! برای اجرای شبانه هم examples/nightly.yml را بردار: هر شب تا ۳ ایشوی دارای لیبل bug را وقتی خوابی فیکس می‌کند 😴

💻 استفاده به‌عنوان CLI

اگر Codex با حساب ChatGPT روی سیستم لاگین است، به ANTHROPIC_API_KEY نیاز نداری:

codex login
codex login status
export GITHUB_TOKEN="github-token-with-minimum-permissions"

git clone https://github.com/AmIrRX0/Fixel.git
cd Fixel
npm install
node src/cli.js --repo myuser/myapp --provider codex --issue 42 --verbose

این روش مخصوص اجرای لوکال است. GitHub Action همچنان از Claude و ANTHROPIC_API_KEY استفاده می‌کند، چون نشست شخصی Codex نباید به runner عمومی منتقل شود.

برای provider پیش‌فرض Claude:

git clone https://github.com/AmIrRX0/Fixel.git
cd Fixel
npm install

cp .env.example .env   # توکن‌ها رو داخلش بذار

# روی ریپوی خودت: ۳ تا ایشوی باز اول رو حل کن و PR بزن
node --env-file=.env src/cli.js --repo myuser/myapp

# روی ریپوی بقیه: فورک بزن، فقط ایشوی ۴۲ رو حل کن، پیشرفت رو هم نشون بده
node --env-file=.env src/cli.js --repo bigorg/oss-project --fork --issue 42 --verbose

# اول فقط تست کن ببین چه تغییری می‌ده، بدون پوش و PR
node --env-file=.env src/cli.js --repo myuser/myapp --dry-run

✨ چی کار می‌کنه؟

  1. با GITHUB_TOKEN به گیت‌هاب وصل می‌شه
  2. اگر به ریپو دسترسی push نداشته باشی (یا --fork بدی) خودش فورک می‌زنه و فورک رو با upstream سینک می‌کنه
  3. ایشوهای باز رو لیست می‌کنه (با قابلیت فیلتر با لیبل یا شماره ایشو)
  4. برای هر ایشو: برنچ تازه از آخرین کد base (fixel/issue-N) ← فیکس توسط provider انتخاب‌شده داخل کلونِ ریپو ← کامیت ← پوش ← PR با Fixes #N (تا با مرج، ایشو خودکار بسته بشه)
  5. اگر برای ایشویی از قبل PR باز وجود داشته باشه، دوباره‌کاری نمی‌کنه

⚙️ آپشن‌های CLI

آپشن توضیح
--repo <owner/name> ریپوی هدف (اجباری)
-V, --version نمایش نسخه CLI فیکسل
--fork فورک بزن و PR رو از فورک باز کن (اگر دسترسی push نداشته باشی خودکار فعال می‌شه)
--issue <n> فقط این ایشو (قابل تکرار: --issue 3 --issue 7)
--max-issues <n> حداکثر تعداد ایشو در هر اجرا (پیش‌فرض: ۳)
--labels <a,b> فقط ایشوهایی که این لیبل‌ها رو دارن
--base <branch> برنچ مقصد PRها (پیش‌فرض: برنچ اصلی ریپو)
--provider <name> انتخاب claude یا codex (پیش‌فرض: claude)
--model <id> شناسه مدل مخصوص provider (پیش‌فرض: مدل پیش‌فرض همان provider)
--dry-run فقط فیکس لوکال و نمایش diff — بدون پوش و PR
--verbose نمایش قدم‌به‌قدم کار ایجنت

📦 پیش‌نیازها

  • Node.js نسخه ۲۰ به بالا و git
  • یک GitHub token — کلاسیک با اسکوپ repo، یا fine-grained با دسترسی Contents (خواندن/نوشتن) + Issues (خواندن) + Pull requests (خواندن/نوشتن). در حالت فورک، فقط روی فورکِ خودت دسترسی push لازمه. (در حالت Action همون secrets.GITHUB_TOKEN کافیه.)
  • برای --provider codex: نصب Codex CLI و ورود با codex login؛ کلید Anthropic لازم نیست.
  • برای --provider claude: پیش‌نیازهای sandbox مربوط به Claude Agent SDK و ANTHROPIC_API_KEY یا احراز هویت پشتیبانی‌شده Claude.

🔒 نکات امنیتی

  • توکن گیت‌هاب هیچ‌وقت داخل URL ریموت یا آرگومان‌های قابل‌مشاهده قرار نمی‌گیره (از credential helper موقتی استفاده می‌شه).
  • فرمان‌های ایجنت داخل sandbox اجرا می‌شوند؛ توکن GitHub و کلیدهای API یا package وارد محیط Codex نمی‌شوند. متن ایشو نیز از stdin فرستاده می‌شود و داخل فرمان shell قرار نمی‌گیرد.
  • ایجنت اجازه‌ی commit/push مستقیم ندارد — این کارها را Fixel بیرون از session ایجنت انجام می‌دهد.
  • متن ایشو، کامنت‌ها، کد ریپو و تست‌ها ورودی غیرقابل‌اعتماد هستند. روی runner ایزوله و با حداقل دسترسی اجرا کن، برای ریپوهای غریبه از --fork یا --dry-run استفاده کن و PR را همیشه قبل از مرج بازبینی کن. جزئیات در سیاست امنیتی آمده است.

🗺️ نقشه راه

  • ✅ CLI با حالت فورک، فیلتر لیبل و dry-run
  • ✅ GitHub Action با تریگر لیبل + زمان‌بندی شبانه
  • ⬜ تریگر با کامنت (@fixel fix this) روی ایشوها
  • ⬜ تلاش مجدد خودکار وقتی CI روی PR قرمز می‌شه
  • ⬜ کامنت گزارش هزینه روی هر PR
  • ✅ یادگیری با تأیید انسان از review و CI با fixel learn
⭐ اگه Fixel یک شب دیباگ رو برات نجات داد، به ریپو استار بده — بقیه‌ی دولوپرها این‌طوری پیداش می‌کنن.

🔧 Fixel — label an issue, get a reviewable pull request.

About

Label an issue, get a reviewable PR. Fixel uses Claude or Codex and learns from human-approved review/CI lessons. GitHub Action + CLI.

Topics

agent-memoryai-agentautomationclaudecodexcoding-agentdeveloper-toolsdevopsgithub-actionsgithub-issueshuman-in-the-loopnodejsopen-sourceopenaipull-requestself-improving-agent

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages