Skip to content

getting-started.md

Latest commit

 

History

History
124 lines (88 loc) · 3.9 KB

getting-started.md

File metadata and controls

124 lines (88 loc) · 3.9 KB
Raw

Getting started

Español: es/getting-started.md.

This guide takes you from zero to a running yaggo-brain with your IDE connected.

1. Prerequisites

  • Node.js >= 20 and pnpm (the repo pins pnpm@11.9.0; corepack enable pnpm works).
  • Docker Desktop (WSL2 backend recommended on Windows).
  • Git.

2. Install

Option A — one-line installer

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/YaggoSEO/yaggo-brain/main/install.sh | bash

Windows (PowerShell):

Invoke-WebRequest -Uri https://raw.githubusercontent.com/YaggoSEO/yaggo-brain/main/install.ps1 -OutFile install.ps1
notepad install.ps1   # optional: inspect before running
.\install.ps1

The installer clones the repo, runs pnpm install, pnpm db:up, pnpm db:migrate, and pulls the local Ollama models. Flags: --dir=PATH, --no-docker, --no-models, --dev.

Option B — manual

git clone https://github.com/YaggoSEO/yaggo-brain.git
cd yaggo-brain
pnpm install
cp .env.example .env
pnpm db:up
pnpm db:migrate

3. Start the panel

pnpm dev

This terminal stays open on purpose (Ctrl+C to stop). Within ~30s you should see the web, api, and worker lines. Then open:

If a port is busy (EADDRINUSE), stop the other process on :3000/:3333 or a previous pnpm dev.

4. Local models (Ollama)

docker exec yaggo-ollama ollama pull nomic-embed-text
docker exec yaggo-ollama ollama pull qwen2.5:3b
docker exec yaggo-ollama ollama pull qwen2.5-coder:7b

nomic-embed-text powers embeddings; qwen2.5:3b is the default ASK_MODEL; qwen2.5-coder:7b is the coder tier.

5. Create a project and connect a repo

  1. Open the panel and create a project.
  2. Go to the Explorer tab and connect a repository by absolute local path (e.g. C:\path\to\your\repo on Windows) or a Git URL.
  3. Wait for the worker to scan it (or click Re-scan repo). The Graph tab renders the code graph.

Note: the "approve diff → new branch + commit" flow (write agents) requires the connected target to be a git repository.

6. Ask questions (RAG)

  • Add content first: upload a document in Docs or create a page in Wiki so the RAG index has material.
  • Use the Ask panel (or POST /api/projects/:id/ask) to ask about the project. Answers come back with clickable citedIds.

7. Run an agent

  • In the Agents tab, run the read-only architect to get an architecture analysis.
  • Runs appear on the kanban board; failed evals create a proposed lesson.

8. Wire your IDE (MCP)

npx yaggo-brain install --target=cursor   # also: claude-code, windsurf, --all
npx yaggo-brain doctor --json

Then, in your agent, say "Index this project". As you work, hooks stream observations into the Memory tab and session.end produces a session summary + a quality review.

9. Where data shows up

You do Data lands in Panel
Connect + scan a repo file_nodes, code graph Explorer, Graph
Upload docs / edit wiki documents, chunks Docs, Wiki, Ask
Rebuild vectors vector_snapshots Vectors
Ask / classify model_calls Costs
Run agents agent_runs, lessons Agents, Lessons
Use the IDE (MCP) observations, session_summaries Memory
Run evals eval_runs Quality

Troubleshooting

  • pnpm dev seems stuck — it's a persistent process; look for the Ready/listening lines rather than a returned prompt.
  • /ask is weak — add docs/wiki first; retrieval needs content.
  • Vectors empty — ask/ingest first so chunks have embeddings, then rebuild the snapshot.
  • Docker not running — start Docker Desktop, then pnpm db:up && pnpm db:migrate.

See also: Architecture and Deployment.