Client Helper - An AI agent that lets non-technical clients ask honest questions about the software their vendors are building — and get answers grounded in actual code, not claims.

Client-Helper.md

Client Helper

An AI agent that lets non-technical clients ask honest questions about the software their vendors are building — and get answers grounded in actual code, not claims.

Built with LangGraph, LangChain, Ollama, and Gradio. Runs fully locally — no data leaves the machine.

---

DM for Repo Access: https://github.com/itskgore/client-helper

---

The Problem

Clients paying vendors to build software have no way to verify progress. "It's mostly done" means nothing without a way to inspect the codebase. This tool bridges that gap.

---

Architecture

Every message flows through a LangGraph StateGraph and is routed to the right agent automatically.

User Message
     │
     ▼
┌─────────────┐
│  Classifier │  ── Pydantic structured output → intent: chat | knowledge | code | none
└─────────────┘
     │
     ├──► Chat Agent     ── General Q&A, architecture advice, roadmap ideas
     │         │
     │    [chat_tools]   ── Tool loop until response is complete
     │
     ├──► RAG Agent      ── Codebase Q&A grounded in live repo access
     │         │
     │    [rag_tools]    ── Tool loop: search, read, git history
     │
     └──► Code Agent     ── (In progress) Diff generation + PR creation

Session memory is persisted per thread_id using LangGraph's InMemorySaver, so context carries across turns.

---

Agents

Classifier

Routes every message to one of four intents using structured JSON output via Pydantic. No wasted context, no wrong agent loaded.

Intent	Routes To	When
chat	Chat Agent	General conversation, advice, brainstorming
knowledge	RAG Agent	Questions about the codebase
code	Code Agent	Requests to modify or generate code
none	Chat Agent	Unrecognised or off-topic

RAG Agent (knowledge)

Acts as a Senior Software Architect with live read access to the vendor's repository. Before every query it auto-syncs the repo if the last sync was more than 5 minutes ago.

Available tools:

Tool	Description
sync_latest_code	Pull latest changes from the configured branch
check_for_updates	Compare local vs remote commit hash
get_recent_changes	Show last N commits with author, date, message
get_project_tree	Walk the directory tree (ignores build artifacts)
search_project_files	Find files by name keyword
search_code	Search source files for a keyword across .dart, .py, .ts, .js, .kt, .java
get_file_content	Read a file with line numbers, supports offset and line limit

The agent searches before reading and reads only what it needs. If something isn't in the codebase, it says so.

Chat Agent (chat)

Thinks like a CTO reviewing a product. Has access to the same repo tools so recommendations are grounded in actual code. Covers:

• Architecture analysis
• Technical debt identification
• Security and scalability risks
• Feature and roadmap suggestions
• Best practice comparisons

Code Agent (code) — In Progress

Planned: full agentic loop with diff generation and pull request creation. The client will be able to flag an issue (wrong colour, broken layout, missing label) and the agent will generate a fix as a PR for the vendor to review and merge.

---

Project Structure

client-helper/
├── app/
│   ├── main.py                        # Entrypoint
│   ├── ui.py                          # Gradio UI
│   ├── config.py                      # LLM initialisation
│   ├── graph/
│   │   ├── builder.py                 # LangGraph StateGraph definition
│   │   └── state.py                   # Shared state (messages + intent)
│   ├── agents/
│   │   ├── classifier.py              # Intent classifier
│   │   ├── chat.py                    # Chat agent
│   │   ├── rag.py                     # RAG agent
│   │   └── code.py                    # Code agent (stub)
│   ├── prompts/
│   │   ├── classifier_prompt.py       # Classifier system prompt
│   │   ├── knowledge_base.py          # RAG agent system prompt
│   │   └── chat_knowledge_base.py     # Chat agent system prompt
│   └── tools/
│       └── rag_tools.py               # All repo access tools + auto-sync
├── pyproject.toml
└── .env

---

Setup

Prerequisites

• Python 3.12+
• uv (recommended) or pip
• Ollama running locally with gemma4:31b-cloud pulled

Install

uv sync
# or
pip install -e .

Configure

1. Point the agent at the vendor's repo.

Open app/tools/rag_tools.py and update:

BRANCH = "your-branch-name"           # Branch to track
PROJECT_ROOT = "/path/to/vendor/repo" # Absolute path to the local clone

2. Set your environment variables.

Create a .env file in the project root:

# Required if using OpenAI instead of Ollama
OPENAI_API_KEY=sk-...

# Optional: Tavily for web search tools
TAVILY_API_KEY=tvly-...

3. Switch the LLM if needed.

app/config.py defaults to Ollama:

llm = init_chat_model(model="ollama:gemma4:31b-cloud")

To use OpenAI:

llm = init_chat_model(model="openai:gpt-4o")

---

Run

cd app
python ui.py

Open http://localhost:7860.

---

How the UI Works

• Session panel — each conversation gets a unique thread_id for isolated memory. Click + New Conversation to start fresh.
• Last Intent badge — shows which agent handled the last message (Chat, Knowledge, Code).
• Agents panel — quick reference for what each agent does.

---

Roadmap

• Classifier with structured intent routing
• RAG agent with live repo access and auto-sync
• Chat agent with CTO-style advisory prompts
• Gradio UI with session management
• Code agent: diff generation and pull request creation
• Configurable PROJECT_ROOT and BRANCH via UI or .env
• Multi-repo support
• SaaS layer: connect any GitHub repo, hosted watchdog running 24/7

---

Tech Stack

• LangGraph — agent graph and state management
• LangChain — LLM abstraction and tool binding
• Ollama — local LLM inference (no data leaves the machine)
• Gradio — web UI
• Pydantic — structured classifier output
• uv — dependency management