QuackStack 🐥

Your cracked unpaid intern for all things codebase related!

QuackStack is an interactive CLI tool that indexes your codebase using local AI embeddings and lets you ask questions about it conversationally. Perfect for understanding unfamiliar code, onboarding to new projects, or giving your AI coding assistant persistent context.

Live Demo | Documentation | Frontend

To skip docs and use QuackStack seamlessly, use the Onboarding Guide.

Features

• Zero-config - Just run quack in any project directory
• Smart code parsing - Automatically extracts functions and classes
• Interactive REPL - Ask questions conversationally, stays open until Ctrl+C
• 100% Local embeddings - No API calls for vector generation, your code stays private
• AI-powered answers - Uses OpenAI, Claude, Gemini, DeepSeek, Grok, Mistral, Prime Intellect, or Moonshot AI for conversational responses
• Git history integration - Track authorship, commit history, and code ownership
• Agent-attributed blame - Tell human commits from AI-agent commits (Claude Code, Cursor, Windsurf, Copilot, ...), with a confidence level, and resolve any line back to the agent that wrote it
• Universal AI tool support - Auto-generate context for Cursor, Windsurf, Cline, Continue, and Aider
• Local database - Your code stays on your infrastructure
• Multi-language - Supports JS/TS, Python, Go, Rust, Java, C/C++, C#, Ruby, PHP, Swift, Kotlin, and more

Installation

Global Install (Recommended)

npm install -g quackstack
# or
pnpm add -g quackstack

Local Development

git clone https://github.com/woustachemax/quackstack.git
cd quackstack
pnpm install
pnpm build

Setup

1. Create .env in your project root

QUACKSTACK_DATABASE_URL=postgresql://user:pass@host:port/dbname

QUACKSTACK_OPENAI_KEY=sk-...
QUACKSTACK_ANTHROPIC_KEY=sk-ant-...
QUACKSTACK_GEMINI_KEY=AIza...
QUACKSTACK_GROK_KEY=xai-...
QUACKSTACK_DEEPSEEK_KEY=sk-...
QUACKSTACK_MISTRAL_KEY=...
QUACKSTACK_PRIMEINTELLECT_KEY=...
QUACKSTACK_MOONSHOT_KEY=sk-...

2. Initialize database

npx prisma generate
npx prisma db push

Usage

Interactive Mode (Default)

quack
# Ask questions about your codebase
# Press Ctrl+C to exit

Generate Context for ALL AI Coding Tools

quack --context

# Creates context files for:
# - Cursor (.cursorrules)
# - Windsurf (.windsurfrules)
# - Cline (.clinerules)
# - Continue (.continue/context.md)
# - Aider (.aider.conf.yml)

Generate AGENTS.md Configuration

quack --agent

# Creates agent.md with codebase context
# for AI agent frameworks

Generate README

quack --readme

# Auto-generates README.md from your codebase

Generate Documentation

quack --docs

# Creates CODEBASE.md with architecture overview

Watch Mode (Auto-update Context)

quack --watch

# Watches for file changes
# Auto-regenerates context files

Git History Commands

# View contributor statistics
quack authors

# Split contributor stats by human vs AI agent
quack authors --agents

# Resolve a line back to the commit, author, and agent that last changed it
quack blame <file>:<line>
quack blame src/lib/ai-provider.ts:130

# View recently modified files
quack recent
quack recent --days 30

# View repository information
quack git-info

Agent-Attributed Blame

QuackStack reads the Co-Authored-By: trailers and commit-message patterns that AI coding tools leave behind, so it can tell which commits were written by an agent and which one. It never adds an LLM call for this - it's all git history plus the AST index.

Attribution carries a confidence level:

| Confidence | Signal | |------------|--------| | high | A known agent's Co-Authored-By: trailer (Claude Code, Cursor, Windsurf, GitHub Copilot, Devin) | | medium | A recognizable agent commit-message pattern (e.g. Aider) | | low | A generic bot/agent trailer, or a commit-cadence + diff-size fingerprint with no explicit signal | | human | No agent signal |

$ quack authors --agents

🤖 Agent vs Human Ownership

Claude Code  1 commit, 4 files touched
   active 2026-07-11 → 2026-07-11
   confidence: high 1 / medium 0 / low 0

Suspected (unattributed)  5 commits, 24 files touched
   active 2025-10-01 → 2026-01-11
   confidence: high 0 / medium 0 / low 5

Humans  71 commits, 31 files touched
   active 2025-10-02 → 2026-08-26

6/77 commits (8%) attributed to agents

$ quack blame src/lib/ai-provider.ts:130

src/lib/ai-provider.ts:130   (in AIClient)

commit  b804f6f  new models, add Prime Intellect provider
author  woustachemax <[email protected]>
date    2026-07-11
agent   Claude Code   confidence: high
session (none)

quack blame works without indexing (it classifies the commit message on the fly); run quack --reindex first to also get the cadence-based low-confidence signals and the enclosing function name. Function resolution uses the AST index, which is precise for JS/TS and coarser for other languages.

Force Reindex

quack --reindex

# Clears old index and re-scans entire codebase

List Available AI Models

quack --list-models

# Shows all configured providers and available models

Example Session

$ quack
…………………………………………………………………………………………………………………………………………………………………………

   ██████╗ ██╗   ██╗ █████╗  ██████╗██╗  ██╗███████╗████████╗ █████╗  ██████╗██╗  ██╗
   ██╔═══██╗██║   ██║██╔══██╗██╔════╝██║ ██╔╝██╔════╝╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝
   ██║   ██║██║   ██║███████║██║     █████╔╝ ███████╗   ██║   ███████║██║     █████╔╝ 
   ██║▄▄██║██║   ██║██╔══██║██║     ██╔═██╗ ╚════██║   ██║   ██╔══██║██║     ██╔═██╗ 
   ╚██████╔╝╚██████╔╝██║  ██║╚██████╗██║  ██╗███████║   ██║   ██║  ██║╚██████╗██║  ██╗
    ╚══▀▀═╝  ╚═════╝ ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝

…………………………………………………………………………………………………………………………………………………………………………
 ✨ Let's get started.

Using: OpenAI - gpt-5.3-codex
💡 Tip: Type '/help' for commands or 'quack --list-models' to see all options
Press Ctrl+C to exit

Indexing your codebase...
Indexing complete

quack > how does the search function work?

The search function uses local embeddings to convert your query into a vector,
compares it against stored code embeddings using cosine similarity, ranks results,
and feeds the top matches to the AI for a conversational answer.

Implementation is in src/commands/search.ts

Want more details? (y/n) > n

quack > who wrote the authentication system?

The authentication system was primarily written by Siddharth Thakkar, with the
main implementation in app/api/auth/[...nextauth]/options.ts (last modified 187 days ago).

quack > ^C
Happy coding!

How It Works

1. Scanning - Finds all code files (ignoring node_modules, .git, etc.)
2. Parsing - Uses AST parsing to extract functions/classes
3. Chunking - Breaks code into logical chunks
4. Local Embedding - Generates vector embeddings locally (no API calls)
5. Git Enrichment - Extracts commit history, authorship, ownership data, and per-commit agent attribution (mapping diff hunks to the functions they changed)
6. Storage - Saves to your PostgreSQL database
7. Search - Semantic search using cosine similarity + AI-powered conversational answers

Commands Reference

| Command | Description | |---------|-------------| | quack | Start interactive REPL | | quack --context | Generate context files for all AI coding tools | | quack --agent | Generate AGENTS.md configuration | | quack --readme | Generate README.md from codebase | | quack --docs | Generate CODEBASE.md documentation | | quack --watch | Watch mode - auto-update context on file changes | | quack --reindex | Force reindex the entire codebase | | quack --list-models | Show available AI providers and models | | quack authors | View contributor statistics | | quack authors --agents | Split contributor stats by human vs AI agent | | quack blame <file>:<line> | Resolve a line to its commit, author, and agent | | quack recent [--days N] | View recently modified files | | quack git-info | View repository information |

Supported AI Providers

| Provider | Used For | Cost | Privacy | Setup | |----------|----------|------|---------|-------| | Local | Embeddings | FREE | 100% Private | Built-in | | OpenAI | Chat answers | $$ | Query only | Get key | | Anthropic | Chat answers | $$$ | Query only | Get key | | Gemini | Chat answers | FREE | Query only | Get key | | xAI Grok | Chat answers | $$ | Query only | Get key | | DeepSeek | Chat answers | $ | Query only | Get key | | Mistral | Chat answers | $$ | Query only | Get key | | Prime Intellect | Chat answers | $ | Query only | Get key | | Moonshot AI | Chat answers | $$ | Query only | Get key |

Privacy Note: QuackStack generates embeddings locally on your machine. Only your natural language queries and retrieved code context are sent to the AI provider for generating conversational answers. Your entire codebase is never sent to any API.

Database Schema

model codeSnippet {
  id                 Int       @id @default(autoincrement())
  content            String
  embedding          Json
  filePath           String
  projectName        String
  language           String?
  functionName       String?
  lineStart          Int?
  lineEnd            Int?
  
  lastCommitHash     String?
  lastCommitAuthor   String?
  lastCommitEmail    String?
  lastCommitDate     DateTime?
  lastCommitMessage  String?
  totalCommits       Int?       @default(0)
  primaryAuthor      String?
  primaryAuthorEmail String?
  fileOwnerCommits   Int?       @default(0)
  
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([projectName])
  @@index([lastCommitDate])
  @@index([primaryAuthor])
}

model gitAuthor {
  id             Int       @id @default(autoincrement())
  projectName    String
  author         String
  email          String
  totalCommits   Int       @default(0)
  linesAdded     Int       @default(0)
  linesRemoved   Int       @default(0)
  recentActivity DateTime?
  filesOwned     String[]
  
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@unique([projectName, email])
  @@index([projectName])
  @@index([recentActivity])
}

model commit {
  hash            String   @id
  projectName     String
  authorName      String
  authorEmail     String
  agentName       String?
  agentConfidence String   @default("human")
  sessionId       String?
  message         String
  authoredAt      DateTime
  createdAt       DateTime @default(now())

  files commitFile[]

  @@index([projectName])
  @@index([projectName, agentName])
  @@index([authoredAt])
}

model commitFile {
  id               Int    @id @default(autoincrement())
  commitHash       String
  projectName      String
  filePath         String
  functionsTouched Json

  commit commit @relation(fields: [commitHash], references: [hash], onDelete: Cascade)

  @@unique([commitHash, filePath])
  @@index([projectName, filePath])
}

Supported Languages

JavaScript, TypeScript, Python, Go, Rust, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, R, Vue, Svelte

Use Cases

• Context switching - Quickly understand projects you haven't touched in months
• Onboarding - New team members can ask questions instead of reading docs
• Code archaeology - Find implementations without grepping
• Code ownership - Identify who wrote and maintains specific parts of the codebase
• Agent accountability - See how much of the codebase was written by AI agents, and trace a bug back to the agent and commit that shipped it
• AI coding assistants - Give Cursor/Windsurf/Cline/Continue/Aider persistent codebase context
• Documentation - Auto-generate explanations of how things work
• Privacy-focused - All embeddings generated locally, no code sent to embedding APIs

Development

git clone https://github.com/woustachemax/quackstack.git
cd quackstack
pnpm install
pnpm build

# Run locally
node dist/cli.cjs

Contributing

Contributions welcome! Feel free to:

• Report bugs via GitHub Issues
• Submit feature requests
• Open pull requests

License

MIT

Pro Tips

Privacy First: Embeddings are generated locally - your code never leaves your machine during indexing.

Gemini Free Tier: Start with Google Gemini for chat responses - it's free and works great for most use cases.

Universal Context: Run quack --context once to generate context files for all major AI coding tools at once.

Background Watcher: Run quack --watch & in the background to keep context always fresh across all your AI tools.

Multiple Projects: Each project gets its own namespace in the database. Just run quack in different directories.

Large Codebases: First index might take a few minutes. After that, only changed files are re-indexed.

Git Integration: QuackStack automatically enriches your codebase with git history - no setup required. Track authorship, view recent changes, and understand code ownership.

Agent Attribution: Run quack authors --agents to see the human/agent split of your history, or quack blame <file>:<line> to find out which agent last touched a line. Works on any repo whose agent commits carry the usual Co-Authored-By: trailers.

No Vendor Lock-in: Unlike other tools, QuackStack works with Cursor, Windsurf, Cline, Continue, and Aider - choose your favorite!