Skip to content
ask-forge

Getting Started

ask-forge is a TypeScript library that lets you programmatically ask questions to any GitHub or GitLab repository. It connects an LLM to a cloned repo with tools for code search, file reading, and git operations, then returns structured answers with source references.

Features

  • Ask questions about any repository — Point it at any public or private repository URL and start asking questions in plain language.
  • Query any point in history — Pin your question to a specific branch, tag, or commit.
  • Configurable — Choose any model and provider supported by pi-ai (OpenRouter, Anthropic, Google, and more). Customize the system prompt, tool iteration limits, and context compaction settings.
  • Sandboxed execution — Run tool execution in an isolated container for exploring untrusted repositories safely.
  • Rich answer metadata — Every response comes with token usage, inference time, and a list of all the sources the model consulted.
  • OpenTelemetry observability — All LLM calls and tool invocations are traced with GenAI semantic conventions.

Requirements

  • Bun (or Node.js >= 18)
  • git, ripgrep, fd
  • An LLM API key (set via environment variable, e.g. OPENROUTER_API_KEY)

Installation

Terminal window
# npm (via JSR)
npx jsr add @nilenso/ask-forge


# Bun
bunx jsr add @nilenso/ask-forge

Quick Start

import { AskForgeClient } from "@nilenso/ask-forge";


const client = new AskForgeClient({
  provider: "openrouter",
  model: "anthropic/claude-sonnet-4-20250514",
});


const session = await client.connect("https://github.com/owner/repo");


const result = await session.ask("What does this repo do?");
console.log(result.response);       // The LLM's answer
console.log(result.toolCalls);      // Tools invoked (rg, fd, read, etc.)
console.log(result.invalidLinks);   // Any invalid links detected


// Every subsequent call to `session.ask()` continues the
// conversation with full context
await session.ask("Tell me more about how the tests are structured");