Gremlins

gremlins

Background coding-agent pipelines that plan, implement, review, and land work end-to-end. Given a goal or GitHub issue, a gremlin runs the full plan → implement → review-code → address-code cycle unattended, writing artifacts to the per-user state directory resolved by `platformdirs.user_state_dir("gremlins")` and optionally opening a pull request. A fleet manager tracks running, stalled, and finished gremlins and provides stop / land / close operations.

**Status: brand-new and a bit janky.** This is a fresh project, actively shaped by daily use. Expect rough edges — stream timeouts, the occasional merge conflict from parallel gremlins, a few stages still finding their final shape. Bug reports, ideas, and PRs are all welcome.

---

Using gremlins with a coding assistant

Paste the output of `gremlins prompt-for-assistant` into a fresh Claude Code session (or any compatible assistant) to configure it as a competent gremlins collaborator.

The workflow: you discuss the work with the assistant, it captures discrete units as GitHub issues or plan files, launches gremlins in the background to implement them, and lands each finished gremlin before starting dependent work. You stay at the strategic level — deciding what to build and in what order — while gremlins handle the implementation cycle unattended. The assistant maintains a queue of running, pending, and blocked work and surfaces it on request.

---

Using gremlins across multiple repos

When you run `gremlins launch`, the launcher captures the current working directory's repo root via `git rev-parse --show-toplevel` and stores it as `project_root` in the gremlin's `state.json`. That value pins the worktree base, child process cwd, and pipeline discovery for that gremlin's lifetime.

**To work on a different repo: `cd` there, then `gremlins launch`.** There is no `--project-root` flag; the cwd at launch time is the contract.

**Fleet view** (`gremlins`) shows gremlins from all repos by default. P