# RepoPilot

RepoPilot is a Next.js application for exploring uploaded repositories with three connected surfaces:

- `Chat`: an agent chat that can inspect source code and use generated wiki content as context
- `Code`: a repository file browser and editor-focused code viewer
- `Wiki`: generated reverse documentation for the uploaded repository

The current codebase is a web app, not a Python SDK. The old SDK/CLI README was stale and has been replaced.

## What It Does

- Import repositories from:
  - local filesystem path
  - uploaded zip archive
  - remote Git URL
- Persist repository metadata and chat sessions in PostgreSQL
- Run an agent over the repository using `Read`, `Glob`, and `Grep`
- Generate repository wiki pages from scanned Java source code
- Render Mermaid diagrams in chat and wiki with server-side validation/fallback
- Navigate from wiki code references into the Code tab
- Compact long chat history on the client before sending more turns

## Stack

- `Next.js 15`
- `React 19`
- `TypeScript`
- `PostgreSQL`
- `@anthropic-ai/claude-agent-sdk`
- `tree-sitter` + `tree-sitter-java`
- `CodeMirror`
- `Mermaid`

## Main Application Areas

- [src/components/AppShell.tsx](/Users/ThangLT4/Desktop/code/RepoPilot/src/components/AppShell.tsx)
  - top-level shell with `Chat`, `Code`, and `Wiki` tabs
- [src/components/ChatApp.tsx](/Users/ThangLT4/Desktop/code/RepoPilot/src/components/ChatApp.tsx)
  - repository selection, session management, chat view, wiki view
- [src/server/agent.ts](/Users/ThangLT4/Desktop/code/RepoPilot/src/server/agent.ts)
  - server-side agent execution and prompt assembly
- [src/server/wiki-generator.ts](/Users/ThangLT4/Desktop/code/RepoPilot/src/server/wiki-generator.ts)
  - repository wiki generation pipeline
- [src/lib/repopilot/scanner](/Users/ThangLT4/Desktop/code/RepoPilot/src/lib/repopilot/scanner)
  - code scanning and graph extraction
- [src/app/api](/Users/ThangLT4/Desktop/code/RepoPilot/src/app/api)
  - REST endpoints for agent, repositories, files, sessions, and wiki

## Environment Configuration

Configuration is now controlled through environment variables.

Start from [.env.example](/Users/ThangLT4/Desktop/code/RepoPilot/.env.example).

Important variables:

- `LITELLM_PROXY_URL`
- `LLM_MODEL`
- `ANTHROPIC_API_KEY`
- `DATABASE_URL`
- `REPOS_PATH`
- `SOURCE_PATH`
- `REPOSITORY_ZIP_EXTRACT_TIMEOUT_MS`
- `REPOSITORY_GIT_CLONE_TIMEOUT_MS`
- `LLM_HEALTHCHECK_TIMEOUT_MS`
- `AGENT_ALLOWED_TOOLS`
- `AGENT_TIMEOUT_MS`
- `AGENT_MAX_THINKING_TOKENS`
- `AGENT_MAX_TURNS`
- `AGENT_CONVERSATION_SUMMARY_MAX_CHARS`
- `AGENT_CONVERSATION_ASSISTANT_MAX_CHARS`
- `AGENT_CONVERSATION_USER_MAX_CHARS`
- `AGENT_CONVERSATION_HISTORY_MESSAGES`
- `CHAT_COMPACTION_MODEL`
- `CHAT_COMPACTION_MAX_TURNS`
- `WIKI_AGENT_MODEL`
- `WIKI_AGENT_ALLOWED_TOOLS`
- `WIKI_AGENT_MAX_TURNS`
- `NEXT_PUBLIC_AGENT_COMPACTION_THRESHOLD_TOKENS`
- `NEXT_PUBLIC_AGENT_MIN_HISTORY_MESSAGES_FOR_COMPACTION`

## Run With Docker

1. Create a local env file.

```bash
cp .env.example .env
```

2. Adjust values in `.env` if needed.

3. Start the stack.

```bash
docker-compose up -d --build
```

4. Open the app.

```text
http://localhost:3000
```

Services started by Docker:

- `repopilot`: Next.js application
- `postgres`: PostgreSQL database

## First 5 Minutes

1. Start the stack with Docker.

```bash
cp .env.example .env
docker-compose up -d --build
```

2. Open `http://localhost:3000`.

3. Add a repository.
   Use `Add Repository`, then choose one of:
   - local path
   - zip upload
   - Git clone URL

4. Wait for the repository to appear in the sidebar.
   The repository is saved first. Wiki generation starts in the background.

5. Ask a high-value first question in `Chat`.
   Example prompts:
   - `What does this repository do?`
   - `Give me the main modules and how they relate.`
   - `What should a new engineer read first?`

6. Open `Wiki` once generation starts producing pages.
   Use it for:
   - repository overview
   - business/domain context
   - workflow summaries

7. Jump into `Code` when needed.
   Wiki code references and agent answers can guide you to exact files for verification.

## Run Locally Without Docker

Prerequisites:

- Node.js 22+
- PostgreSQL
- access to your configured LLM proxy / Anthropic-compatible endpoint

1. Install dependencies.

```bash
npm ci
```

2. Create `.env` from the example and point `DATABASE_URL` and `LITELLM_PROXY_URL` to working services.

3. Start the dev server.

```bash
npm run dev
```

## Current API Surface

Core endpoints:

- `POST /api/agent`
- `POST /api/agent/compact`
- `GET /api/agent/init`
- `GET /api/health`
- `GET /api/repositories`
- `POST /api/repositories`
- `GET /api/repositories/:id`
- `DELETE /api/repositories/:id`
- `GET /api/repositories/:id/wiki`
- `GET /api/repositories/:id/wiki/manifest`
- `GET /api/repositories/:id/wiki/pages/:pageId`
- `GET /api/repositories/:id/wiki/[...path]`
- `GET /api/repositories/:id/wiki/status/stream`
- `GET /api/files`
- `GET /api/files/read`
- `GET /api/sessions`
- `POST /api/sessions`
- `GET /api/sessions/:id`
- `PUT /api/sessions/:id`
- `DELETE /api/sessions/:id`

## Repository Workflow

1. Add a repository from local path, zip, or Git URL
2. Repo metadata is stored in PostgreSQL
3. Wiki generation starts in the background
4. Chat can inspect the repository immediately
5. Wiki becomes available as generated pages finish
6. Wiki code references can jump into the Code tab

## Development Notes

- Chat history is persisted by session
- Chat uses client-side history compaction before very long conversations
- Mermaid handling is intentionally conservative:
  - invalid diagrams are downgraded instead of aggressively rewritten in the browser
- Wiki generation is currently optimized for Java repositories because the scanner is Java-specific

## Useful Commands

```bash
npm run dev
npm run build
npm run test:wiki-smoke
docker-compose up -d --build
docker-compose down
```

## Current Limitations

- The repository scanner is Java-focused
- Wiki quality depends on scan coverage and agent output quality
- Some wiki flows are still generation-heavy and can be slower on larger repositories
- The app expects a reachable Anthropic-compatible endpoint through the configured proxy