CodeChain

A self-hosted watcher that turns other repositories' best ideas into improvements for your code.

Agents watch. You improve.

Why? · Features · Quick Start · Usage · Configuration · Project Layout · Contributing

---

Why?

You have a project you want to improve — and a feed of excellent open-source repos moving every day. Manually reading commits, PRs, and refactors doesn't scale, and insights buried in your reading list never reach your code.

CodeChain watches the repositories you pick, analyzes every change with an AI agent, and files concrete improvement suggestions for your target project — drafted, then automatically reviewed before you ever see them.

┌─────────────────┐   new changes   ┌──────────────────────┐  suggestions  ┌────────────────┐
│  watched repos  │ ──────────────▶ │  ReAct agent         │ ────────────▶ │  target repo   │
│  (open source)  │                 │  draft → review      │               │  (yours)       │
└─────────────────┘                 └──────────────────────┘               └────────────────┘
                                             │
                                             ▼
                                       👤 you (web UI)

Features

• Two-stage pipeline — every analysis produces a draft, then an automatic review pass (independent sessions per repository) before anything reaches you.
• ReAct agent with real tools — code search, git inspection, memory, and report tools. Grounded analysis, not prompt-summarized diffs.
• Semantic code index — the target repo is chunked and embedded with pgvector, so suggestions reference actual code.
• Agent memory — per-watched-repo memory accumulates across runs; the agent doesn't relearn the same repo every hour.
• Multi-provider — Gitea, GitLab, and GitHub. Hourly auto-polling plus a manual "run analysis" button per watched repo.
• Live UI — Vue 3 + Pinia dashboard with WebSocket session streaming; installable PWA.
• Bring your own LLM — any OpenAI-compatible endpoint (llama.cpp, Ollama, …). Your code never leaves your machine.
• One docker compose up — FastAPI + PostgreSQL + Nginx, fully self-hosted.

Quick Start

cp .env.example .env
# edit .env → point LLM_BASE_URL at your llama.cpp / Ollama endpoint
docker compose up -d --build

Open http://localhost:12000 — done.

The API lives at http://localhost:12001/api, PostgreSQL at localhost:12010.

Usage

1. Add your Git server (Gitea, GitLab, GitHub) on the Settings page.
2. Create a project — pick the target repository you want improved.
3. Add watched repositories — register open-source repos worth learning from.
4. Hit Run analysis on a watched repo for an on-demand pass, or let the hourly scheduler do it. Suggestions land on the project.

Configuration

Everything is env-driven (.env):

Variable	Default	Purpose
LLM_BASE_URL	http://localhost:8080/v1	OpenAI-compatible API endpoint
LLM_MODEL	default	model name
LLM_CONTEXT_SIZE	32768	model context size
LLM_MAX_CONCURRENT	1	max concurrent LLM requests
DATABASE_URL	(Docker-internal)	PostgreSQL connection string

Project Layout

backend/app/agent/       # ReAct agent: runner, prompt builder, tools (code search, git, memory, report)
backend/app/services/    # LLM adapter, change detection, code indexer, memory, workspaces
backend/app/scheduler/   # APScheduler jobs (hourly polling)
backend/app/api/         # FastAPI routers + WebSocket sessions
backend/alembic/         # DB migrations
frontend/src/            # Vue 3 + Pinia UI (projects, sessions, monitoring, settings)
nginx/                   # reverse proxy (UI :12000, API :12001)

Contributing

Issues and pull requests are welcome.

License

MIT © ByungHyun21