Gene AI
huksley/gene
Do ticket ao PR mergeável, completamente automatizado com Claude Code
Ver no GitHubAgent 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/gene1 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
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
Genelabel — 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, defaultme; setanyto 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 state | What the daemon sees | What Gene does |
|---|---|---|
| Todo | a change request is already attached | continues that change request on its own branch — skips planning |
| Todo | no change request yet | starts from scratch: plan → code → open the MR/PR → In Review |
| In Progress | a new human comment | hands it to the work in flight as feedback |
| Blocked | a new human reply | resumes — Gene had asked a question or proposed a plan that a human needs to confirm |
| In Review | a new review comment on the change request | re-dispatches Claude Code to address it — acts even while CI is still running |
| In Review | the CI/CD for a change request failed | re-dispatches Claude Code to address the failure |
| In Review | nothing new (quiet; CI green or still running) | no-op — waits for the next signal |
| In Review | the change request has been merged | moves 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.
## Triggersays when it runs (see Triggers), ormanual.## Workflowis what the agent does on each run.## Acceptance criteriais 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.
| State | What it means for a program |
|---|---|
| Todo | Switched on and at rest. Its trigger is armed, g runs it, and so does a !gene comment. Every run comes back here. |
| In Progress | A run is live. If nothing is running it, Gene moves it back to Todo on the next scan. |
| Blocked | Waiting 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 other | Switched 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
- Fired — press
gon it in the dashboard, comment!gene …on it, or its trigger matches. - Gene moves the ticket to In Progress. It posts no comment: the state says it's running, and the dashboard shows the live progress.
- If the program links a repo, Gene brings its worktree level with the remote branch.
- 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.
- 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 to | Left on the ticket |
|---|---|---|
| finished | Todo | the agent's result comment |
| asked a question | Blocked | the question; reply to resume |
didn't finish (Gene hit an error, the agent exited early or timed out, claude isn't logged in) | Todo | Gene's comment saying why |
| was cancelled from the dashboard | Todo | — |
was restarted (g while running) | stays In Progress and fires again | — |
| couldn't sync its branch | Blocked | Gene'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:
- No trigger line on the program's detail screen →
GENE_PROGRAM_TRIGGERS=trueisn't set for this Gene instance. - Row shows ⟳ instead of ϟ → the program isn't in exactly the trigger state
(
LINEAR_TRIGGER_STATE/TRELLO_TRIGGER_STATE, defaultTodo; the name must match the team's state), or its trigger hasn't compiled yet. - Still nothing → the program must carry the program label and be assigned to the
configured assignee (
LINEAR_ASSIGNEE/TRELLO_ASSIGNEE, defaultme); triggers of programs assigned to someone else are never checked. - Trigger line in warning colour / "Couldn't compile the trigger" comment → the
compile or check failed:
claudeisn't logged in on this machine, or the check runs a command not inGENE_TRIGGER_EXEC_ALLOW.
Limits
- Sandboxed. Checks run in QuickJS with no filesystem, env, or network except
fetch(http/https, no credentials added) andexec, which only runs commands matchingGENE_TRIGGER_EXEC_ALLOW(e.g.glab api,argocd app list; empty by default).glab apiis 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 andfetchcan 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 — agpress counts. Checks that call out run at most everyGENE_TRIGGER_IO_MIN_INTERVAL_MIN(default 5) minutes. A condition that stays true re-fires once per cooldown until the run fixes it; set## Triggertomanualto 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, andtshows 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(defaulthaiku).gworks 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=trueevery 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=truemakes 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
Genelabel and is assigned to you (*_ASSIGNEE); everything else is skipped. - Secrets stay local. Config splits into a committed
gene.configand a gitignored.gene.config(keys, tokens), with real env always winning. YourANTHROPIC_API_KEYis 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=trueto run eachclaude -pagent inside a throwaway microVM instead of on your host (seesandbox/). - 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/repopath (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 byGENE_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 followsGENE_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 whenGENE_DATABASE_URLis 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 withGENE_DB_DIR; honoursXDG_CONFIG_HOME). This is what makes Gene self-contained —npm startjust works. It is single-process: one Gene owns the data dir behind a self-healing PID lock, so a one-shotlog/resetcan't run while the daemon is up — stop it first, or use Postgres. - Postgres server (opt-in) — set
GENE_DATABASE_URLand Gene talks to that instead. Multi-connection, solog/resetwork alongside a running daemon.npm run pgbrings up a throwaway local cluster underdata/pg/(gitignored) on port 5434 if you want one locally (GENE_DATABASE_URL=postgres://$USER@127.0.0.1:5434/postgres). The genericDATABASE_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 anANTHROPIC_API_KEYwith 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 realclauderun. Token usage scales with ticket complexity andGENE_MAX_CONCURRENT; start withGENE_DRY_RUN=trueand 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/orglab(GitLab), authenticated; plusgit, and thelinearCLI 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 runclaude -pagents 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.
| Linear | Trello | |
|---|---|---|
| issue | an issue | a card |
| state | workflow state name | the card's list name |
| label | Gene label | Gene label |
| identifier | TASK-1094 | the card's shortLink |
| branch | Linear's auto-link branch, overridable | synthesized gene/<shortLink>, overridable |
| read access | linear CLI (linear api) | provided trello-cli |
| agent write-back | linear issue … | provided trello-cli |
| auth | LINEAR_API_KEY / linear login | TRELLO_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.