isa:planning isa:implementing isa:validating isa:trigger isa:success

Your GitHub issues,
resolved by AI.

ISA polls your repositories, orchestrates Claude and Gemini agents to plan and implement changes, validates through your CI pipeline, and opens pull requests. No database, no external services — just GitHub.

See how it works
isa-service
How It Works

From issue to pull request

Label an issue with isa:trigger and ISA handles the rest. When things go differently, the pipeline adapts.

01
Trigger
Add isa:trigger label
isa:trigger
02
Discover
Identify needed repos
isa:discovering
03
Plan
Explore code, build plan
isa:planning
04
Implement
Edit files, push changes
isa:implementing
05
Validate
Run checks and tests
isa:validating
06
Ship
PRs created, issue closed
isa:success
acme/backend-api
Issue
Add rate limiting to API endpoints #42
● Open opened 14 minutes ago
Ivan added isa:trigger 14 min ago
I
Ivan 14 min ago

Public endpoints have no throttling. Add a sliding window rate limiter to GET and POST routes, return 429 when exceeded, and make limits configurable per-environment.

isa added isa:discovering 13 min ago
ISA
isa bot 13 min ago

Workspace ready — 3 repos identified

acme/backend-api — target repo (this issue)
acme/shared-middleware — existing throttling patterns
acme/api-gateway — existing rate limit headers
isa added isa:planning 11 min ago
ISA
isa bot 10 min ago

Plan ready — 3 files across 1 repo

src/middleware.py — Sliding window rate limiter middleware
@@ class RateLimiter @@
+ def __init__(self, limit: int, window: int):
+ self.limit = limit
+ self.cache: dict[str, list[float]] = {}
+ def is_allowed(self, client_ip: str) -> bool:
+ return len(self._recent(client_ip)) < self.limit
src/routes.py — Apply rate limiter to public endpoints
src/config.py — RATE_LIMIT, RATE_WINDOW settings
isa added isa:implementing 8 min ago
isa added isa:validating 4 min ago
ISA
isa bot 2 min ago
✓ Pipeline complete — PR #43 ready for review

+85 −2 across 3 files · All CI checks passing

isa added isa:success 2 min ago
acme/backend-api
Pull Request
isa(#42): Add rate limiting to API endpoints #43
● Open opened 4 minutes ago by isa
isa/42 ← main +85 −2

Summary

Adds sliding window rate limiting to all public API endpoints. Configurable per-route limits with shared middleware.

Changes

  • src/middleware.py — New RateLimiter class with sliding window
  • src/routes.py — @rate_limit decorator on public endpoints
  • src/config.py — RATE_LIMIT, RATE_WINDOW settings
Closes #42
3 files changed
src/middleware.py
src/routes.py
src/config.py
✓
CI / tests (3m 12s)
✓
CI / lint
✓
CI / type-check
✓
All checks passed — ready to merge
AI Agents

Four specialized roles, any model

Each pipeline step is powered by a dedicated AI agent with its own tools and model. Mix Claude and Gemini freely across roles.

Step 02 · Discover

Discovery

Identifies which repos matter and builds a multi-repo workspace.

▷ Scanning org repos…
✓ 3 repos: backend-api, auth-lib, sdk
✓ Workspace ready
Step 03 · Plan

Planner

Explores the codebase and builds a step-by-step implementation plan.

▷ Exploring codebase…
✓ Plan ready — 3 files, 2 modules
Step 04 · Implement

Implementation

Edits files, runs commands, and pushes changes to a feature branch.

▷ Editing src/middleware.py…
▷ Editing src/routes.py…
✓ Committed + pushed to isa/42
Step 05 · Validate on demand

Plan Review

Checks CI results and test output against the original plan.

▷ Reviewing CI output…
✓ All checks passed
Claude API key or subscription
opus sonnet haiku
Gemini API key or Vertex AI
2.5-pro 2.5-flash 3-pro 3-flash 3.1-pro

Any model, any role — mix providers freely across agents.

Configuration

Three YAML files. That's it.

Define what repos to watch, how to process issues, and which AI models to use. No code changes needed for most customizations.

Maps GitHub repositories to workflows. Add per-repo overrides for branches, retries, approval requirements, and validator config.
repos:
  # Simple: just point a repo at a workflow
  - name: my-python-project
    workflow: general

  # Advanced: per-repo overrides
  - name: my-critical-project
    workflow: general
    base_branch: develop              # override workflow default
    max_retries: 5                    # override workflow default
    require_plan_approval: true      # force approval for this repo
    validator:
      config:
        timeout: 300                  # merged with workflow validator config
Defines processing behavior: branch patterns, agents, validators, hooks, completion actions, and more.
workflows:
  general:
    working_branch: "isa/{issue_number}"
    base_branch: main
    context_resolver: isa.context.SingleRepoResolver

    agents:
      planner: general-planner           # references agents.yaml
      implementation: general-implementation

    validator:
      type: none                          # "none" or dotted Python path

    completion:
      create_prs: true
      pr_targets: [main]                 # PR to multiple branches
      close_issue: true
      delete_working_branch: false

    require_plan_approval: false
    max_retries: 3
    max_run_duration: 1800               # seconds before poller kills the run

    hooks:
      on_success:
        - type: api_call
          config:
            url: "https://your-webhook.example.com/notify"
            body: { text: "ISA completed #{issue_number}" }
Defines AI agent profiles: model, tools, timeout, reasoning budget, and domain-specific system prompts. Output formats are handled automatically by the framework.
agents:
  general-planner:
    model: opus                            # or sonnet, haiku, gemini-*
    timeout: 600
    allowed_tools:
      - Read
      - Glob
      - Grep
    system_prompt: |
      You are a planning agent. Given a GitHub issue and a codebase,
      explore the code and create a detailed implementation plan.

  general-implementation:
    model: opus
    timeout: 600
    allowed_tools: [Edit, Write, Read, Glob, Grep, Bash]
    # thinking: high                     # optional reasoning budget
    system_prompt: |
      You are an implementation agent. Follow the plan exactly.
      Do not add features beyond what was asked.
Extensibility

A Python class and a dotted path

No SDKs, no frameworks, no plugin registries. Write a class, reference it in YAML, and ISA loads it at runtime.

Context Resolvers

The backbone of multi-repo workflows. The Discovery agent identifies repos at runtime, then resolve() clones them and expand() adds more mid-planning. Extra context keys are automatically injected into agent prompts.

SingleRepoResolver resolve() → WorkspaceLayout expand() → add repos mid-plan extra_context → agent prompts
context_resolver: myapp.resolvers.MultiRepoResolver # Discovery agent feeds repos → resolve() clones them # Planner can request more → expand() adds mid-plan # extra_context keys auto-surface in agent prompts

Validators

Run after implementation to check results. Integrate your CI pipeline, test suites, linters, or any custom validation. Three result statuses drive the next step.

NoopValidator success needs_review failure
validator: type: myapp.validators.CIValidator config: timeout: 300

Hooks

Actions that fire at pipeline transitions. Merge branches, push code, call webhooks, run scripts, or write your own handler — all configurable per workflow.

merge_to_branch push_branch run_script api_call
hooks: on_success: - type: myapp.hooks.SlackNotifier config: { channel: "#deploys" }

Hook points in the pipeline lifecycle

after_plan
after_implementation
after_validation
on_success
on_failure
Human-in-the-Loop

AI proposes, you decide

Review plans before implementation, answer agent questions, retry with feedback, or revert changes — all from GitHub issue comments.

Add rate limiting to API endpoints #42
● Open isa:awaiting-approval
ISA
isa bot 3 minutes ago

Plan ready for review

Files to change (3):
src/middleware.py — Sliding window rate limiter
src/routes.py — Apply limiter to public endpoints
src/config.py — RATE_LIMIT, RATE_WINDOW settings

Reply /approve to proceed or /replan with feedback.

you
Ivan 2 minutes ago

/replan Also add rate limit headers (X-RateLimit-Remaining) to responses

ISA
isa bot 1 minute ago

Updated plan

Files to change (4):
src/middleware.py — Sliding window rate limiter
src/routes.py — Apply limiter to public endpoints
src/config.py — RATE_LIMIT, RATE_WINDOW settings
src/responses.py — Rate limit headers in API responses

Reply /approve to proceed.

you
Ivan 1 minute ago

/approve

ISA
isa bot just now
✓ Implementation complete — 4 files changed, pushed to isa/42

PR #43 created → main. All checks passing.

From Planning

Needs clarification → NEEDS_INFO → user replies → re-plan
Approval required → AWAITING_APPROVAL /approve → implement · /replan → re-plan · /reject → failed

From Validation

Checks failed → AWAITING_DECISION /retry → re-plan · /revert → undo commits · /revalidate → re-check · /abort → failed

Available Commands

/approve Accept plan, start implementation
/replan Re-plan with your feedback
/reject Reject the plan entirely
/retry Re-plan after validation failure
/revert Undo ISA commits (last, all, or specific SHA)
/revalidate Re-run validation without re-planning
/abort Stop processing this issue
Per-repo and per-issue control: Set require_plan_approval: true in repos.yaml, or add the isa:require-approval label to any individual issue. Use isa:skip-approval to bypass approval on a case-by-case basis.
Reliability

GitHub is the database

Every state transition is a comment edit. No external database, no Redis, no message queue. Crash recovery is a heartbeat check.

State Persistence

Storage GitHub issue comments
Heartbeat interval 60 seconds
Stale threshold 300 seconds
Claim mechanism Comment ID tiebreaker
External dependencies None
<!-- isa-bot --> <!-- isa-state {"attempt":1,"max_retries":3,...} --> Status: Implementing (1/3) · 5m elapsed

Crash Recovery

When the service restarts or a pipeline crashes mid-execution:

1. Poller detects stale heartbeat (>300s old)
2. Issue transitioned to AWAITING_DECISION
3. User notified with available commands
4. On restart: reclaim via edited state comment
5. Large fields reloaded from marker comments

Distributed claiming uses a comment-ID tiebreaker: multiple instances can race, lowest comment ID wins. No coordination service needed.

Enterprise

Your code, your keys, your infrastructure

ISA runs entirely in your environment. No code leaves your network. You bring your own AI provider keys.

Self-Hosted Deployment

Ship as a Docker image or Helm chart. Runs on any infrastructure with outbound HTTPS access.

  • Docker / docker-compose for simple setups
  • Kubernetes with Helm chart for orchestration
  • Your own AI API keys (Anthropic, Google)
  • GitHub App or PAT authentication
  • No inbound ports needed (polling mode)
┌────────────────────────────────────────┐ │ Your Infrastructure │ │ │ │ ┌──────────────────────────────────┐ │ │ │ ISA Container │ │ │ │ ┌────────────────────────────┐ │ │ │ │ │ Pipeline Engine + Poller │ │ │ │ │ └────────────────────────────┘ │ │ │ │ ┌────────────┐ ┌─────────────┐ │ │ │ │ │ Claude CLI │ │ Gemini CLI │ │ │ │ │ └────────────┘ └─────────────┘ │ │ │ └──────────────────────────────────┘ │ │ │ │ │ │ ┌────┬────┐ ┌─────┬─────┐ │ │ │ GitHub │ │ AI APIs │ │ │ └─────────┘ └───────────┘ │ └────────────────────────────────────────┘

Licensing

ISA is available under the Business Source License 1.1. Free for non-commercial and evaluation use. Commercial production use requires a license.

  • Non-commercial use: always free
  • Internal evaluation: always free
  • Commercial production: licensed
  • Converts to Apache 2.0 after 4 years
Enterprise packages include implementation contracts, custom validator and hook development, agent prompt engineering, deployment assistance, and ongoing support with SLA.
ISA

Ready to automate your issues?

Get ISA running on your repositories in a single afternoon.

Get in touch →