Chat Assistant
The Chat Assistant is a conversational interface for exploring your engineering data. Instead of navigating dashboards and filtering tables, you ask questions in plain language and get answers grounded in your company's actual commit, PR, and team data.
Overview
The assistant runs as an LLM-powered chat with access to structured tools that query ShipLens data. It doesn't hallucinate metrics — every answer is backed by a tool call that hits the database.
Route: /c/:slug/assistant
How It Works
Tool-Based Architecture
The assistant is not a generic chatbot. It's a Claude Sonnet instance equipped with a set of tools that mirror the ShipLens data model:
| Tool | What It Queries |
|---|---|
get_contributor_stats | Commit counts, scores, work patterns for a contributor |
get_project_stats | Project-level metrics, active contributors, domain map |
get_squad_stats | Squad velocity, cycle time, contributor breakdown |
compare_periods | Week-over-week or month-over-month metric comparisons |
search_commits | Find commits by type, author, project, date range, or keyword |
get_alerts | Fetch unresolved alerts for a contributor or team |
get_pr_metrics | PR cycle time, size distribution, review stats |
When you ask a question, the LLM decides which tools to call, executes them, and synthesizes the results into a natural language response. Complex questions may trigger multiple tool calls in sequence.
Example Conversations
Simple lookup:
You: How many commits did Sarah ship last week?
Assistant: Sarah made 23 commits last week across 2 projects (API and Dashboard). Her average score was 7.2, up from 6.8 the previous week. 18 were features, 3 were fixes, and 2 were refactors.
Comparative analysis:
You: Compare the Backend and Platform squads this month.
Assistant: Backend shipped 142 commits (avg score 6.9) vs Platform's 98 commits (avg score 7.4). Platform has higher quality per commit but lower volume. Backend's fix ratio is 34% — worth watching if it continues trending up. Platform's cycle time is 1.2 days vs Backend's 2.8 days.
Trend investigation:
You: Why did velocity drop on the Payments project?
Assistant: Payments velocity dropped 40% this week. Two factors: Alex was on PTO (typically 30% of the squad's output), and the remaining contributors spent significant time on PR reviews for the auth migration — review comment volume was 3x normal.
Thread-Based Conversations
Conversations are persisted in the chat_threads table, allowing you to:
- Return to a previous conversation and continue it
- Reference earlier context ("What about the other squad I asked about?")
- Keep separate threads for different lines of inquiry
Each thread stores:
| Field | Description |
|---|---|
id | Unique thread identifier |
company_id | Scoped to the current company |
title | Auto-generated from the first message |
messages | Ordered list of user and assistant messages |
created_at | When the thread was started |
updated_at | Last activity timestamp |
What You Can Ask
The assistant handles four broad categories of questions:
Contributor Performance
- Individual commit stats, scores, and trends
- Work pattern analysis (session depth, focus areas)
- Comparison between contributors (with appropriate context)
- Alert and gaming flag history
Project Status
- Active contributors and their recent output
- Domain coverage and ownership
- Commit type distribution and quality signals
- Tech debt trends
Team Comparisons
- Squad-level velocity and quality metrics
- Cross-team cycle time and review patterns
- Headcount-normalized comparisons
Trend Analysis
- Week-over-week and month-over-month changes
- Anomaly investigation ("why did X change?")
- Forecasting based on historical patterns
Cost
Each assistant interaction costs approximately:
| Component | Typical Cost |
|---|---|
| Input tokens (question + context + tool results) | ~1,000–5,000 tokens |
| Output tokens (response) | ~200–1,000 tokens |
| Per question | $0.003–0.01 |
Multi-turn conversations accumulate context, so later messages in a long thread cost more due to conversation history.
TIP
The assistant is scoped to your company's data. It cannot access data from other companies, and it cannot modify anything — all tools are read-only queries.