ResQ — AI Project Rescue Agent

Scan half-finished, abandoned, or chaotic projects and get a structured rescue plan.

ResQ is a terminal-based AI agent that analyzes your codebase, runs diagnostics, and produces a comprehensive rescue report — telling you what works, what's broken, what to delete, and the shortest path to shipping.

# Scan any project directory
npx resq-ai ~/my-project

# Use a specific model
npx resq-ai ~/my-project --model claude-sonnet-4

# Or install globally
npm install -g resq-ai
resq-ai .

Features

• Parallel Discovery — 39-44 shell commands run locally in parallel to gather project data (file tree, git state, tests, coverage, source code, TODOs, CI config) before any LLM calls
• Adaptive Synthesis — The agent starts with complete context and produces the report in 1-4 turns, with targeted follow-up reads when needed
• Multi-Provider — Works with Anthropic Claude API, OpenAI, Ollama local models, or any OpenAI-compatible endpoint
• Structured Reports — Always produces the same 6-section format: What This Is, What Works, What's Broken, What to Delete, What to Build Next, Shortest Path to Shipping
• Report Persistence — Saves every report as JSON + Markdown to ~/.resq/reports/
• Beautiful Terminal Output — Colorized sections, bordered report box, real-time activity log

Quick Start

1. Install

# Global install
npm install -g resq-ai

# Or use via npx (no install)
npx resq-ai --help

2. Configure (optional)

Create a .env file or set environment variables:

# For Anthropic (cloud)
ANTHROPIC_API_KEY=your_api_key_here

# For OpenAI (cloud)
OPENAI_API_KEY=sk-your-key
RESQ_MODEL=gpt-4o

# For Ollama (local)
OLLAMA_BASE_URL=http://localhost:11434  # or ANTHROPIC_BASE_URL (OLLAMA_BASE_URL takes priority)
ANTHROPIC_API_KEY=ollama
RESQ_MODEL=gemma4:31b-cloud

# Optional behavior
RESQ_MAX_TURNS=40
RESQ_LOG_LEVEL=info
RESQ_SAVE_REPORTS=true

See docs/CONFIGURATION.md for full reference.

3. Run

# Scan current directory
resq-ai

# Scan a specific project
resq-ai ~/my-project

# Use a specific model
resq-ai ~/my-project --model kimi-k2.6:cloud

Architecture

resq/
├── bin/resq.mjs          # CLI entry point (shebang + arg parsing)
├── src/
│   ├── agent.ts           # LLM synthesis + adaptive follow-up
│   ├── cli.ts             # Terminal UI (spinner, colors, activity log)
│   ├── config.ts          # Config management (CLI > env > file > defaults)
│   ├── discovery.ts       # Parallel project discovery (no LLM)
│   ├── logger.ts          # Structured logging
│   ├── retry.ts           # Resilient error handling with backoff
│   └── session-store.ts   # Report persistence (JSON + Markdown)
├── test/                  # CLI smoke tests
│   └── smoke.test.ts
└── vitest.config.ts       # Test configuration (src/**/*.test.ts + test/**/*.test.ts)

How It Works

1. Phase 1 — Discovery: gatherDiscovery() runs 39-44 shell commands in parallel (file tree, git, configs, tests, lint, coverage, source snippets, TODOs, CI). This takes ~3-10 seconds locally.
2. Phase 2 — Synthesis: The full discovery payload is injected into the LLM prompt. The agent produces the structured report in a single turn.
3. Phase 3 — Adaptive Follow-Up: If the agent finds gaps, it uses Read/Grep/Bash tools for targeted deeper inspection (0-3 additional turns).

Result: Reports that used to take 55 LLM turns (~$2.13) now take 1-4 turns (~$0.15) with equal or better depth.

Ollama / Local Models

ResQ works great with local models via Ollama:

# Install Ollama
https://ollama.com/download

# Pull a model
ollama pull gemma4:31b-cloud

# Set config
export ANTHROPIC_BASE_URL=http://localhost:11434
export ANTHROPIC_API_KEY=ollama
export RESQ_MODEL=gemma4:31b-cloud

# Run
resq-ai ~/my-project

See docs/OLLAMA.md for detailed setup.

Configuration Priority

Config values are merged in this order (highest wins):

1. CLI flags (--model)
2. Environment variables (RESQ_MODEL)
3. ~/.resq/config.json
4. Defaults

See docs/CONFIGURATION.md.

Report Output

Every run produces:

• Terminal display — Colorized, bordered report with activity log
• JSON report — ~/.resq/reports/_{timestamp}.json (structured data)
• Markdown report — ~/.resq/reports/_{timestamp}.md (human-readable)

Example report sections:

# RESQ PROJECT RESCUE REPORT

## 1. WHAT THIS PROJECT IS
[Description]

## 2. WHAT WORKS
- [Specific components with evidence]

## 3. WHAT'S BROKEN
- [Exact file paths, line numbers, error counts]

## 4. WHAT TO DELETE
- [Dead code, unused files, build artifacts]

## 5. WHAT TO BUILD NEXT
1. [Concrete step — effort: LOW|MEDIUM|HIGH]
2. [Next step — effort: LOW|MEDIUM|HIGH]

## 6. SHORTEST PATH TO SHIPPING
[Minimal sequence to deploy, tagged with LOW|MEDIUM|HIGH effort]

Development

# Clone
git clone https://github.com/saadiqhorton/ResQ.git
cd ResQ

# Install dependencies
npm install

# Build (required before running — dist/ is gitignored)
npm run build

# Run locally
node bin/resq.mjs ~/my-project

# Run tests
npm test

Requirements

• Node.js 20+ (ESM)
• TypeScript 5.8+
• For Anthropic cloud: Anthropic API key
• For OpenAI cloud: OpenAI API key
• For local: Ollama running on localhost:11434

License

ISC

Acknowledgments

Built with Claude Agent SDK and Anthropic's Claude.