Skip to content

Add markdown documentation files to root #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
livefire2015 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add markdown documentation files to root #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b3f4200
docs: Add project documentation markdown files
claude Nov 18, 2025
f705701
docs: Add comprehensive v0, v1, v2 coverage to all markdown files
claude Nov 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# CLAUDE.md

**solid-ag-chat** is a SolidJS library for building chat UIs with AG-UI protocol support and bidirectional tool execution. This is a library (not a ready-to-use UI), providing primitives and hooks for developers to build custom chat interfaces.

## Development Setup

The project contains three versions in separate directories:

```bash
# v2 (Current - Recommended)
cd v2 && npm run dev # Watch mode
cd v2 && npm run build # Production build

# v1 (Previous)
cd v1 && npm run dev
cd v1 && npm run build

# v0 (Deprecated)
cd v0 && npm run dev
cd v0 && npm run build
```

## Architecture Highlights

Each version has its own architecture:

- **v2**: Exports through `v2/src/index.ts`, primitives in `v2/src/primitives/`, state in `v2/src/store/`
- **v1**: Exports through `v1/src/index.ts`, similar structure to v2 but without tool execution
- **v0**: Exports through `v0/src/index.tsx`, includes built-in UI components

All versions build to ES module and CommonJS formats with peer dependencies on solid-js.

## Version Structure

- **v2 (Current):** Bidirectional tool execution with automatic handler invocation
- **v1 (Previous):** Official AG-UI protocol support
- **v0 (Deprecated):** Legacy version with built-in UI components

## State Management & Key Features

The library provides hooks like `useConversation`, `useMessages`, `useToolCalls`, and `useToolExecution` for managing chat state through SolidJS signals and stores. V2 adds tool registration, execution state tracking, and human-in-the-loop patterns.

## Integration & Workflows

The backend expects POST requests with conversation history and returns streaming responses via Server-Sent Events following the AG-UI protocol. For active development across library and consuming apps, the recommended approach uses `npm run dev` (watch mode) alongside `npm link` for local testing without npm publication.

## Key Dependencies

- **@ag-ui/core** & **@ag-ui/client** - Official AG-UI protocol
- **RxJS** - Reactive streams
- **fast-json-patch** - JSON Patch for state deltas
- **solid-js** (peer) - Reactive UI framework
Loading