Skip to content

Commit 33ad544

Browse files
prosdevprosdev
committed
docs: add Nextra v4 documentation website
- Set up Nextra v4 with Next.js 15 and nextra-theme-docs - Add landing page with feature overview - Add installation and quickstart guides - Document all 6 MCP tools (dev_search, dev_plan, dev_explore, dev_gh, dev_status, dev_health) - Add architecture documentation - Configure Vercel Analytics integration - Use plain markdown (no custom components) for RSC compatibility Ready for Vercel deployment at /website
1 parent 4a25d84 commit 33ad544

25 files changed

+8993
-0
lines changed

‎website/.gitignore‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Dependencies
2+
node_modules/
3+
.pnpm-store/
4+
5+
# Next.js
6+
.next/
7+
out/
8+
9+
# Build
10+
dist/
11+
12+
# Debug
13+
npm-debug.log*
14+
yarn-debug.log*
15+
yarn-error.log*
16+
17+
# Local env
18+
.env*.local
19+
20+
# Vercel
21+
.vercel
22+
23+
# TypeScript
24+
*.tsbuildinfo
25+
next-env.d.ts
26+

‎website/app/[[...mdxPath]]/page.tsx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import { generateStaticParamsFor, importPage } from 'nextra/pages';
2+
import { useMDXComponents } from 'nextra-theme-docs';
3+
4+
export const generateStaticParams = generateStaticParamsFor('mdxPath');
5+
6+
export async function generateMetadata(props: { params: Promise<{ mdxPath?: string[] }> }) {
7+
const params = await props.params;
8+
const { metadata } = await importPage(params.mdxPath);
9+
return metadata;
10+
}
11+
12+
export default async function Page(props: { params: Promise<{ mdxPath?: string[] }> }) {
13+
const params = await props.params;
14+
const result = await importPage(params.mdxPath);
15+
const { default: MDXContent, ...rest } = result;
16+
const { wrapper: Wrapper } = useMDXComponents();
17+
18+
return (
19+
<Wrapper {...rest}>
20+
<MDXContent />
21+
</Wrapper>
22+
);
23+
}

‎website/app/globals.css‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
:root {
2+
--nextra-primary-hue: 212deg;
3+
--nextra-primary-saturation: 100%;
4+
}
5+

‎website/app/layout.tsx‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import { Analytics } from '@vercel/analytics/react';
2+
import { Head } from 'nextra/components';
3+
import { getPageMap } from 'nextra/page-map';
4+
import { Footer, Layout, Navbar } from 'nextra-theme-docs';
5+
import 'nextra-theme-docs/style.css';
6+
import './globals.css';
7+
8+
export const metadata = {
9+
title: {
10+
default: 'dev-agent',
11+
template: '%s | dev-agent',
12+
},
13+
description: 'AI-native code intelligence for Cursor and Claude Code',
14+
};
15+
16+
const logo = (
17+
<span style={{ fontWeight: 'bold' }}>
18+
<span style={{ color: '#3b82f6' }}>dev</span>-agent
19+
</span>
20+
);
21+
22+
export default async function RootLayout({ children }: { children: React.ReactNode }) {
23+
const pageMap = await getPageMap();
24+
25+
return (
26+
<html lang="en" dir="ltr" suppressHydrationWarning>
27+
<Head faviconGlyph="🤖" />
28+
<body>
29+
<Layout
30+
pageMap={pageMap}
31+
docsRepositoryBase="https://github.com/lytics/dev-agent/tree/main/website/content"
32+
editLink="Edit this page on GitHub"
33+
sidebar={{ defaultMenuCollapseLevel: 1 }}
34+
navbar={<Navbar logo={logo} projectLink="https://github.com/lytics/dev-agent" />}
35+
footer={<Footer>MIT {new Date().getFullYear()} © Contentstack</Footer>}
36+
>
37+
{children}
38+
</Layout>
39+
<Analytics />
40+
</body>
41+
</html>
42+
);
43+
}

‎website/content/_meta.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
export default {
2+
index: 'Home',
3+
docs: 'Documentation',
4+
};

‎website/content/docs/_meta.js‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
export default {
2+
index: 'Introduction',
3+
install: 'Installation',
4+
quickstart: 'Quickstart',
5+
'---tools': {
6+
type: 'separator',
7+
title: 'MCP Tools',
8+
},
9+
tools: 'Tools Reference',
10+
'---more': {
11+
type: 'separator',
12+
title: 'Learn More',
13+
},
14+
architecture: 'Architecture',
15+
};

‎website/content/docs/architecture.mdx‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Architecture
2+
3+
dev-agent is built as a TypeScript monorepo with specialized packages for different concerns.
4+
5+
## System Overview
6+
7+
```
8+
┌─────────────────────────────────────────────────────────────────────┐
9+
│ AI Tools │
10+
│ (Cursor / Claude Code / VS Code) │
11+
└─────────────────────────┬───────────────────────────────────────────┘
12+
│ Model Context Protocol (MCP)
13+
┌─────────────────────────▼───────────────────────────────────────────┐
14+
│ MCP Server │
15+
│ ┌─────────────────────────────────────────────────────────────┐ │
16+
│ │ Adapter Registry │ │
17+
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
18+
│ │ │ Search │ │ Plan │ │ Explore │ │ GitHub │ ... │ │
19+
│ │ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ │ │
20+
│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │
21+
│ └───────┼────────────┼────────────┼────────────┼───────────────┘ │
22+
│ │ │ │ │ │
23+
│ ┌───────▼────────────▼────────────▼────────────▼───────────────┐ │
24+
│ │ Subagent Coordinator │ │
25+
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
26+
│ │ │ Planner │ │ Explorer │ │ PR Agent │ │ │
27+
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
28+
│ └──────────────────────────────────────────────────────────────┘ │
29+
└─────────────────────────┬───────────────────────────────────────────┘
30+
│
31+
┌─────────────────────────▼───────────────────────────────────────────┐
32+
│ Core │
33+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
34+
│ │ Scanner │ │ Indexer │ │ GitHub │ │
35+
│ │ (AST Parse) │ │ (Embeddings)│ │ Integration │ │
36+
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
37+
│ │ │ │ │
38+
│ ┌──────▼─────────────────▼─────────────────▼───────────────────┐ │
39+
│ │ Vector Storage │ │
40+
│ │ (LanceDB) │ │
41+
│ └──────────────────────────────────────────────────────────────┘ │
42+
└─────────────────────────────────────────────────────────────────────┘
43+
```
44+
45+
## Packages
46+
47+
### @lytics/dev-agent-core
48+
49+
The foundation layer providing:
50+
51+
- **Scanner** — Multi-language AST parsing using TypeScript Compiler API and ts-morph
52+
- **Indexer** — Converts code components to vector embeddings
53+
- **Vector Storage** — LanceDB for fast similarity search
54+
- **GitHub Integration** — Fetches and indexes issues/PRs via GitHub CLI
55+
56+
### @lytics/dev-agent-cli
57+
58+
Command-line interface:
59+
60+
```bash
61+
dev index . # Index repository
62+
dev mcp install # Install MCP integration
63+
dev gh index # Index GitHub issues/PRs
64+
dev status # Check indexing status
65+
```
66+
67+
### @lytics/dev-agent-mcp
68+
69+
MCP server with tool adapters:
70+
71+
- **AdapterRegistry** — Manages tool registration and execution
72+
- **Built-in Adapters** — Search, Plan, Explore, GitHub, Status, Health
73+
- **Rate Limiting** — Token bucket algorithm (100 req burst)
74+
- **Retry Logic** — Exponential backoff with jitter
75+
76+
### @lytics/dev-agent-subagents
77+
78+
Specialized AI agents:
79+
80+
- **PlannerAgent** — Generates implementation plans from issues
81+
- **ExplorerAgent** — Code pattern analysis and relationship mapping
82+
- **PRAgent** — PR management and review assistance
83+
- **Coordinator** — Routes tasks to appropriate agents
84+
85+
### @lytics/kero
86+
87+
Centralized logging:
88+
89+
- Multiple log levels (debug, info, warn, error)
90+
- Console and file transports
91+
- JSON and pretty formatters
92+
- Structured metadata
93+
94+
## Key Technologies
95+
96+
| Component | Technology | Purpose |
97+
|-----------|------------|---------|
98+
| Language | TypeScript (strict) | Type safety |
99+
| Build | Turborepo | Monorepo orchestration |
100+
| Testing | Vitest | 1100+ tests |
101+
| Linting | Biome | Fast linting/formatting |
102+
| Vector DB | LanceDB | Embedded vector storage |
103+
| Embeddings | @xenova/transformers | Local ML inference |
104+
| Model | all-MiniLM-L6-v2 | Sentence embeddings |
105+
| Protocol | MCP | AI tool integration |
106+
107+
## Data Flow
108+
109+
### Indexing Flow
110+
111+
```
112+
Source Code
113+
│
114+
▼
115+
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
116+
│ Glob │ ──▶ │ Parse │ ──▶ │ Extract │ ──▶ │ Embed │
117+
│ Files │ │ AST │ │Components│ │ Vectors │
118+
└──────────┘ └──────────┘ └──────────┘ └──────────┘
119+
│
120+
▼
121+
┌──────────┐
122+
│ LanceDB │
123+
└──────────┘
124+
```
125+
126+
### Query Flow
127+
128+
```
129+
User Query: "Where is auth handled?"
130+
│
131+
▼
132+
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
133+
│ Embed │ ──▶ │ Vector │ ──▶ │ Rank │ ──▶ │ Format │
134+
│ Query │ │ Search │ │ Results │ │ Output │
135+
└──────────┘ └──────────┘ └──────────┘ └──────────┘
136+
```
137+
138+
## Storage
139+
140+
All data is stored locally in `~/.dev-agent/`:
141+
142+
```
143+
~/.dev-agent/
144+
├── indexes/
145+
│ └── <repo-hash>/
146+
│ ├── code.lance/ # Code vector index
147+
│ └── metadata.json # Index metadata
148+
├── github/
149+
│ └── <repo-hash>/
150+
│ ├── issues.lance/ # Issues vector index
151+
│ └── prs.lance/ # PRs vector index
152+
└── config.json # Global config (optional)
153+
```
154+
155+
## Security
156+
157+
- **100% Local** — No data sent to external services
158+
- **No Cloud** — All processing happens on your machine
159+
- **Embeddings** — Generated locally via @xenova/transformers
160+
- **GitHub Data** — Fetched via authenticated GitHub CLI
161+

‎website/content/docs/index.mdx‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Introduction
2+
3+
**dev-agent** is a local-first repository context provider for AI tools. It gives AI assistants like Cursor and Claude Code deep understanding of your codebase through semantic search, code analysis, and GitHub integration.
4+
5+
## The Problem
6+
7+
AI coding assistants are powerful, but they struggle with context:
8+
9+
- They can't search your codebase semantically
10+
- They don't understand relationships between files
11+
- They lack awareness of your GitHub issues and PRs
12+
- They hallucinate about code that doesn't exist
13+
14+
## The Solution
15+
16+
dev-agent solves this by:
17+
18+
1. **Indexing your codebase** with local embeddings (all-MiniLM-L6-v2)
19+
2. **Exposing semantic search** via the Model Context Protocol (MCP)
20+
3. **Integrating with GitHub** to understand your project's history
21+
4. **Providing specialized tools** for planning, exploration, and more
22+
23+
## Key Features
24+
25+
| Feature | Description |
26+
|---------|-------------|
27+
| **Semantic Search** | Find code by meaning, not keywords |
28+
| **AST Analysis** | Type-aware understanding of your code |
29+
| **GitHub Integration** | Search issues and PRs semantically |
30+
| **Local-First** | Your code never leaves your machine |
31+
| **MCP Native** | Works with Cursor, Claude Code, VS Code |
32+
33+
## Architecture Overview
34+
35+
dev-agent is built as a monorepo with specialized packages:
36+
37+
- **@lytics/dev-agent-core** — Repository scanning, vector storage, GitHub integration
38+
- **@lytics/dev-agent-cli** — Command-line interface
39+
- **@lytics/dev-agent-mcp** — MCP server with tool adapters
40+
- **@lytics/dev-agent-subagents** — Specialized agents (planner, explorer, PR manager)
41+
42+
## Next Steps
43+
44+
- [Installation →](/docs/install) — Get dev-agent installed in under 2 minutes
45+
- [Quickstart →](/docs/quickstart) — From zero to semantic search in 5 minutes
46+

0 commit comments

Comments
 (0)