convez.ai
AgenteAutomaçãoAvançado
huksley

Gene AI

huksley/gene

Do ticket ao PR mergeável, completamente automatizado com Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent autônomo que transforma tickets do Linear ou Trello em pull requests mergeáveis usando Claude Code. Gene monitora seu rastreador de issues, despacha um agente de IA em uma worktree dedicada para executar o trabalho, e gerencia todo o ciclo de review e CI até que a mudança esteja pronta para merge — você mantém controle total sobre o merge final.

Instalação

$npx convez-ai huksley/gene

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
3
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
v1.5.2
Issues abertas
0
Contribuidores
3

Casos de uso

  • Automatizar desenvolvimento de features a partir de tickets estruturados
  • Reduzir tempo de codificação repetitiva em repositórios gerenciados
  • Gerenciar ciclo completo de CI/review com resposta automática a comentários

Veredito

Gene AI é um harness produção-ready para transformar issue tracking em código entregável. Arquitetura sólida (TypeScript, suporte multi-forge), mas requer setup cuidadoso de credenciais e está ainda em desenvolvimento ativo — ideal para equipes que querem automação séria de desenvolvimento, não para experimentadores.

README

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

🧬 Gene AI

Gene AI is an autonomous AI harness powered by Claude Code — from a ticket to a mergeable pull request, completely automated.

Gene AI is a console app you run on your machine. It watches your issue tracker — Linear or Trello — for tickets labelled Gene and assigned to you, and for each one dispatches a Claude Code agent in a dedicated git worktree to do the work and open a pull/merge request. It then watches that change request through review and CI — replying to comments, fixing CI failures — until it's ready to merge. Gene opens change requests but never merges them itself, so you stay in control where it matters.

It's the personal, unattended harness around claude, not a replacement for it: watching the tracker, the ticket lifecycle, per-issue multi-repo/forge routing, and the review/CI re-dispatch loop are what Gene adds. If you already drive Claude Code by hand, Gene is what runs it for you — from a ticket — while you do something more meaningful.

Status: open source (Apache-2.0) and under active development. The prebuilt binary is macOS arm64; on other platforms, build manually from the source code.

Workflow

    Linear               Worktree              GitHub
    Trello               (sandbox)             GitLab
   ┌──────────┐        ┌─────────────┐       ┌───────────┐       ┌──────────┐
   │ Todo     │ ─────► │ In Progress │ ────► │ In Review │ ────► │ Done     │
   │ (plan)   │ ─────► │   (code)    │ ────► │  (push)   │ ────► │ (merge)  │
   └──────────┘        └─────────────┘       └───────────┘       └──────────┘
    pick up              │   ▲                │   ▲  │   merged
    + comment            │   │                │   └──┘
                    plan │   │ reply          │        re-dispatch loop:
                         ▼   │                │        CI failed, comment, or review
                      ┌──────┴──────┐         │
                      │   Blocked   │ ◄───────┘
                      └─────────────┘   needs a human decision

Gene AI watches your issue tracker — Linear or Trello — for Todo issues (or Trello cards) labelled Gene, and for each one dispatches a claude agent — running with a dedicated git worktree — to do the work and open a change request. Each issue chooses its own target repo (and the assigned forge) from a link in the issue, so one tracker can drive GitLab and GitHub repos side by side.

Writing tickets

Gene only acts on an issue when all of these hold — so an issue needs:

  • the Gene label — the ownership tag the daemon filters on (never removed by Gene);
  • an assignee of you — the tracker user Gene is authenticated as (LINEAR_ASSIGNEE / TRELLO_ASSIGNEE, default me; set any to drop the filter, or a specific user to work on their behalf);
  • a target repo — a GitLab/GitHub link in the description (the first link wins; comments are a fallback), or mapped via GENE_REPO_MAP / GENE_REPO_URL (see Repo targeting); it also falls back to the local repo URL when Gene's working directory is itself a git repo.
  • state Todo — the trigger for new agent task. The other states are reactions to comments / CI, see the lifecycle table.

Write the description for an engineer who would pick it up without any prior knowledge — the agent sees only the issue, its comments, and the repo. Say what and why, not how, and attach screenshots / logs to the issue (image attachments and markdown files are added as temporary files into the worktree the agent works in).

Recommended: set GENE_REQUIRE_SECTIONS to require specific headings in the issue description so Gene will know what to do. If set, and missing, Gene will reply asking for them and moves the issue to Blocked until you fill them in. The recommended sections are:

  • ## Problem — the bug or desired change, with enough context to reproduce or locate it.
  • ## Acceptance criteria — what "done" looks like, concretely, for example "unit tests/e2e tests etc added/updated for this issue".

How it works

Gene checks the issue tracker, decides, posts a start comment, moves the issue to In Progress, clones the repo into a worktree, and downloads any attachments. The spawned Claude Code agent does everything else — code changes, the merge/pull request, and the tracker write-back (comments + the terminal state move).

Quick start

Install all required CLIs: Claude Code, linear, notion, GitLab, GitHub and more if you need.

Add Gene config file to your repo, optionally exclude it in .gitignore or locally (echo ".gene*" >> .git/info/exclude).

Add following .gene.config

LINEAR_WORKSPACE=<your-workspace-name>
GENE_LABEL=Gene
LINEAR_TRIGGER_STATE=Todo
LINEAR_ACTIVE_STATE=In Progress
LINEAR_BLOCKED_STATE=Blocked
LINEAR_REVIEW_STATE=In Review
LINEAR_DONE_STATE=Done
GENE_AGENT_MARKER="#gene-ai"
GENE_REQUIRE_SECTIONS=## Problem,## Acceptance criteria
# github or gitlab
GENE_FORGE=github
# Your code repo
GENE_REPO_URL=https://github.com/example/example
# If you have repos per team in Linear, TICKET-1 will checkout this repo
# Can be overriden in the ticket as well
# GENE_REPO_MAP='{ "TICKET": "https://github.com/example/example" }'
GENE_POLL_INTERVAL_MS=30000
GENE_DEBOUNCE_MS=20000
GENE_MAX_CONCURRENT=4
GENE_DRY_RUN=false
GENE_CLAUDE_BIN=claude
GENE_AGENT_MAX_PROCESSING_TIME=3600
LINEAR_IGNORE_COMMENTS=!review,/review
GITLAB_IGNORE_COMMENTS=!review,Walkthrough
GITHUB_IGNORE_COMMENTS=/review,/linear
DRAFT_CHANGE_REQUEST=true
# Additional tools to whitelist
GENE_ALLOWED_TOOLS="Bash(ntn *),Bash(python3 *),Bash(glab *),Bash(git push *)"

Download gene and run from your folder. Press R in the main menu will quickly reload and fetch the tickets marked with Gene label.

Quick tip on getting issues ready for Gene: State: Todo, Assigned: to you, Label: Gene, with 2 sections: ## Problem and ## Acceptance criteria properly described.

Lifecycle (issue states)

The lifecycle is driven by the issue status in Linear, or the list the card is on in Trello. Each scan, for every eligible issue, Gene decides what to do next:

Tracker stateWhat the daemon seesWhat Gene does
Todoa change request is already attachedcontinues that change request on its own branch — skips planning
Todono change request yetstarts from scratch: plan → code → open the MR/PR → In Review
In Progressa new human commenthands it to the work in flight as feedback
Blockeda new human replyresumes — Gene had asked a question or proposed a plan that a human needs to confirm
In Reviewa new review comment on the change requestre-dispatches Claude Code to address it — acts even while CI is still running
In Reviewthe CI/CD for a change request failedre-dispatches Claude Code to address the failure
In Reviewnothing new (quiet; CI green or still running)no-op — waits for the next signal
In Reviewthe change request has been mergedmoves issue to → Done (when LINEAR_DONE_STATE is set)

Eligibility (label Gene, assigned to you, a target repo) and what to put in the description are covered in Writing tickets.

The Gene label is an ownership tag and is never removed by the pipeline. Each scan watches Gene issues in {Todo, In Progress, Blocked, In Review} and handles ongoing work — active conversations (In Progress / Blocked) and open change requests (In Review) — before picking up new Todo work.

Assignee filter Gene only works issues assigned to you — the tracker user it is authenticated as. Issues with the Gene label assigned to someone else (or unassigned) are skipped and logged. Set the assignee filter (LINEAR_ASSIGNEE / TRELLO_ASSIGNEE) to any to drop it, or to a specific user — Linear by email, Trello by username — to work on their behalf (default: me).

Agent vs human comments Gene posts as your own tracker user (both backends do), so author identity can't tell them apart. Every comment Gene writes carries a marker (GENE_AGENT_MARKER, default #gene-ai); decide.ts treats marker-bearing comments as Gene's, and a human comment newer than Gene's last one is the trigger to resume / handle feedback.

Ignored comments Some comments shouldn't count as a trigger — slash/bang commands meant for another bot (/review), or a tracker's own status chatter. Patterns to ignore are set per source — LINEAR_/TRELLO_IGNORE_COMMENTS for issue comments, GITLAB_/GITHUB_IGNORE_COMMENTS for review comments on the MR/PR — as a comma-separated list where each item is a case-insensitive substring or a /regexp/flags (full test; commas inside the slashes are kept). Built-ins are always on — !review and /review everywhere, plus Review on Linear — and your patterns add to them. A matching issue comment isn't treated as new human feedback; a matching review comment neither re-dispatches the agent nor reaches its prompt. (Substrings are broad — Review also matches "please review" — so anchor a /…/ to narrow if needed.)

In-Review handling Once a change request is open, the daemon polls the forge for two signals before it touches new Todo work: a failing pipeline / Actions run, and new review comments on the MR/PR (the same marker tells Gene's own replies from a human's). On either, it re-dispatches the agent to push a fix and reply. A new human comment is acted on immediately — even while CI is still running, so a reviewer never has to wait for a pipeline to finish to be heard. Running CI only defers the cases where it logically must: a still-running pipeline can't be a failure yet, and a draft pickup with nothing new won't pile a fresh run onto mid-flight CI. With no new signal at all, the scan is a no-op and the daemon moves on. A per-issue cursor (the handled head SHA + newest comment, stored in the state store via db.ts) ensures each signal triggers exactly one dispatch, not one per poll.

Auto-progress to Done on merge Set <TP>_DONE_STATE (e.g. TRELLO_DONE_STATE=Done / LINEAR_DONE_STATE=Done) and the daemon moves an In-Review issue to that state — with a comment — as soon as its change request merges, instead of waiting for a human to drag it across. Left unset, merge→Done stays a manual step (the default).

Stalled Claude Code calls moved to Blocked claude -p exits 0 even if its connection to the model API drops mid-stream or it dies before emitting a final result. The daemon detects both (a transient-transport signature in the stream, or a missing success result), retries within the agent's retry budget, and — if it still didn't finish — posts a "I stopped before finishing — reply to resume" comment and moves the issue to Blocked rather than letting it stall silently In Progress. The worktree is preserved, so a reply resumes from where it left off.

Interrupted runs recover on restart If the daemon itself is killed while an agent is mid-run — a hard quit, a crash, a reboot — that run never records an outcome; its activity log just ends at agent-start. On the next startup the daemon reconciles these: it writes a closing agent-interrupted event for each (so the run stops haunting the dashboard as a stale in-flight row, shown there as the interrupted status), and — because the issue is still In Progress — the very next scan re-picks it up and continues from the preserved worktree. The per-issue file lock is self-healing (it records the owning PID, and a lock held by a now-dead process is reclaimed on the next dispatch), so a hard kill never wedges an issue.

Low-latency reactivity (optional Trello webhook) By default the daemon reacts within GENE_POLL_INTERVAL_MS. On Trello you can drop that to seconds: set GENE_WEBHOOK_URL (a public tunnel pointing at the local listener on GENE_WEBHOOK_PORT, default 8473) plus TRELLO_API_SECRET, register the board webhook with npm run webhook, and board activity wakes the poll loop immediately. It's a per-tracker capability (Tracker.startWatch); without it the daemon just polls — correctness never depends on the webhook.

Draft pickup If a Todo issue already has an open change request — a human opened a draft MR/PR and handed it to Gene, or a previous run opened one — Gene continues it instead of starting from scratch. It finds the change request from the issue's tracker attachments (then description, then comments), matched to the resolved repo and looked up by number — so it works even when the MR/PR lives on a human-named branch, not an auto-linked one. The agent checks out that branch, reads the diff, the CI result and any review comments, addresses the pipeline failures / feedback below, finishes whatever the change request is still missing, and — once the work is complete and CI is green — marks the draft ready for review and moves the issue to In Review (or back to Blocked if it needs a decision). With GENE_DRAFT_CHANGE_REQUEST set, it leaves the draft as-is for a human to mark ready instead. This is the same machinery as In-Review handling, just with "there's queued work here" rather than "wait for a new signal".

Activity log Alongside the review cursor, the daemon records a per-issue activity log in the state store, keyed by (tracker, issue id): each dispatch, the agent's start / finish (with its own final summary), review re-dispatches, draft pickups, and resets (dry-run entries are flagged). Inspect one issue's history with npm run log -- <system>:<id> (e.g. linear:CLOUD-1094; a bare id defaults the system to GENE_TRACKER). With the opt-in Postgres backend the store is multi-connection, so a one-shot command (log / reset) reads it fine while the daemon runs — both point at the same server. The default embedded store is single-process: stop the daemon before running log / reset, or point both at a shared Postgres (GENE_DATABASE_URL). See State store.

Programs

A program is a recurring job that lives on a ticket: a daily security review, an hourly log check, "rebase my open MRs". Gene runs it on demand or from its trigger, the agent does what the ticket's workflow says and reports back on the ticket, and the program goes back to rest until the next run. Unlike a coding ticket, a program never opens a change request and is never moved to Done.

Writing a program

A program is a ticket with the program label (LINEAR_PROGRAM_LABEL / TRELLO_PROGRAM_LABEL, default Program), assigned to you, with these sections:

## Trigger
Every weekday at 08:00 UTC.

## Workflow
Review the commits merged to `main` since the SHA in the run notes. File a sub-issue
for each finding. Record the newest reviewed SHA in the run notes.

## Acceptance criteria
A run report comment listing what was reviewed, and one sub-issue per finding.
  • ## Trigger says when it runs (see Triggers), or manual.
  • ## Workflow is what the agent does on each run.
  • ## Acceptance criteria is what a good run looks like.
  • ## Branch (optional) pins the branch a repo-linked program runs on (see Branch).
  • ## Run notes (or ## Current state) is written by the program itself, not by you (see Run notes).

Gene won't fire a program that's missing a required section (GENE_PROGRAM_REQUIRE_SECTIONS, defaults to the first three; empty = no gate); it comments with what's missing instead. Give a program agent extra tools, on top of the base set, the tracker and (when the program links a repo) the forge CLI, with GENE_PROGRAM_ALLOWED_TOOLS (e.g. Bash(pup *),Bash(datadog *)). Follow-up work goes into sub-issues with the Gene label (never Program), so they enter the normal coding queue.

States

The ticket's state says whether a program is switched on, running, or waiting for you.

StateWhat it means for a program
TodoSwitched on and at rest. Its trigger is armed, g runs it, and so does a !gene comment. Every run comes back here.
In ProgressA run is live. If nothing is running it, Gene moves it back to Todo on the next scan.
BlockedWaiting for a human: the run asked a question, or the branch can't be synced. Reply to resume, or reply !gene stop to drop the run (→ Todo).
Triage, Backlog, any otherSwitched off: still with humans. Its trigger compiles (review it with t) but isn't armed, so it never runs on its own. Move it to Todo to switch it on. (g still runs it once, and the run lands in Todo.)

A program only ever moves between Todo, In Progress and Blocked, and lands in Blocked only when it needs you. It never rests in Blocked or In Progress.

A run, step by step

  1. Fired — press g on it in the dashboard, comment !gene … on it, or its trigger matches.
  2. Gene moves the ticket to In Progress. It posts no comment: the state says it's running, and the dashboard shows the live progress.
  3. If the program links a repo, Gene brings its worktree level with the remote branch.
  4. The agent carries out the Workflow: it comments its result on the ticket, may open sub-issues, and may update its run notes. If it needs a decision, it posts the question and moves the ticket to Blocked.
  5. When the run ends, Gene saves the run notes, folds away the comments from before this run, and moves the ticket as below.

How a run ends

The run…Ticket goes toLeft on the ticket
finishedTodothe agent's result comment
asked a questionBlockedthe question; reply to resume
didn't finish (Gene hit an error, the agent exited early or timed out, claude isn't logged in)TodoGene's comment saying why
was cancelled from the dashboardTodo—
was restarted (g while running)stays In Progress and fires again—
couldn't sync its branchBlockedGene's comment with the reason; fix the branch and reply

A program found In Progress with nothing running (the move back to Todo failed, or an older Gene left it there) is returned to Todo on the next scan, which re-arms its trigger. It is never re-run on that basis.

What the ticket shows

A program runs again and again, so its ticket is kept to what matters: the description (with its run notes), the newest comment, and its sub-issues.

When a run ends, Gene resolves every comment thread from before that run. Linear collapses resolved threads, but they stay readable, so a workflow can still look back at an earlier run's report. The newest comment always stays open, and so does anything posted during the run. Trello has no collapsible threads, so its comments are left as they are.

Every comment the agent posts ends with the agent marker (GENE_AGENT_MARKER, default #gene-ai). That's how Gene tells its own comments from yours, so a reply from you is what resumes a Blocked program or fires one in Todo, and the agent's own comments never do.

Run notes

A program can keep a little memory between runs in its own description, under ## Run notes: the last SHA it reviewed, where a rotation is up to. The agent writes its new notes to a file. When the run ends, Gene replaces just that section of the description as it is at that moment. It doesn't touch ## Trigger, ## Workflow, ## Acceptance criteria, or edits you made during the run.

The agent never edits the description itself, so a run can't rewrite your workflow or clobber an edit you're making.

To call the section ## Current state instead, add that heading to the description (empty is fine). Gene fills whichever of the two it finds first and keeps your heading as written. With neither, it appends ## Run notes.

  • Once the section exists, the agent refreshes it every run. Without one, notes are optional and the first run that writes some adds ## Run notes.
  • The notes are replaced, not appended to, so they stay short.
  • Notes identical to what's there leave the description untouched.
  • Changing the notes never recompiles the trigger.
  • A cancelled run's notes are dropped.

To use them, say so in the workflow: "Start from the SHA in the run notes; record the newest reviewed SHA there."

Asking a human

A program can stop mid-run to ask something: it posts the question and moves the ticket to Blocked. Reply on the ticket (!gene approve, or just answer) and the next scan resumes the run, with the question and your reply in its prompt. Reply !gene stop to drop the run instead; the program goes back to Todo.

Firing a program

From the ticket: comment on a program in Todo with a line addressed to Gene, e.g. !gene go ahead with option B. The next scan (within GENE_POLL_INTERVAL_MS) fires it, and the run gets your comment in its prompt as the reason it fired. Only comments posted since the program's last run count, and each fires one run. A comment without !gene doesn't fire anything: it's a note the next run reads. !gene stop has nothing to stop in Todo, so it doesn't fire either. A program switched off (Triage, Backlog) ignores !gene comments.

From the dashboard: in the dashboard, select a program row and press g, then g again within 2 s to confirm. Pressing g on a running program restarts it: the live run is cancelled and fired again. Programs are marked ⟳ in the list (ϟ when a trigger is armed); Shift+P shows programs only. Opening a program shows the live agent progress while it runs, and its activity log at rest, just like a coding ticket.

Branch

A program that links a repo runs on that repo's default branch. Pin another one with a ## Branch section holding just the branch name (or link the repo as …/tree/<branch>; ## Branch wins when both are set):

## Branch
release/2.x

The program's worktree is reused across runs, so before every run Gene fetches the branch and resets the worktree to origin/<branch>. Leftover edits and local commits from the previous run are discarded; untracked files are kept. If the branch can't be fetched (a typo, a deleted branch, no access), the program doesn't run: Gene comments with the reason and moves it to Blocked. Fix the branch and reply on the ticket to retry.

Triggers (opt-in)

Set GENE_PROGRAM_TRIGGERS=true and Gene fires programs on its own from their ## Trigger prose. When the prose is new or changes, a short agent run compiles it once into a small JavaScript check() function — written against standard-looking globals (fetch, exec, cron, localStorage, console, Date) — "every hour" becomes a cron check, "when one of my MRs needs a rebase" becomes a glab api query — cached until the prose changes. The daemon runs due checks on its poll; when one matches, the program fires and the check's reason (e.g. !87, !91 need rebase) is handed to the run. Write manual in ## Trigger to keep a program manual-only.

Triggers are off by default. To turn them on, add to your .gene.config (or .env.development) and restart Gene:

GENE_PROGRAM_TRIGGERS=true
# Commands a check may run, if a trigger needs to query something (no shell; read-only only).
# Leave empty for schedule-only ("every day at 08:00") and plain-URL triggers.
GENE_TRIGGER_EXEC_ALLOW=glab api,linear
# Optional tuning (defaults shown)
# GENE_PROGRAM_TRIGGER_COOLDOWN_MIN=30
# GENE_TRIGGER_IO_MIN_INTERVAL_MIN=5
# GENE_TRIGGER_COMPILE_MODEL=haiku

Then write the condition in the program's ## Trigger section, e.g.:

## Trigger
Every weekday at 08:00 UTC, if any open issue in the Cloud team has "YWH" in the title
and no `gene-triaged` label.

and move the ticket to Todo. Open the program in the TUI to see its trigger line (ϟ <summary> · in 4m · last: no fire) and press t to review the compiled code.

A trigger is armed only while the program is in Todo — Todo means "program activated". A new program in Triage or Backlog is still with humans: its trigger compiles (so you can review it with t) but never runs until you move the ticket to Todo. A Blocked program waits for a human too. Ticks that pass while a program isn't armed are dropped, not caught up later.

Trigger not firing?

Check, in order:

  1. No trigger line on the program's detail screen → GENE_PROGRAM_TRIGGERS=true isn't set for this Gene instance.
  2. Row shows ⟳ instead of ϟ → the program isn't in exactly the trigger state (LINEAR_TRIGGER_STATE / TRELLO_TRIGGER_STATE, default Todo; the name must match the team's state), or its trigger hasn't compiled yet.
  3. Still nothing → the program must carry the program label and be assigned to the configured assignee (LINEAR_ASSIGNEE / TRELLO_ASSIGNEE, default me); triggers of programs assigned to someone else are never checked.
  4. Trigger line in warning colour / "Couldn't compile the trigger" comment → the compile or check failed: claude isn't logged in on this machine, or the check runs a command not in GENE_TRIGGER_EXEC_ALLOW.

Limits

  • Sandboxed. Checks run in QuickJS with no filesystem, env, or network except fetch (http/https, no credentials added) and exec, which only runs commands matching GENE_TRIGGER_EXEC_ALLOW (e.g. glab api,argocd app list; empty by default). glab api is forced read-only, and flags that redirect a CLI to another host or config (--hostname, --server, --auth-token, --kubeconfig, …) are refused. Treat everything after an allowed prefix as written by whoever can edit the ticket: allow only read-only commands, and keep commands that print secrets (e.g. bao kv get) off the list — a check can read a command's output and fetch can reach any http(s) host, including internal ones.
  • Safety limits. A trigger never fires a program that is already running, and waits GENE_PROGRAM_TRIGGER_COOLDOWN_MIN (default 30) after the last fire — a g press counts. Checks that call out run at most every GENE_TRIGGER_IO_MIN_INTERVAL_MIN (default 5) minutes. A condition that stays true re-fires once per cooldown until the run fixes it; set ## Trigger to manual to silence it.
  • Visible. Armed programs show ϟ instead of ⟳ (a compiled trigger on a program outside Todo shows ⟳, and its last result reads skipped (inactive)); the detail view shows the compiled summary, next check and last result, and t shows the code. When a trigger compiles, Gene runs it once for real and logs whether it would fire right now. A trigger that can't be compiled, or whose check fails 3 times in a row, gets one comment on the ticket — and a check whose commands exit non-zero or print errors (e.g. an expired CLI login) counts as failing, not as "nothing to do".
  • Compiles use GENE_TRIGGER_COMPILE_MODEL (default haiku). g works exactly as before.

Safety and control

Gene runs unattended and acts with your credentials, so the guardrails are deliberate:

  • It never merges. Gene opens and updates change requests, and can mark a draft ready for review, but it never merges a PR/MR or pushes to your default branch — merging is always a human action.
  • Draft mode is a hard human gate. With GENE_DRAFT_CHANGE_REQUEST=true every change request opens as a draft and Gene never marks it ready; a human reviews and promotes it. This is enforced, not just requested: when a run finishes, Gene checks the change request and pushes it back to draft if the agent left it ready for review.
  • Dry run. GENE_DRY_RUN=true makes a full pass with no tracker/forge writes and no agent spawns — it just logs what it would do. The best way to try it on a real board.
  • It only touches tickets you opt in. A ticket is acted on only when it carries the Gene label and is assigned to you (*_ASSIGNEE); everything else is skipped.
  • Secrets stay local. Config splits into a committed gene.config and a gitignored .gene.config (keys, tokens), with real env always winning. Your ANTHROPIC_API_KEY is handed to the agent only when you opt into API billing — otherwise it's stripped from the agent's environment.
  • Optional sandbox. Set GENE_SANDBOX=true to run each claude -p agent inside a throwaway microVM instead of on your host (see sandbox/).
  • Self-hosted, no phone-home. Gene runs on your machine; its only outbound calls are to your tracker, your forge, and the Claude API (via claude).
  • Stuck runs fail safe. A stalled or interrupted agent is retried, then parked in Blocked with a comment rather than left hanging In Progress — and the worktree is preserved so a reply resumes it.

Repo targeting (per issue)

An issue declares its target repo simply by including a GitLab or GitHub link in its description — the first such link wins (comments are checked as a fallback). From the link Gene derives:

  • the change request forge — from the host: gitlab.* → glab, github.com → gh;
  • the repo — the project / owner/repo path (GitLab nested groups supported);
  • a monorepo subdir — from a …/tree/<branch>/<path> deep link, if present; the agent is told to scope its changes to that subdirectory;
  • the base branch — the <branch> in a /tree/ link, else the repo's default.
https://gitlab.com/example/example-repo                                   → gitlab, whole repo
https://gitlab.com/example/example-repo/-/tree/main/path/to/dir           → gitlab, subdir path/to/dir
https://github.com/example/example-repo                                   → github, whole repo

Issues with no link fall back to a per-team default repo, overridable via the GENE_REPO_URL env var or the GENE_REPO_MAP env var (a JSON object of team key → repo URL). If you run Gene from inside a git repo, that local repo becomes the default.

Repository model

  • target repos — cloned under .gene/repos/<repoPath>/ (gitignored; can be changed by GENE_REPOS_DIR). A repo is cloned on demand the first time an issue targets it; per-issue worktrees are created at .gene/repos/.worktrees/<repoPath>/<ISSUE-ID>, branched off the base. The branch name follows GENE_BRANCH_TEMPLATE (default {prefix}/{identifier}-{slug}; see .env.example). Runtime locks live in .gene/ (gitignored); the persistent state store needs no setup — embedded PGlite under ~/.config/gene/ by default, or an external Postgres when GENE_DATABASE_URL is set (see State store).

State store

Gene keeps its persistent state — the per-issue review cursor and activity log (db.ts) — in a small PostgreSQL store, with two backends picked automatically:

  • Embedded PGlite (default) — Postgres compiled to WASM, running in-process. No server, no setup: data lives under ~/.config/gene/pgdata (override with GENE_DB_DIR; honours XDG_CONFIG_HOME). This is what makes Gene self-contained — npm start just works. It is single-process: one Gene owns the data dir behind a self-healing PID lock, so a one-shot log / reset can't run while the daemon is up — stop it first, or use Postgres.
  • Postgres server (opt-in) — set GENE_DATABASE_URL and Gene talks to that instead. Multi-connection, so log / reset work alongside a running daemon. npm run pg brings up a throwaway local cluster under data/pg/ (gitignored) on port 5434 if you want one locally (GENE_DATABASE_URL=postgres://$USER@127.0.0.1:5434/postgres). The generic DATABASE_URL / PG* vars are ignored on purpose: Gene runs inside the project it works on, whose dev shell often sets them for the app's own database.

The schema is identical either way; switching backends starts a fresh store (state is not migrated between them). If the tables vanish under a running daemon (the database was reset), Gene recreates them on the next query.

Requirements

  • Claude Code — Gene shells out to claude -p, so you need either a Claude subscription (claude /login) or an ANTHROPIC_API_KEY with API billing (GENE_CLAUDE_API_BILLING=true). This is where the cost is: Gene itself is free and open source, but every dispatch — the initial work, plus each re-dispatch for a CI failure or review comment — is a real claude run. Token usage scales with ticket complexity and GENE_MAX_CONCURRENT; start with GENE_DRY_RUN=true and low concurrency to get a feel for it.
  • An issue tracker — a Linear or Trello account (GENE_TRACKER).
  • A change request forge and its CLI — gh (GitHub) and/or glab (GitLab), authenticated; plus git, and the linear CLI for the Linear backend.
  • OS — the prebuilt binary is macOS arm64 only. On Linux/Windows, run from source with Node 26 (npm start); everything but the single-file binary works the same.

Installation

Standalone binary (macOS arm64)

Install — or upgrade — to the latest release with one command. It drops a gene binary on your PATH (/usr/local/bin if writable, else ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/huksley/gene/main/install.sh | bash

Pass options after -s -- to choose where it lands or pin a release:

# install into a specific directory
curl -fsSL https://raw.githubusercontent.com/huksley/gene/main/install.sh | bash -s -- --dir ~/.local/bin
# or a specific release tag
curl -fsSL https://raw.githubusercontent.com/huksley/gene/main/install.sh | bash -s -- --version v1.2.3

Once installed, update in place from the running binary:

gene --update            # download + install the latest release (atomic, with rollback)
gene --update --force    # reinstall even if already on the latest
gene --version
gene --help

The binary bundles the embedded state store, so it needs no other dependencies to run — but Gene still shells out to the runtime CLIs (claude, git, gh/glab, and linear for the Linear backend). Install whichever you need from the Dependencies table below.

Dependencies

Once Gene is installed, authenticate the CLIs and configure your environment. The Trello backend needs no CLI login — it uses TRELLO_API_KEY + TRELLO_TOKEN via the optional @huksley/trello-cli.

Prefer isolation? The whole toolchain is packaged as a microVM — see sandbox/ to run claude -p agents in a throwaway VM (microsandbox) instead of installing the CLIs on your host.

# 1. Authenticate the CLIs (one-time, interactive — run with a leading `!` here)
glab auth login [--hostname gitlab.example.com]    # accept "use glab as a git credential helper"
gh auth login                                      # only if any issue targets a GitHub repo
linear login                                       # Linear backend: if not already logged in
claude /login                                      # OAuth / Subscription session or ANTHROPIC_API_KEY for API usage 

# Trello backend (GENE_TRACKER=trello): no login — mint TRELLO_API_KEY + TRELLO_TOKEN at https://trello.com/power-ups/admin and put them in .env.development (see trello/README.md)
# install Trello CLI
npm install -g @huksley/trello-cli

# 2. Configure (see .env.example for all supported params)

# Repo config - safe to add to the git
cat >gene.config <<END
# Use Linear
GENE_TRACKER=linear
LINEAR_TRIGGER_STATE=Todo
LINEAR_ACTIVE_STATE=In Progress
LINEAR_BLOCKED_STATE=Blocked
LINEAR_REVIEW_STATE=In Review
LINEAR_DONE_STATE=Done
GENE_REQUIRE_SECTIONS=## Problem,## Acceptance criteria
# How often recheck the issue tracker
GENE_POLL_INTERVAL_MS=30000
# How many tasks to run at the same time
GENE_MAX_CONCURRENT=4
LINEAR_IGNORE_COMMENTS=!review,/review
GITHUB_IGNORE_COMMENTS=/review,/linear
GENE_DRAFT_CHANGE_REQUEST=true
# Additional allowed tools for Claude Code
GENE_ALLOWED_TOOLS="Bash(ntn *)"
# Optional: run the agent in a sandbox
GENE_SANDBOX=false
END

# Secrets (never commit to the repo, add to .gitignore)
cat >.gene.config<<END
LINEAR_API_KEY=yourapikey
END

# Opt-in to the sandbox (experimental, optional)
# install microsandbox from https://microsandbox.dev/
npm install -g microsandbox

# 3. Run Gene
gene

Trackers (Linear / Trello)

Which issue tracker Gene uses is set by GENE_TRACKER (linear | trello, default linear), which is used for the work queue.

LinearTrello
issuean issuea card
stateworkflow state namethe card's list name
labelGene labelGene label
identifierTASK-1094the card's shortLink
branchLinear's auto-link branch, overridablesynthesized gene/<shortLink>, overridable
read accesslinear CLI (linear api)provided trello-cli
agent write-backlinear issue …provided trello-cli
authLINEAR_API_KEY / linear loginTRELLO_API_KEY + TRELLO_TOKEN

Tracker-specific config is namespaced by the active tracker (LINEAR_* / TRELLO_*); only the selected block is read, so the internal names stay neutral and every consumer is unchanged. Trello also needs TRELLO_BOARD (the board whose cards it watches) and accepts an optional TRELLO_LIST_MAP (JSON state-name → list-id) for when a board's list names differ from the state names. See .env.example for the full list, and trello/README.md for minting the key + token.

Two honest differences from Linear: Trello has no MR/PR ↔ card auto-link, so the agent links the change request in the card's description/comments instead; and the assignee filter matches a Trello username, not an email (me / any work identically).

FAQ

Does Gene merge code by itself? No. It opens and updates pull/merge requests and can mark a draft ready for review, but a human always does the merge — and with GENE_DRAFT_CHANGE_REQUEST=true it won't even mark them ready. See Safety and control.

What does it cost to run? Gene is free and open source (Apache-2.0). The cost is whatever Claude Code costs you: it runs claude -p under your subscription or ANTHROPIC_API_KEY. Each dispatch is a real run, and re-dispatches (CI failures, review replies) add up, so token usage scales with ticket complexity and GENE_MAX_CONCURRENT.

Are my code or secrets sent anywhere? Does it phone home? No phone-home — Gene is self-hosted. Your code reaches Anthropic exactly as it would if you ran Claude Code by hand. Secrets stay in your gitignored .gene.config/environment, and your API key is handed to the agent only when you turn on API billing.

Is it macOS only? The prebuilt binary is macOS arm64. On Linux/Windows you run from source with Node 26 — same behaviour, just no single-file binary.

Why not just use Claude Code (or aider) directly? Gene is the harness around claude, not a replacement: it polls your tracker, drives the ticket lifecycle, routes each issue to its own repo/forge, re-dispatches on CI failures and review comments, and recovers from crashes — so a ticket becomes a PR while you're doing something else.

What if it gets something wrong or gets stuck? You review every PR before it merges, and draft mode adds a gate. A stalled or interrupted run is retried and then parked in Blocked with a comment, not left hanging — and the worktree is kept so your reply resumes it. Run with GENE_DRY_RUN=true first to watch its decisions with zero writes.

Can I run it headless on a server? Yes — gene --headless runs the daemon without the TUI dashboard, logging to stdout (gene --once does a single scan and exits). Point it at an external Postgres (GENE_DATABASE_URL) if you want to inspect state while it runs.

Which trackers and forges are supported? Trackers: Linear and Trello. Forges: GitHub and GitLab, chosen per issue from the repo link. Jira, GitHub Issues, and Bitbucket aren't supported yet.

Does it work on monorepos? Yes — a …/tree/<branch>/<path> deep link in the ticket scopes the agent to that subdirectory and base branch. See Repo targeting.

How do I try it safely first? Set GENE_DRY_RUN=true and a low GENE_MAX_CONCURRENT, label one throwaway ticket, and watch the logs — Gene reports what it would do without writing to your tracker or forge or spawning agents.

Ver o original no GitHub

Bom para

Relacionados