tissues 🧻

AI Enhanced GitHub Issues: create consistent, high-quality GitHub Issues cut for agents to make reliable updates to your codebase through rich context add-ons for git history, related issues, project rules, coding standards, risk and complexity scores, auto-labeling, and templates.

Agent Safety Mechanics: automatic data recovery, configurable rate limits, loop detection with circuit breakers, auditable signatures.

Install

Homebrew (recommended):

brew install calebogden/tap/tissues

npm:

npm install -g tissues

Requires Node.js >= 18.

Quick Start

# Authenticate (auto-detects gh CLI token)
tissues auth

# Set your active repo and configure AI (interactive wizard)
tissues config

# Create an issue interactively (title as positional argument — no quotes needed)
tissues create fix the login bug

# Check auth, safety, and config status
tissues status

Commands

tissues auth

Authenticate with GitHub. Auto-detects your gh CLI token if you're already logged in via gh. Falls back to GitHub OAuth Device Flow if not.

tissues auth

tissues create

Create a new GitHub issue. Runs dedup checks and safety gates before creating anything.

tissues create [title...] [options]

Options:

| Flag | Description | |---|---| | --repo <owner/name> | Override active repo | | --template <name> | Template to use: default, bug, feature, or custom | | --title <title> | Issue title (skips interactive prompt and triage step — title used as-is) | | --body <text> | Issue body / description — the actual content describing the issue (skips interactive prompt) | | --instructions <text> | AI enhancement instructions: guides how the AI writes the issue body (e.g. "keep it under 200 words", "use formal tone"). Does not appear in the created issue. Optional — skips interactive prompt when provided. | | --no-enhance | Skip AI enhancement, use rendered template as-is | | --pipeline | Force multi-step AI pipeline even if config disabled | | --no-pipeline | Force single-shot AI enhancement even if pipeline enabled | | --batch <file> | Create multiple issues from a JSON file. Each item supports: title, body, template, labels, agent, session | | --labels <labels> | Comma-separated labels to apply. If a label doesn't exist on the repo, tissues will prompt to create it automatically. | | --agent <name> | Agent identifier for attribution (default: human) | | --session <id> | Session ID for attribution and idempotency | | --force | Skip dedup warnings (still blocks on exact matches) | | --dry-run | Check dedup and safety without creating the issue |

Examples:

# Interactive (title pre-filled from positional argument)
tissues create fix the login bug

# Fully scripted (no prompts)
tissues create \
  --repo owner/my-repo \
  --template bug \
  --title "Login fails on Safari 17" \
  --body "Reproducible on fresh profile. Console shows CORS error." \
  --instructions "Keep it under 150 words and include a clear reproduction checklist." \
  --labels "bug,P1"

# From an AI agent
tissues create \
  --agent claude-opus-4-6 \
  --session abc123 \
  --template feature \
  --title "Add dark mode toggle" \
  --dry-run

tissues drafts

Manage issue drafts. tissues saves your issue to .tissues/drafts/ before any safety or dedup checks — the drafts command lets you view, flush, retry failed items, or clear the queue.

tissues drafts                    # interactive management menu
tissues drafts flush              # flush pending issues (non-interactive)

tissues templates

Manage issue templates interactively. View, edit, or create templates. Editing a built-in template creates a user copy that overrides the default.

tissues templates

tissues ai

AI-powered issue management. The agent translates natural language into JSON actions with built-in guardrails — it only handles tissues/GitHub operations and declines off-topic requests.

# Single-shot: natural language → action
tissues ai list my open issues
tissues ai what repos do I have access to
tissues ai create a bug report about login failing on Safari

# Preview without executing
tissues ai --dry-run add a feature request for dark mode

# Multi-turn conversation
tissues ai --chat
tissues ai --chat "set up labels for our project"

In chat mode, the agent can list issues, switch repos, manage config, create issues, and more — all from natural language. Test the agent with npm run test:agent -- --mock.

See AI Agent docs for prompt architecture, guardrails, and testing details.

tissues sync

Sync issues, labels, and repos to the local cache. The cache makes dedup checks instant and eliminates redundant network calls.

# One-shot sync
tissues sync
tissues sync --repo owner/other-repo
tissues sync --force                    # full re-sync

# Background daemon
tissues sync start                      # fork daemon process
tissues sync status                     # check daemon health
tissues sync stop                       # stop daemon
tissues sync restart

The daemon uses adaptive intervals (2 min when active, up to 60 min when idle) and incremental since-based fetching for issues.

tissues storage

Inspect and manage all cached/stored data.

tissues storage                         # overview dashboard
tissues storage issues                  # per-repo issue breakdown
tissues storage clear issues            # clear cached issues
tissues storage clear all               # clear everything
tissues storage clear all --include-safety  # also reset circuit breaker
tissues storage export                  # JSON dump for debugging
tissues storage --json                  # machine-readable overview

tissues list

Browse open issues for the active repo (served from local cache when fresh).

tissues list
tissues list --repo owner/other-repo

tissues status

Show auth, AI config, safety status, and draft count for the active repo.

tissues status
tissues status --agent claude-opus-4-6
tissues status --reset   # force-reset circuit breaker to closed

Data Recovery

tissues never silently discards your input. Before any safety check or network call, your issue is written to .tissues/drafts/. If a rate limit, circuit breaker, or network failure blocks submission, your work is saved and tissues drafts flush sends it when you're ready.

# See what's waiting
tissues status       # shows "Drafts: N pending"

# Manage or flush
tissues drafts       # interactive: view, flush, retry, clear
tissues drafts flush # send all pending (non-interactive)

→ See Non-Destructive Data Policy and Your Data in tissues for full details.

AI Enhancement

tissues enhances your issues using an 8-step AI pipeline. You type freeform text into "What's the issue" and the pipeline derives everything: the triage step extracts a concise title and structured description, followed by duplicate check, context extraction, scope analysis, complexity scoring, risk assessment, label suggestion, and body formatting. Each step feeds the next, producing structured issues with scores, auto-labels, and rich sections.

# Interactive setup
tissues config

# Or set a key directly
tissues config set ai.keys.anthropic sk-ant-your-key

  ✓ Input analyzed: Fix OAuth 401 error on Safari
  ✓ Duplicate check (none)
  ✓ Context gathered
  ✓ Scope analyzed (3 files)
  ✓ Complexity: 4/10
  ✓ Risk: 2/10
  ✓ Labels: bug, P2-medium
  ✓ Body formatted

The pipeline is resilient — failed steps are skipped, and the format step always runs with whatever data is available. Use --no-pipeline for single-shot enhancement, or --no-enhance to skip AI entirely.

→ See AI Enhancement docs for pipeline configuration, providers, routing rules, model selection, and token budgets.

Safety Features

tissues is designed to be called from AI agent loops. The safety infrastructure prevents one misconfigured agent from flooding a repo with issues.

Circuit Breaker

Three-state machine (closed / half-open / open) per repo+agent pair.

• Closed — normal operation
• Open — creation blocked; cooldown in effect (default: 30 minutes)
• Half-open — one probe request allowed through to test recovery

The circuit trips after 3 blocked attempts (dedup blocks count as failures). If the probe succeeds, the circuit resets to closed automatically.

To inspect or reset:

tissues status
tissues status --reset

Rate Limiting

Three independent rate limits, all checked before creating:

| Limit | Default | Scope | |---|---|---| | Per-agent hourly | 10 issues/hour | per repo + agent | | Per-agent burst | 5 issues / 5 minutes | per repo + agent | | Global hourly | 30 issues/hour | per repo, all agents combined |

All limits are configurable in .tissues/config.json.

Deduplication (3 layers)

Dedup runs cheapest-first before every create:

1. Idempotency key (O(1) DB lookup) — blocks if the same agent + trigger + issueType + repo combination has already created an issue this session.
2. Content fingerprint (O(1) DB lookup) — SHA-256 of normalized title + first 500 chars of body. Blocks exact re-submissions even across sessions.
3. Fuzzy title match (O(n) GitHub API) — Levenshtein similarity against all open issues. Blocks at >95% similarity; warns at >80%.

A block always prevents creation. A warn prompts interactively (or is skipped with --force).

Attribution Tracking

Every issue created by tissues includes a machine-readable <!-- tissues-meta --> block. See Attribution below.

Configuration

Configuration is loaded and merged from three sources in ascending priority order:

1. Built-in defaults
2. User-level config: ~/.config/tissues/config.json
3. Repo-level config: .tissues/config.json

Example .tissues/config.json

{
  "safety": {
    "maxPerHour": 5,
    "burstLimit": 3,
    "burstWindowMinutes": 5,
    "tripThreshold": 3,
    "cooldownMinutes": 30,
    "globalMaxPerHour": 20
  },
  "dedup": {
    "blockAbove": 0.95,
    "warnAbove": 0.80,
    "fingerprintTTLDays": 90
  },
  "attribution": {
    "required": false,
    "defaultAgent": "human"
  },
  "templates": {
    "dir": ".tissues/templates",
    "default": "bug"
  },
  "hooks": {
    "postCreate": "scripts/notify-slack.sh"
  }
}

Background sync configuration (opt-in):

{
  "sync": {
    "enabled": true,
    "repos": [],
    "interval": 300,
    "adaptiveInterval": true,
    "issueLimit": 500,
    "includeClosedDays": 30,
    "autoStart": false
  }
}

AI keys go in user-level config only (~/.config/tissues/config.json) — never commit them:

{
  "ai": {
    "provider": "anthropic",
    "keys": {
      "anthropic": "sk-ant-...",
      "openai": "sk-..."
    }
  }
}

tissues config

Interactive config wizard or direct KVP access. Values are stored in ~/.config/tissues/config.json.

# Interactive wizard (main menu: repo, AI provider, keys, budgets, templates, safety, routing, backup)
tissues config

# Direct KVP access
tissues config ai.provider                    # get
tissues config ai.provider anthropic          # set
tissues config set safety.maxPerHour 5        # set (subcommand form)
tissues config get safety.maxPerHour          # get (subcommand form)
tissues config list                           # show all resolved config

Hooks

postCreate runs a shell command after every successful issue creation. Three environment variables are injected:

TISSUES_REPO          # owner/repo
TISSUES_ISSUE_NUMBER  # 142
TISSUES_ISSUE_URL     # https://github.com/owner/repo/issues/142

Templates

Built-in Templates

| Key | Description | |---|---| | default | Generic summary + details + additional context | | bug | Steps to reproduce, expected vs actual behavior, environment | | feature | Motivation, proposed solution, alternatives |

Custom Templates

Place .md files in .tissues/templates/ (repo-level) or ~/.config/tissues/templates/ (user-level). Repo templates take priority over user templates, which take priority over built-ins.

Template files support {{variable}} substitution:

| Variable | Value | |---|---| | {{title}} | Issue title | | {{description}} | Issue description — the actual content describing the issue | | {{agent}} | Agent identifier | | {{session}} | Session ID | | {{date}} | ISO date (YYYY-MM-DD) | | {{repo}} | Repository (owner/name) |

Example .tissues/templates/incident.md:

name: Incident Report

## Incident: {{title}}

**Date:** {{date}}
**Reported by:** {{agent}}

## What happened

{{description}}

## Impact

## Timeline

## Resolution

## Prevention

Use it with --template incident.

Attribution

Every issue created by tissues includes a machine-readable HTML comment at the bottom of the body. GitHub renders it as invisible text; it does not appear in the rendered issue.

<!-- tissues-meta
agent: claude-opus-4-6
session: abc123
trigger: cli-create
fingerprint: sha256:3f2a1b...
created_at: 2026-02-19T15:30:00.000Z
created_via: tissues-cli/0.5
-->

The block is used by tissues to:

• Power content fingerprint dedup (prevents re-creating identical issues)
• Track which agent created which issue
• Enable idempotency for agent workflows

You can pass additional fields via --agent, --session, and the programmatic API.

pid is available but opt-in — pass it explicitly via the programmatic API (pid: process.pid). It is omitted by default to avoid leaking process info into public issues.

State Database

tissues stores local state in a SQLite database at:

.tissues/data/tissues.db

No separate SQLite install. The CLI uses better-sqlite3, which compiles SQLite into the Node addon at npm install time. Users do not need to install SQLite on their system. SQLite is a common choice for CLI tool state when you need queryable, structured data (rate limits, dedup history, circuit breaker); simpler config lives in JSON (e.g. conf store).

What it stores:

• fingerprints — SHA-256 hashes of previously created issues (for dedup layer 2)
• rate_events — timestamped creation events (for rate limiting)
• circuit_breaker — circuit state per repo+agent (status, failure count, cooldown)
• idempotency_keys — deterministic keys for agent-driven idempotency
• cached_issues — locally cached GitHub issues for instant dedup and offline context
• cached_labels — locally cached repo labels
• cached_repos — locally cached repo list
• sync_meta — sync cursors and timestamps for incremental fetching

The cache tables are populated by tissues sync (manual or background daemon) and used transparently by create, list, ai, and dedup checks. Run tissues storage to inspect cache state.

The database file can be committed to share dedup history across a team, or added to .gitignore to keep it local. It is created automatically on first use.

License

MIT