Lisa

Label an issue. Walk away. Come back to a PR.

Lisa connects your issue tracker to an AI coding agent and delivers pull requests — autonomously. Tag an issue with a label, Lisa picks it up, implements it, opens a PR, and updates your board. No babysitting.

Quickstart

npm install -g @tarcisiopgs/lisa
lisa init    # interactive setup wizard
lisa run

How It Works

  Fetch issue → Activate → Build context → Implement → Push → Open PR → Update board → Next

Lisa picks the highest-priority labeled issue, moves it to "In Progress", sends a structured prompt to the AI agent, and monitors execution. The agent works in an isolated git worktree, implements the change, runs tests, and commits. Lisa pushes, opens a PR, moves the ticket to "In Review", and picks up the next one.

If something fails — pre-push hooks, quota limits, stuck processes — Lisa handles it: retries with error context, falls back to the next model, or kills and moves on.

Features

• 7 issue trackers — Linear, GitHub Issues, GitLab Issues, Jira, Trello, Plane, Shortcut
• 8 AI agents — Claude Code, Gemini CLI, GitHub Copilot CLI, Cursor Agent, Aider, Goose, OpenCode, Codex
• Concurrent execution — process multiple issues in parallel, each in its own worktree
• Multi-repo — plans across repos, creates one PR per repo in the correct order
• Model fallback — chain models; transient errors (429, quota, timeout) auto-switch to the next
• Real-time TUI — Kanban board with live provider output, keyboard controls, PR merge detection
• Self-healing — orphan recovery on startup, push failure retry, stuck process detection
• Guardrails — past failures are injected into future prompts to avoid repeating mistakes
• Project context — auto-generates .lisa/context.md with your stack, conventions, and constraints

Providers

Configure a fallback chain:

provider: claude
models:
  - claude-sonnet-4-6   # primary
  - claude-opus-4-6     # fallback

Commands

lisa run                     # start the agent loop
lisa run --once              # process a single issue
lisa run --once --dry-run    # preview config without executing
lisa run --watch             # poll for new issues after queue empties
lisa run --concurrency 3     # process 3 issues in parallel
lisa run --issue INT-42      # process a specific issue
lisa run --limit 5           # stop after 5 issues
lisa init                    # create .lisa/config.yaml interactively
lisa status                  # show session stats
lisa context refresh         # regenerate project context
lisa feedback --pr URL       # inject PR review feedback into guardrails

Configuration

Config lives in .lisa/config.yaml. Run lisa init to create it interactively.

provider: claude
source: linear
workflow: worktree       # "worktree" (isolated) or "branch" (in-place)

source_config:
  team: Engineering
  project: Web App
  label: ready
  pick_from: Backlog
  in_progress: In Progress
  done: In Review

platform: cli            # "cli" (gh), "token" (GITHUB_TOKEN), "gitlab", "bitbucket"
base_branch: main

# PR creation (at least one)
GITHUB_TOKEN=""           # or use `gh` CLI
GITLAB_TOKEN=""           # for platform: gitlab
BITBUCKET_TOKEN=""        # for platform: bitbucket
BITBUCKET_USERNAME=""

# Issue tracker (set the one you use)
LINEAR_API_KEY=""
TRELLO_API_KEY="" && TRELLO_TOKEN=""
PLANE_API_TOKEN=""
SHORTCUT_API_TOKEN=""
GITLAB_TOKEN=""
GITHUB_TOKEN=""
JIRA_BASE_URL="" && JIRA_EMAIL="" && JIRA_API_TOKEN=""

repos:
  - name: my-api
    path: ./api
    base_branch: main
    match: "[API]"        # route issues by title prefix
  - name: my-app
    path: ./app
    base_branch: main

loop:
  cooldown: 10             # seconds between issues
  session_timeout: 0       # max seconds per provider run (0 = disabled)

overseer:
  enabled: true
  check_interval: 30       # seconds between git status checks
  stuck_threshold: 300     # kill provider after this many seconds without changes

lifecycle:
  mode: auto               # "auto", "skip" (default), "validate-only"
  timeout: 30

validation:
  require_acceptance_criteria: true

Writing Good Issues

Issue quality = PR quality. Lisa validates issues and skips vague ones (labeling them needs-spec).

Include: acceptance criteria (- [ ] checklists), relevant file paths, technical constraints, stack info.

Title: Add rate limiting to /api/users endpoint

Implement rate limiting on `/api/users` to prevent abuse.

Relevant files: src/routes/users.ts, src/middleware/auth.ts

Acceptance criteria:
- [ ] Requests exceeding 100/min per IP return HTTP 429
- [ ] Rate limit headers included in responses
- [ ] Rate limit state stored in Redis (use src/lib/redis.ts)
- [ ] Existing tests still pass

TUI

The real-time Kanban board shows issue progress, streams provider output, and detects PR merges.

License

MIT